systematic-debugging · v1.0.0 · 2026-09-25 · sha256 a869f2f7c1f6f1a7
systematic-debugging v1.0.0A
Immutable. This exact content never changes and is served at /api/v1/blob/a869f2f7c1f6f1a7.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_4wdnx3duivbspl5s/a869f2f7c1f6f1a7bf04669dd7fe4bcf20c43b6b5009dde2ccffc982ca0b9c39.json
Then /plugin install systematic-debugging@markdownregistry-4wdnx3duivbspl5s in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: systematic-debugging
description: Four-phase root-cause investigation — Investigate → Analyze → Hypothesize → Verify → Implement. No fix lands without a confirmed root cause and a regression test that would have caught the original failure.
version: 1.0.0
author: ethosagent
tags: [coding, debugging, quality]
required_tools: [read_file, terminal, search_files]
ethos:
category: quality-and-testing
default_personalities: [engineer, reviewer]
prerequisites:
external_cli: []
auth: []
env_vars: []
optional_tools: [process, write_file, patch_file]
integrates_with:
- tool: process
role: tail logs while iterating without blocking the chat
- tool: write_file
role: persist the investigation log under the workspace's .ethos-work/investigations/
surface_metadata:
invocation_trigger: "user reports a bug, regression, or unexpected behaviour; agent self-invokes when a terminal command unexpectedly fails"
estimated_turns: "5-20 (investigations vary widely in length)"
---
# Systematic Debugging
Investigation discipline. The fix is the *last* step, not the first.
## When to use this skill
- The user reported a bug, error, regression, or "X was working yesterday".
- A `terminal` command unexpectedly failed and the cause is not immediately obvious.
- The user said "debug this" / "why is X broken" / "track this down".
When the cause is obvious from a one-line error message and a one-line fix exists, do not invoke the full procedure — just fix it. Reserve this skill for problems where the root cause is unclear.
## The four phases
### 1. Investigate — gather evidence
Collect, do not theorize:
- The exact error message and stack trace, copied verbatim.
- Recent changes: `git log --since="1 week" --oneline`, `git diff <last-known-good>...HEAD`.
- Related files: search for the failing identifier with `search_files`.
- Environment: relevant env vars, library versions, OS specifics.
- Reproduction: what minimal input triggers it? Capture the smallest repro.
Write all of this down — into the conversation or, for longer investigations, into `.ethos-work/investigations/<slug>.md` in the workspace (see "Persisting investigations").
### 2. Analyze — group the evidence
Group what you collected by what each piece tells you about *what is actually happening*. Cluster similar errors. Note what's *not* there (e.g. "no entry in the access log" is a finding, not noise).
If the evidence is thin, return to step 1. Do not skip ahead to hypotheses with insufficient data.
### 3. Hypothesize — name 1-3 candidate root causes
A hypothesis is a sentence of the form: "X is happening because Y, which is observable as Z."
- Rank by likelihood given the evidence.
- For each, design a small experiment that would distinguish it from the others.
- Run the experiments. The result either confirms a hypothesis or invalidates it.
If all hypotheses are invalidated, return to step 1 — the data was not enough.
### 4. Verify — confirm the root cause
Before writing a fix, verify the chosen hypothesis with a final concrete test:
- Reproduce the failure deterministically.
- Apply the proposed fix locally.
- Confirm the failure no longer reproduces.
- Confirm no other behaviour regressed.
Only now do you have a confirmed root cause.
### 5. Implement
Two parts, both required:
1. **The fix.** Smallest change that addresses the root cause. No collateral cleanup.
2. **A regression test.** A test that would have caught the original failure. Without this, the fix is invisible — the next regression slips through.
Run the full test suite. Do not move on until all tests pass.
## Per-boundary logging
While investigating, prefer adding entry/exit logging at component boundaries (function boundaries, network boundaries, queue boundaries) over scattering `console.log` inside a single function. The signal-to-noise is much higher: you see *what crossed the boundary*, not the internal arithmetic.
Remove the boundary logging when the bug is confirmed and a regression test is in place.
## Persisting investigations
For non-trivial investigations, write the log to `.ethos-work/investigations/<slug>.md` in the workspace. Include: the symptoms, the evidence collected, the hypothesis tested, the root cause, and the fix. Future investigations of similar bugs benefit from being able to grep this directory.
`.ethos-work/` is the workspace's scratch directory, kept out of git by adding `.ethos-work/` to `.git/info/exclude`. Do not write under `~/.ethos`: a personality's default `fs_reach` lets `write_file` write only its own personality directory and its working directory (`deriveFsReachPaths` in `packages/core/src/fs-reach.ts`), so a write there is refused.
## The iron rule
**No fix lands without a confirmed root cause and a regression test.** A bug fix without a test that would have caught the original is not really fixed — it just isn't visible right now.
If the user asks you to skip the test "because we're in a hurry", refuse and explain that you'll skip the test only when explicitly authorized as a hotfix-with-followup, and only if a follow-up task is created to add the test.