Imported from akillness/jeo-skills (.agent-skills/diagnose/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill diagnose. Copyright stays with the author.

Diagnose

A six-phase loop for systematic bug investigation. The key insight: invest disproportionate effort in Phase 1. With a reliable feedback loop, phases 2–6 become mechanical.

When to use this skill

• Hard bugs that resist quick fixes
• Performance regressions with unclear root cause
• Flaky failures that need repeated-run evidence
• Any failure where previous fix attempts failed

When not to use this skill

• Quick targeted fixes with obvious root cause → use debugging
• Symptom-first log triage → use log-analysis
• Broad test-policy design → use testing-strategies

The Six Phases

Phase 1 — Build a feedback loop (invest here first)

Create a fast, deterministic, automated pass/fail signal for the bug.

Goal: < 10 second feedback cycle
Signal: automated pass/fail, not manual inspection
Determinism: same input → same result every time

Ask yourself: "Can I run one command and know within 10 seconds if the bug is present?"

• Write a failing test if one doesn't exist
• Create a minimal reproduction script
• Isolate the trigger to the smallest possible input
• Make the failure obvious and observable

Do not proceed to Phase 2 until the feedback loop is reliable.

Phase 2 — Reproduce

Confirm the failure is reproducible under controlled conditions.

• Run the feedback loop multiple times to confirm determinism
• Document exact inputs, environment, and steps
• Identify if this is new behavior (regression) or always-broken

Phase 3 — Hypothesize

Form ranked hypotheses about root cause.

• List 2–4 candidate causes ordered by likelihood
• Each hypothesis must be falsifiable
• Start with the most likely, not the most interesting

H1 (most likely): [specific cause]
H2: [alternative cause]
H3: [edge case cause]

Phase 4 — Instrument

Run one discriminating check per hypothesis.

• Add logging, assertions, or breakpoints at the narrowest useful point
• Use the feedback loop to test each hypothesis quickly
• Record evidence: confirmed / refuted / inconclusive
• Move to the next hypothesis when one is refuted

Phase 5 — Fix and test

Apply the fix and verify it closes the loop.

• Write the regression test before the fix (if possible)
• Apply the minimal change that addresses root cause
• Run the full test suite, not just the target test
• Confirm the feedback loop now passes

Phase 6 — Cleanup and post-mortem

• Remove diagnostic instrumentation
• Document what the root cause was and why it was surprising
• Identify if similar patterns exist elsewhere in the codebase
• Consider whether a preventive check (lint rule, test, assertion) would catch this class of bug automatically

Quick reference

# Phase 1: make the feedback loop
# Write a failing test or minimal repro script

# Phase 4: instrument at the narrowest point
console.error('[diagnose] value at boundary:', value)

# Phase 5: verify fix closes the loop
npm test -- --testPathPattern=failing-test

Instructions

1. Identify the task trigger and expected output.
2. Follow the workflow steps in this skill from top to bottom.
3. Validate outputs before moving to the next step.
4. Capture blockers and fallback path if any step fails.

Examples

• Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

• Keep outputs deterministic and auditable.
• Prefer small reversible changes over broad risky edits.
• Record assumptions explicitly.

References

• Project standards: .agent-skills/skill-standardization/SKILL.md
• Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh