proofline
TR

debug-proof

Purpose

Debugs a failure with proof instead of guesses.

Source Skill purpose

When to use it

Use debug-proof for a reported bug, test failure, crash or build error that needs a demonstrated cause. It starts with a repeatable reproduction and several falsifiable hypotheses, then narrows by experiments or a known-good revision. A root cause is proved by changing only the suspected cause and seeing the failure flip. The fix is small and gets a regression test that fails before and passes after. Each experiment and result stays in a ledger, so the report distinguishes proof from a guess.

The experiment ledger records each controlled change, command, observation and effect on the ranked hypotheses. Instrumentation and revision bisection stay in isolated worktrees.

Source Skill purpose

How it works

Steps of the skill, in source orderEach numbered step follows the skill definition and links to its source.1. Take the symptomFlow2. Reproduce twiceFlow3. Rank hypothesesFlow4. Narrow the causeFlow5. Prove the flipFlow6. Fix minimallyFlow7. Add regression coverageFlow8. Validate evidenceFlow9. Clean worktreesFlow10. Report the proofFlow
Steps of the skill, in source order

Source Flow

  1. Take the symptom Read expected behavior, observed failure and any known-good revision.

    Source Flow

  2. Reproduce twice Run a command that fails for the reported reason and save its output.

    Source Flow

  3. Rank hypotheses Write at least two explanations with observations that could disprove each.

    Source Flow

  4. Narrow the cause Use focused logging, input bisection or revision bisection in an isolated worktree.

    Source Flow

  5. Prove the flip Change only the suspected cause and show the reproduction changes outcome.

    Source Flow

  6. Fix minimally Inspect callers and repair the shared cause with the smallest in-scope change.

    Source Flow

  7. Add regression coverage Keep a test that fails before the fix for the correct assertion and passes after.

    Source Flow

  8. Validate evidence Run the debug validator and required project checks for the result.

    Source Flow

  9. Clean worktrees Remove recorded experiment worktrees and check the user's tree state.

    Source Flow

  10. Report the proof State symptom, cause, flip experiment, fix and regression result in one report.

    Source Flow

Key rules

  • Reproduce the reported failure before changing code.

    Source Hard rules

  • Rank multiple hypotheses and state how each could be refuted.

    Source Hard rules

  • Record every experiment, command and observed result in the ledger.

    Source Hard rules

  • Prove the cause by a one-variable experiment that flips the failure.

    Source Hard rules

  • Keep a regression assertion that fails before and passes after the fix.

    Source Hard rules

Output and gate

Output

The skill definition states no output.

Source Skill definition

Gate

  • Completion requires a validated fixed result with both cause proof and regression evidence.

    Source Gate rule

Source

Source Skill definition

← All skills