michael-denyer/pstack-claude

principle-fix-root-causes

Apply when debugging.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/michael-denyer/pstack-claude --skill principle-fix-root-causes

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Fix Root Causes

When debugging, fix the fault, not the place where it surfaced. The symptom is where a wrong state became visible. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle.

Why: A symptom fix hides the evidence and leaves the fault free to surface somewhere else. Each one makes the system harder to reason about, because the code now carries a workaround for a bug that nobody named.

Pattern:

  • Reproduce first.
  • Ask "why" at each step until the answer is a wrong decision in the code, not a consequence of an earlier one.
  • When stuck, instrument. Read the actual error and the actual state. Do not guess.
  • Ask whether the state that triggered the symptom is legitimate. If the system may be in that state, the code that broke on it is the root cause, and handling the state there is the fix. If the state should never exist, a check where it broke hides the bug. Find what produced the state. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
  • When something fails only after a restart, suspect persisted state first: config files, caches, lock files, serialized state.
  • Check for the pattern, not just the instance. Find every place with the same fault and fix them all.
  • If a workaround needs a paragraph-long comment to justify it, the code is wrong. Fix the code, not the comment.
  • If the deciding fact took a deep dig to find, propose the cheap, always-on signal that would have shown it at first look.

Related by task

from this repository

More skills

All skills
michael-denyer
Community

architect

Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape.

1h installs
1
GitHub stars
4K
Updated
Nov 4
michael-denyer
Community

babysit

Watch an open PR — fix failing CI, handle the straightforward review comments, and drive it to a mergeable state. Claude Code analog of Cursor's built-in /babysit. Use after opening a PR when the user wants the agent to shepherd it without re-prompting.

1h installs
1
GitHub stars
4K
Updated
Nov 4
michael-denyer
Community

benchmark-checklist

Vet a perf measurement (limiter, tuning, limits, errors, repeatability, relevance, and whether the work happened) before you report or act on it. Use when you run a benchmark or report a speedup or regression you measured.

1h installs
1
GitHub stars
4K
Updated
Nov 4
michael-denyer
Community

blast-radius

Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', reviewing a small diff you don't trust, or a brief that asserts something about existing code ('make X public', 'X already handles Y') before you design against that assertion.

1h installs
1
GitHub stars
4K
Updated
Nov 4