systematic-debugging

name	systematic-debugging
description	Trigger only when an observed failure, reproducible bug, regression, stack trace, failing test, or merge conflict requires evidence-based root-cause diagnosis before applying or recommending a fix.
requires	[]

systematic-debugging — Evidence-First Root Cause Skill

1. Trigger Boundary

Use this skill only for a concrete failure signal:

• Reproducible bug or regression.
• Failing test, stack trace, crash, or error log.
• Incorrect runtime behavior with an expected behavior to compare against.
• Merge conflict or integration failure requiring root-cause reasoning.

Do not use this skill for general review, planned feature work, or post-implementation verification unless a failure must be diagnosed.

2. Non-Negotiable Constraints

• Reproduce or explain non-reproduction. Do not diagnose until reproduction has been attempted or the missing reproduction blocker is recorded.
• Evidence before fix. Every root-cause claim must cite observed evidence: command output, log excerpt, code path, test failure, or file location.
• Root cause over symptom. A symptom description is not a root cause.
• Smallest safe fix. Apply or recommend the minimum change that addresses the verified cause.
• Verification is mandatory. A fix is incomplete until the original failure signal is rechecked.

3. Debugging State Machine

State A — Capture Failure

Record:

• Symptom.
• Expected behavior.
• Actual behavior.
• Reproduction command or steps.
• Logs, stack traces, failing tests, or recent changes.

State B — Reproduce

Run or reason through the reproduction path. If reproduction cannot be run, mark the blocker and continue only with explicit uncertainty.

State C — Localize

Trace from failure signal to responsible code path:

1. Identify the failing boundary.
2. Follow data/control flow.
3. Compare intended behavior with actual behavior.
4. Isolate the smallest responsible condition.

State D — Fix

Apply or propose a fix only after evidence supports the diagnosis. Keep changes scoped to the root cause.

State E — Verify

Re-run the original reproduction and relevant regression checks. Report exact pass/fail evidence.

4. Negative Prompts

• Never guess a root cause without evidence.
• Never modify code before reproduction or evidence collection unless the user explicitly asks for speculative patching.
• Never call a workaround the root cause.
• Never hide failed or skipped verification.
• Never broaden the task into unrelated refactors.
• Never output “fixed” when the original failure was not rechecked.

5. Final Output Format

status: fixed | diagnosed | blocked | unresolved
symptom: string
reproduction:
  attempted: boolean
  commandOrSteps: string
  result: passed | failed | blocked | not-run
evidence:
  - source: string
    detail: string
rootCause: string
fix:
  applied: boolean
  summary: string
  filesChanged: string[]
verification:
  attempted: boolean
  commands: string[]
  passed: boolean
  failedChecks: string[]
blockedReason: string | null
nextAction: none | gather-more-evidence | apply-fix | ask-user | escalate