diagnose

Context

Receives:

• Dispatch summary from yo (issue description, tier assignment)
• Explorer findings (if std/deep tier)
• User input describing the problem

Reads:

• Source code relevant to reported issue
• Test output, browser console, logs as applicable
• wiki/extensions/diagnose.md for extension investigation agents

Produces:

• wiki/diagnoses/<slug>.md (see references/diagnose-template.md)

Procedure

1. Reproduce

Confirm the issue exists. Pick the fastest path:

• Test: run relevant test suite, read output, find failure
• Browser: navigate to reported location, observe behavior
• Manual: execute reported steps, compare actual vs expected
• Logs: search logs/error output for reported symptoms

If cannot reproduce after 2 attempts with different approaches, state clearly and ask user for more context.

2. Classify

Classification	Definition	Next action
Real bug	Code behaves contrary to intent	Continue to step 3
Environmental	Works in code, fails in env (deps, config, OS)	State finding, ask user
User error	Misuse of API/feature	State correct usage, done
Works as designed	Behavior is intentional	Explain design rationale, done
Incomplete info	Cannot determine	Ask user for specifics

3. Quick hypothesis

Form directional hypothesis -- not committed, just a starting point.

• State what you think the root cause is
• State confidence (high/medium/low)
• State what would confirm or refute it

4. Assess severity

Severity	Definition
Blocking	Feature unusable, no workaround, data loss risk
Degraded	Feature partially works or has workaround
Cosmetic	Visual/UX issue, functionality intact

5. Dispatch extensions

If wiki/extensions/diagnose.md exists, dispatch investigation agents defined there. Wait for all extension findings before proceeding — steps 6 and 7 depend on the complete picture (extension findings may change classification, severity, or routing decision).

6. Write diagnosis artifact

Gate: ARTIFACT-BEFORE-HANDOFF -- persist to disk before routing.

Write to wiki/diagnoses/<slug>.md using references/diagnose-template.md. Slug was generated by yo. Always write, even for non-bugs -- "not a bug" is a valuable data point.

7. Route

Condition	Route
Not a bug (env/user error/WAD)	Done -- explain to user
Real bug, single file, obvious fix	Craft (lightweight)
Real bug, std/deep complexity	Sketch (std/deep)

8. Upgrade heuristic

Propose upgrade from lightweight to std/deep if any:

• Fix touches 3+ files
• Fix spans 2+ subsystems
• Root cause unclear after initial investigation
• Reproduction reveals deeper systemic issue

User confirms before proceeding.

Output

Produces: wiki/diagnoses/<slug>.md Passes to: done | craft (lightweight) | sketch (std/deep)

References

• references/diagnose-template.md -- YAML frontmatter schema, section template
• yo/references/agent-dispatch.md -- how to compose Agent tool calls (for extension dispatch)

Gotchas

• Hypothesis is directional, not a commitment. Do not tunnel-vision on first guess.
• Upgrade heuristic is a proposal, not automatic. User must confirm tier change.
• Extension agents from wiki/extensions/diagnose.md are optional -- skip gracefully.
• If reproduction requires destructive action (DB reset, cache clear), warn user first.
• Symptom is not cause. "API returns 500" is a symptom -- push past it.
• Extension findings must complete before writing the artifact or routing. An extension agent may reclassify the bug or change the severity — writing the artifact too early captures an incomplete picture.

Rationalization Red Flags

If you catch yourself thinking any of these, STOP and follow the diagnose procedure:

1. "I can see the bug, skip reproduction" — reproduction confirms you're fixing the right thing. Visual inspection misses environmental and state-dependent triggers.
2. "It's obviously a real bug" — classify anyway. Environmental issues and user error waste entire fix cycles when misidentified.
3. "I know the root cause already" — state your hypothesis with confidence level. Tunnel vision on the first guess is the #1 cause of wrong fixes.
4. "This is minor, skip the artifact" — every diagnosis is a data point for /propose. Without it, the framework can't detect systemic patterns.
5. "Let me just fix it while I'm here" — diagnose routes to craft. Merging investigation and fix skips the severity assessment and tier decision.
6. "Reproduction would take too long" — 2 attempts with different approaches. If it still fails, ask for context — don't skip and guess.