Debugging Cycle

Use this skill for requests like debug flaky completion test, investigate parser crash on unterminated regex, diagnose lexer ordering regression, or find root cause of duplicate annotations.

Inputs: a bug/failure/flaky behavior/regression/diagnostic scope in $ARGUMENTS; relevant code, tests, generated sources, logs; optional severity/issue/package/path hints.

Artifact location (graceful degradation)

• If .specify/ exists, use .specify/debug/<case-slug>/debug-report.md.
• Otherwise, use docs/debug/<case-slug>/debug-report.md.
• <case-slug> uses YYYY-MM-DD-short-kebab-summary, preferring an issue-number prefix.

Rules:

• First deliverable is always the debug report, not an immediate fix.
• The debug report is a pre-spec evidence artifact; it does not replace a canonical spec.md.
• Do not propose or implement fixes until the report has concrete evidence, a best hypothesis, and a recommended follow-up path.
• Ground every factual claim in repo/runtime evidence; label uncertain claims as hypothesis or unknown. Verify Phel/grammar facts against api.json, .flex/.bnf, and src/main/gen/ — never memory.
• If scope crosses 3+ files, 2+ packages, or needs end-to-end tracing, run /workflow.team-run analysis <scope> before finalizing.

Workflow:

1. Resolve the debug case:
   • Reuse the current case directory when resuming the same active diagnosis.
   • Otherwise create the case directory at the resolved artifact home.
   • Load debug-report-template.md before writing or updating debug-report.md.
2. Triage and scoping:
   • Capture current symptom, impact, severity, suspected surface, and any safe containment step.
   • Decide whether the case is likely restore-fix, spec-required, or investigation-only; this can stay provisional until more evidence exists.
3. Investigation:
   • Reproduce or explicitly document why reproduction is not yet possible. Prefer a focused test: ./gradlew test --tests "<FullyQualifiedTest>".
   • Read errors fully, compare recent changes (git log/git diff), trace data flow, and gather evidence at component boundaries (lexer → parser → PSI → annotator/completion/inspection).
   • For grammar issues, inspect the actual generated output in src/main/gen/ and the rule ordering in Phel.flex/Phel.bnf.
   • For IDE-runtime issues, check the sandbox log (./gradlew runIde) and watch for swallowed ProcessCanceledException or EDT violations.
   • When the surface is broad, run /workflow.team-run analysis <scope> and merge that evidence into the report.
4. Diagnosis synthesis:
   • Update debug-report.md with evidence, current best root-cause hypothesis, known unknowns, and the smallest next validating step.
   • Set Resolution class to one of:
     • restore-fix — a narrow repair that restores already-intended behavior without changing product or interface intent
     • spec-required — the permanent fix changes intended behavior, a token/PSI/grammar contract, or another spec-level decision
     • investigation-only — more evidence is needed before either path is safe
5. Review gate:
   • Stop and summarize the diagnosis, evidence quality, and resolution class.
   • End with: Debug report ready. Reply with "approve debug report" to continue or tell me what to change.
6. Post-approval routing:
   • restore-fix → continue as a narrow bugfix in the implementation workflow, keeping the debug report as the source of truth for scope and verification.
   • spec-required → create or update a dedicated feature spec for the permanent change and continue through spec → plan → tasks → implementation.
   • investigation-only → continue investigation rather than guessing.
7. Completion:
   • Leave the repo with an updated debug-report.md.
   • Summarize the evidence used, the current diagnosis confidence, the chosen resolution class, and the exact next workflow step.