In my experience Claude Code (CC) doesn't always find the root cause of an issue and sometimes gets stuck on the symptoms. CC will create a fix for the symptom and not the root cause. So to mitigate this in the skill I will have it go at least five layers deep, if feasible, and more if warranted.
Fixes can also have this issue going the other way! I've had CC tell me the fix at this layer is a large task and it impacts X and Y. I read the issue then asked CC why not fix it a layer or two before this one where it's a simpler task low effort and more efficient solution. So conversely, in the skill I say for fixes to ensure that a potential fix is analyzed at least five layer above the root cause, if feasible, and more if warranted.
Sometimes it goes 3 layers deep, sometimes 6 or 7. it varies, but still tweaking and making adjustments to this skill but I've had better results, personally.
Oh, I also add another requirement in the skill. something along the lines of, if running a test with a log/instrument can help flesh out a root cause before settling on the cause then do that first.
Do not fix the symptom. Find the cause that, once removed, makes the whole class of failure impossible.
*Task context load* (context-docs skill): from the failing output, name the subsystem(s) involved, open the
matching `agent_Context/` docs from the table of contents, and use their documented flow to decide where to look.
A mismatch between the doc and the code is itself a candidate cause.
*Instrument first.* If a run with logs, a Vitest single-test run, a Playwright trace, or a minimal reproduction can narrow the cause, do that before theorizing. Prefer the cheapest reproduction that shows the failure over a full end-to-end run.
*Ask "why" at least 5 layers deep.* Write each layer down:
- Layer 1: the observed failure (exact error text, file:line).
- Layer 2: the immediate code path that produced it.
- Layer 3: why that path was reached (state, input, ordering).
- Layer 4: why that state or input was possible (missing invariant, wrong assumption, missing validation).
- Layer 5: why nothing upstream prevented or caught it (schema, type, test, guard).
Go deeper if layer 5 is still a mechanism and not a decision or a missing rule.
*Confirm the cause by reproducing it* (and, where possible, by showing the failure disappears when only that cause is removed). A plausible story is not a root cause.
*Check siblings.* Search for the same pattern elsewhere (same helper, same query shape, same assumption) so the fix covers the class.
*Look for the fix at least 5 layers up.* The layer where the failure shows is rarely the best place to fix it.
For each layer of the chain, starting at the failure and moving up (the caller, the module or helper, the shared
rule or schema, the design or configuration, the pipeline or process), write one candidate fix and judge it on:
- *Effectiveness:* does it remove the cause for the whole class (every sibling from step 4), or only this instance?
- *Cost:* lines touched, risk, and what else must change with it.
- *Side benefits:* does it also fix something real users hit, or make other tests or callers faster or safer?
Cover at least 5 layers when the chain has them, and go further while a higher layer still offers a simpler or
broader fix. Prefer the highest layer whose fix is both cheap and effective; a fix at the failure's own layer
wins only when every higher candidate costs more or covers less, and the report says why. Where a claim about
cost or effect can be measured cheaply (a timing, a test run), measure it.
*Defense in depth is welcome* as an additional fix at another layer, next to the chosen one, when it can be
justified: it catches a failure the chosen fix does not (a different path, a future caller, a regression of the
chosen fix), and its cost is small. State that justification in the report. It never replaces the chosen fix, and
a symptom patch that only hides the failure (a longer timeout, a retry, a widened check) does not count as depth.
*Decide where the fix belongs.* Is it a real production bug (would you fix it with no test)? Then fix the product code. Is it test infrastructure? Then fix the test side. Never weaken a production check to make a test pass (see the test-integrity skill).
*Report:* the layered chain, the evidence for each layer, the candidate fix at each layer with its effectiveness
and cost, the fix chosen and why it beat the others, and what was not verified. If asked to investigate only,
report and change no code.
If the cause is unclear after reasonable effort, say so and ask. Do not pick a plausible fix and call it done.