Claude Skill

diagnose

For a bug-fix brief, a bug resisting its first fix, or a fix about to ship without a proven cause, reproduce the failure, state its cause with evidence, and keep a regression check before shipping.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download timharris707-skills-plugins_clickai-codex_skills_run_diagnose-b6a29f5.zip · 3 KB

Install

skills CLI npx skills add https://github.com/timharris707/skills/tree/main/plugins/clickai-codex/skills/run/diagnose
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install timharris707-skills@llmmart
Git git clone https://github.com/timharris707/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole timharris707/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Diagnose

Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.

A fix may not ship without a named cause: one plain sentence stating what was wrong, backed by evidence, readable by a non-engineer decider. This skill is the discipline a working lane follows inline when fixing bugs. It is not a lane type of its own, and it deliberately has no binding slots: everything repo-specific already arrived in the lane's brief.

The named-cause test is the trigger, and it binds on every fix. If you can already state the cause in one sentence and point at the evidence, the loop is satisfied: ship. If you cannot, the loop runs, however small the bug looks. "Hard bugs only" is the wrong gate, because the first fix attempt is where the vibes-fix ships: a change that makes the symptom go away for reasons nobody can state.

The loop

Six steps, in order. A failed fix re-enters at the step whose output it disproved, usually the hypothesis list, sometimes the repro itself.

  1. Reproduce red. Write a failing automated test that catches the user's exact symptom, before any fix attempt; it is the loop you iterate against now and the regression test you keep after. Where test infra genuinely cannot reach the bug (timing, a third-party boundary), the recorded fallback is a documented manual repro with exact steps, flagged as a fallback at close-out, never silently substituted.
  2. Minimize proportionately. Shrink the repro until it is tight, fast and deterministic enough to iterate against, cutting one element at a time and re-running after each cut. Tight is the purpose and the stopping point: a two-second deterministic loop is the tool; shrinking past it is polishing the repro instead of finding the cause. Non-deterministic bugs minimize toward a reproduction rate high enough to debug against.
  3. Hypothesize falsifiably. Generate several ranked hypotheses before testing any: a single hypothesis anchors on the first plausible idea. Each is stated so evidence could kill it, skeptic-style: "if X is the cause, then changing Y makes the bug disappear." A hypothesis with no prediction is a vibe; sharpen it or discard it.
  4. Instrument. Evidence gathering precedes any fix attempt. Each probe maps to one hypothesis's prediction, changing one variable at a time: a breakpoint beats ten logs, targeted logs beat logging everything and grepping. Tag every debug probe with one unique prefix so cleanup is a single grep. When a check fails, suspect the observation method before the system: indirect evidence (mtimes, cached screenshots, self-reports) feels cheaper than direct observation and lies more often.
  5. Fix. Only against the hypothesis the instrumentation confirmed. Watch the red test go green.
  6. Regression-test. Re-run the original, un-minimized repro; keep the failing test from step 1 in the suite as the regression test; grep the probe tag out. Then write the closing artifact.

Across all six steps, redact secrets: every secret in a command, an output, or a captured artifact the lane shows is replaced with <REDACTED>. Feedback loops read credentials from environment variables, so a credential never appears in the loop itself. Quote only the lines of an artifact that carry the signal. When the evidence needs an artifact the user holds (a log dump, a captured request), ask for a redacted copy.

The closing artifact

Two things, and close-out audits check for both:

  • The named cause: one plain sentence a non-engineer decider reads without translation ("the cache key omitted the locale, so two languages shared one entry"), with the evidence that confirmed it.
  • The regression test: the step-1 test, now green in the suite; or the recorded manual-repro fallback with its exact steps, flagged as a fallback.

An unnamed cause is not done, whatever the symptom is doing.

Structural causes feed the friction gate

Sometimes the named cause says the bug is a symptom: a missing seam, a rule duplicated in N places and updated in N−1. The lane still fixes the instance under this skill's own bar, then reports the structural cause as friction, codebase-review's third entry gate, in its close-out summary. The diagnosing lane never expands its own scope to fix the structure: that is a review-and-disposition matter, decided with more information than the lane has.

Where it sits in the pack

  • Lane briefs: orchestrate points bug-shaped items here, so the discipline arrives with the work.
  • Mid-build bugs: implement routes a bug surfacing mid-build here; the named-cause test binds before the lane resumes building.
  • Close-out audit: the orchestrator's audit checks the two closing artifacts on every bug fix; the named cause is what it reads first.
  • Domain memory: where the repo binds domain-memory, a root cause that reveals a standing fact (an assumption the repo held that the bug just proved wrong) is offered to it as a fact record (open and read the domain-memory skill's SKILL.md completely to draft it): the same correction class as a decider correcting a session, with reality as the corrector.
  • Deliberately not hooked: handoff GOTCHAS. The durable copy of a diagnosis's lesson is the domain-memory record; writing it into handoff GOTCHAS too would be the same meaning in two places.

Done when (checkable: verify each line before reporting complete)

  • The cause is stated in one plain sentence with its confirming evidence, readable by a non-engineer decider, or no fix shipped.
  • A failing automated test existed before the fix, caught the user's exact symptom, passes after, and stays in the suite as the regression test; where one genuinely could not reach the bug, the recorded manual repro carries exact steps and is flagged as the fallback at close-out.
  • The repro was minimized until tight, fast and deterministic enough to iterate against, and no further.
  • Every hypothesis tested carried a falsifiable prediction, and the fix answers the hypothesis the instrumentation confirmed, not a hunch that survived by making the symptom vanish.
  • The original un-minimized repro no longer reproduces, and a grep of the probe tag comes back empty.
  • No secret appears in anything the lane showed: each is <REDACTED> or an environment-variable reference.
  • A structural cause, where the diagnosis revealed one, is reported as friction toward codebase-review's entry gate, with the instance fixed and the lane's scope unexpanded.
  • Where the repo binds domain-memory: a standing fact revealed by the root cause was offered as a record, or there was none.

Attribution

Adapted from Matt Pocock's diagnosing-bugs (MIT). The six-step spine is his: build a tight feedback loop and watch it go red, minimize by cutting one element at a time, generate ranked falsifiable hypotheses each stating its prediction (his format and several of these phrasings, near-verbatim), instrument one variable at a time with tagged probes rather than logging everything, write the regression test before the fix and re-run the original repro after, and state the confirmed cause so the next debugger learns. So are tight as the loop's quality bar, the reproduction-rate framing for flaky bugs, and the post-mortem handoff of architectural causes to his improve-codebase-architecture, the seed of the friction-gate escalation here. The redaction paragraph is adapted from the Redact section he added later.

What this pack changes: the named-cause test as the binding trigger (any fix shipping without a nameable cause, not hard bugs only), the failing-automated-test-first bar with the documented manual repro as a recorded, flagged fallback, proportionate minimize (tight enough to iterate against is the stopping point, not load-bearing minimality for its own sake), the plain-sentence closing artifact audited at lane close-out, the domain-memory feed for standing facts, and the friction-gate rewiring into codebase-review's entry gate with the diagnosing lane's scope pinned.

One line in step 4 (suspect the observation method before the system) is adapted from Lauren Tan's principle-prove-it-works (MIT).

Files (skills)
  • agents
    • openai.yaml 132 B
      Loading…
  • SKILL.md 8.6 KB
    ---
    name: diagnose
    description: "For a bug-fix brief, a bug resisting its first fix, or a fix about to ship without a proven cause, reproduce the failure, state its cause with evidence, and keep a regression check before shipping."
    ---
    
    # Diagnose
    
    Read the [Codex desktop binding](../../../CODEX.md) when this workflow needs harness mechanics, model routing, or recovery.
    
    A fix may not ship without a **named cause**: one plain sentence stating what was wrong, backed by evidence, readable by a non-engineer decider. This skill is the discipline a working lane follows inline when fixing bugs. It is not a lane type of its own, and it deliberately has no binding slots: everything repo-specific already arrived in the lane's brief.
    
    **The named-cause test is the trigger, and it binds on every fix.** If you can already state the cause in one sentence and point at the evidence, the loop is satisfied: ship. If you cannot, the loop runs, however small the bug looks. "Hard bugs only" is the wrong gate, because the first fix attempt is where the vibes-fix ships: a change that makes the symptom go away for reasons nobody can state.
    
    ## The loop
    
    Six steps, in order. A failed fix re-enters at the step whose output it disproved, usually the hypothesis list, sometimes the repro itself.
    
    1. **Reproduce red.** Write a failing automated test that catches the user's exact symptom, **before any fix attempt**; it is the loop you iterate against now and the regression test you keep after. Where test infra genuinely cannot reach the bug (timing, a third-party boundary), the recorded fallback is a documented manual repro with exact steps, flagged as a fallback at close-out, never silently substituted.
    2. **Minimize proportionately.** Shrink the repro until it is **tight**, fast and deterministic enough to iterate against, cutting one element at a time and re-running after each cut. Tight is the purpose and the stopping point: a two-second deterministic loop is the tool; shrinking past it is polishing the repro instead of finding the cause. Non-deterministic bugs minimize toward a reproduction *rate* high enough to debug against.
    3. **Hypothesize falsifiably.** Generate several ranked hypotheses before testing any: a single hypothesis anchors on the first plausible idea. Each is stated so evidence could kill it, skeptic-style: "if X is the cause, then changing Y makes the bug disappear." A hypothesis with no prediction is a vibe; sharpen it or discard it.
    4. **Instrument.** Evidence gathering precedes any fix attempt. Each probe maps to one hypothesis's prediction, changing one variable at a time: a breakpoint beats ten logs, targeted logs beat logging everything and grepping. Tag every debug probe with one unique prefix so cleanup is a single grep. When a check fails, suspect the observation method before the system: indirect evidence (mtimes, cached screenshots, self-reports) feels cheaper than direct observation and lies more often.
    5. **Fix.** Only against the hypothesis the instrumentation confirmed. Watch the red test go green.
    6. **Regression-test.** Re-run the original, un-minimized repro; keep the failing test from step 1 in the suite as the regression test; grep the probe tag out. Then write the closing artifact.
    
    Across all six steps, **redact secrets**: every secret in a command, an output, or a captured artifact the lane shows is replaced with `<REDACTED>`. Feedback loops read credentials from environment variables, so a credential never appears in the loop itself. Quote only the lines of an artifact that carry the signal. When the evidence needs an artifact the user holds (a log dump, a captured request), ask for a redacted copy.
    
    ## The closing artifact
    
    Two things, and close-out audits check for both:
    
    - **The named cause**: one plain sentence a non-engineer decider reads without translation ("the cache key omitted the locale, so two languages shared one entry"), with the evidence that confirmed it.
    - **The regression test**: the step-1 test, now green in the suite; or the recorded manual-repro fallback with its exact steps, flagged as a fallback.
    
    An unnamed cause is not done, whatever the symptom is doing.
    
    ## Structural causes feed the friction gate
    
    Sometimes the named cause says the bug is a **symptom**: a missing seam, a rule duplicated in N places and updated in N−1. The lane still fixes the instance under this skill's own bar, then reports the structural cause as **friction**, [codebase-review](../../investigate/codebase-review/SKILL.md)'s third entry gate, in its close-out summary. The diagnosing lane never expands its own scope to fix the structure: that is a review-and-disposition matter, decided with more information than the lane has.
    
    ## Where it sits in the pack
    
    - **Lane briefs**: [orchestrate](../orchestrate/SKILL.md) points bug-shaped items here, so the discipline arrives with the work.
    - **Mid-build bugs**: [implement](../implement/SKILL.md) routes a bug surfacing mid-build here; the named-cause test binds before the lane resumes building.
    - **Close-out audit**: the orchestrator's audit checks the two closing artifacts on every bug fix; the named cause is what it reads first.
    - **Domain memory**: where the repo binds [domain-memory](../../orient/domain-memory/SKILL.md), a root cause that reveals a **standing fact** (an assumption the repo held that the bug just proved wrong) is offered to it as a fact record (open and read the `domain-memory` skill's SKILL.md completely to draft it): the same correction class as a decider correcting a session, with reality as the corrector.
    - **Deliberately not hooked: handoff GOTCHAS.** The durable copy of a diagnosis's lesson is the domain-memory record; writing it into [handoff](../handoff/SKILL.md) GOTCHAS too would be the same meaning in two places.
    
    ## Done when (checkable: verify each line before reporting complete)
    
    - The cause is stated in one plain sentence with its confirming evidence, readable by a non-engineer decider, or no fix shipped.
    - A failing automated test existed before the fix, caught the user's exact symptom, passes after, and stays in the suite as the regression test; where one genuinely could not reach the bug, the recorded manual repro carries exact steps and is flagged as the fallback at close-out.
    - The repro was minimized until tight, fast and deterministic enough to iterate against, and no further.
    - Every hypothesis tested carried a falsifiable prediction, and the fix answers the hypothesis the instrumentation confirmed, not a hunch that survived by making the symptom vanish.
    - The original un-minimized repro no longer reproduces, and a grep of the probe tag comes back empty.
    - No secret appears in anything the lane showed: each is `<REDACTED>` or an environment-variable reference.
    - A structural cause, where the diagnosis revealed one, is reported as friction toward codebase-review's entry gate, with the instance fixed and the lane's scope unexpanded.
    - Where the repo binds domain-memory: a standing fact revealed by the root cause was offered as a record, or there was none.
    
    ## Attribution
    
    Adapted from Matt Pocock's [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs) (MIT). The six-step spine is his: build a tight feedback loop and watch it go red, minimize by cutting one element at a time, generate ranked falsifiable hypotheses each stating its prediction (his format and several of these phrasings, near-verbatim), instrument one variable at a time with tagged probes rather than logging everything, write the regression test before the fix and re-run the original repro after, and state the confirmed cause so the next debugger learns. So are *tight* as the loop's quality bar, the reproduction-rate framing for flaky bugs, and the post-mortem handoff of architectural causes to his `improve-codebase-architecture`, the seed of the friction-gate escalation here. The redaction paragraph is adapted from the `Redact` section he added later.
    
    What this pack changes: the named-cause test as the binding trigger (any fix shipping without a nameable cause, not hard bugs only), the failing-automated-test-first bar with the documented manual repro as a recorded, flagged fallback, proportionate minimize (tight enough to iterate against is the stopping point, not load-bearing minimality for its own sake), the plain-sentence closing artifact audited at lane close-out, the domain-memory feed for standing facts, and the friction-gate rewiring into codebase-review's entry gate with the diagnosing lane's scope pinned.
    
    One line in step 4 (suspect the observation method before the system) is adapted from Lauren Tan's [`principle-prove-it-works`](https://github.com/cursor/plugins/tree/main/pstack/skills/principle-prove-it-works) (MIT).
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.