Troubleshoot

Skill AndrewTtofi/spine/skills/troubleshoot

Use when something is broken — a failing test, a bug, an error, behavior that regressed. Drives a disciplined investigate → reproduce → root-cause → fix loop, checks the Spine for prior art, and records the root cause so the failure mode isn't repeated. Iron law — no fix without a confirmed root cause.From its SKILL.md

Install

npx -y skills add AndrewTtofi/spine --skill troubleshoot

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.2 KB, as published. Nobody here has run it

troubleshoot — root cause, not symptom

The fast fix that doesn't understand the bug just moves it. This skill refuses to patch a symptom until the root cause is proven, and writes the lesson back so the next session doesn't relearn it.

Steps

Read the Spine. Load context.md (architecture + language), conventions.md (test/debug commands), and decisions/ — has this surface bitten us before? A prior ADR may already hold the answer.
Reproduce first. Get a reliable, minimal repro. If you can't reproduce it, you can't confirm a fix — gather more evidence before guessing.
Investigate. Follow the evidence: read the failing path, logs, recent diffs, and state. Narrow the surface methodically. No speculative edits.
Hypothesize. State a single falsifiable hypothesis about the root cause, then confirm it with evidence before changing anything. Iron law: no fix without a confirmed root cause.
Pin it with a test. Write a failing test that reproduces the bug (RED). This is the proof of the cause and the guard against regression.
Fix at the root. Make the minimal change that addresses the cause, not the symptom. Confirm the test goes GREEN and the original repro is gone.
Record in the Spine. Write the root cause and fix to journal.md. If the failure mode is a durable lesson, add an ADR in .spine/decisions/NNNN-title.md so it's remembered. Hand off to verify to confirm against criteria.

Spine I/O

Reads: context.md, conventions.md, decisions/ (prior art), journal.md.
Writes: journal.md (root cause + fix), decisions/ (ADR for durable lessons).

Notes

Reproduce before you fix; a fix you can't see fail is a fix you can't trust.
Check decisions/ early — the cheapest debugging is the bug you already solved.
The regression test is non-negotiable: without it, the bug comes back.