Problem Locating and Solving
Coverage
End-to-end bug localization workflow: problem-statement construction, search-space reduction by symptom type, boundary-based fault localization (entry-point tracing, differential comparison, binary search, minimal repro, search-before-read), root-cause isolation (symptom vs cause analysis with stop conditions), multi-option fix generation across local-patch / guardrail / structural classes, blast-radius comparison between candidates, implementation rules that bind the fix to a regression-proofing artifact, five verification types (repro test, regression test, neighbor check, blast-radius check, explanation check), and a four-question post-fix reflection that promotes one-off fixes into prevention mechanisms when the class could recur.
Philosophy
The most common debugging failure is not lack of skill — it is skipping steps. Agents jump from symptom to fix without isolating the root cause, which produces patches that hide bugs instead of removing them. This skill exists for the gap between "something is wrong" and "the right fix is verified."
Every step in the loop has been added because skipping it caused a real false fix. Knowing debugging theory is not enough — you need a repeatable way to find the failing boundary, isolate the actual cause, compare solution options, and prove the fix closes the problem without widening the blast radius. The loop is the process; intuition without the loop produces patches that look like fixes and re-emerge under different inputs two days later.
Workflow
Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.
1. The Locate-to-Solve Loop
Use this loop in order. Skipping steps creates false fixes.
- Define the problem precisely.
- Bound the search space.
- Locate the first failing boundary.
- Isolate the root cause.
- Generate multiple fix options.
- Choose the lowest-blast-radius fix that prevents recurrence.
- Verify with regression evidence.
- Reflect on what should now be prevented or documented.
2. Problem Statement Contract
Before searching the codebase, write the problem in a concrete form.
| Field |
Required question |
| What |
What is failing? |
| Where |
Which route, job, component, file, or workflow shows the failure? |
| When |
Under what timing, input, environment, or user state does it happen? |
| Expected |
What should happen instead? |
| Actual |
What observable result occurs now? |
| Impact |
Why does this matter: correctness, UX, security, cost, or trust? |
If one of these is missing, the search space is still too loose.
3. Bound the Search Space
Do not search the whole repo emotionally. Reduce the space first.
Search-space reduction table
| Symptom type |
Start boundary |
Fastest first move |
| Route / API failure |
Request handler → service → query |
Find the route entry point and first downstream call |
| UI bug |
Visible component → state source → async edge |
Identify the first component that renders wrong data |
| Data mismatch |
Read model → transform → source table |
Compare the final number against the nearest prior stage |
| Scheduled job issue |
Cron trigger → worker → provider call |
Find where the run first diverges from normal logs |
| Build / test failure |
First failing file → import chain → config |
Start from the first deterministic error, not the last cascade |
Bounding rules
- Prefer the first failing boundary over the final visible symptom.
- Prefer the smallest reproducible path over the full production path.
- Prefer one confirmed stack trace or failing assertion over broad speculation.
- If you cannot name the likely subsystem, you are still in discovery, not fixing.
4. Locate the First Failing Boundary
The critical move is to find the first point where reality stops matching the expected flow.
| Technique |
Use when |
Result |
| Entry-point tracing |
You know the failing route or component |
Narrows owner path quickly |
| Differential comparison |
Good path vs bad path exists |
Exposes the divergence point |
| Binary search through the path |
Flow has many stages |
Cuts search space fast |
| Minimal repro |
Failure is noisy or stateful |
Produces a smaller truth surface |
| Search-before-read |
Codebase is unfamiliar |
Finds candidate files without flooding context |
Boundary questions
- Where is the first bad value observed?
- What was the last known-good step immediately before it?
- Is the failure caused by code, data, environment, or timing?
- What single check would prove which of those four buckets owns it?
5. Root Cause Isolation
Symptoms are not causes. A cause explains why the symptom appears.
Cause-isolation pattern
- State the symptom.
- Ask what immediate condition makes that symptom possible.
- Ask what created that condition.
- Stop only when the answer identifies a fixable logic, data, config, or process cause.
Symptom vs cause table
| Symptom |
Likely cause form |
| Timeout |
Query shape, retry loop, blocking external dependency |
| Wrong total |
Missing component, double count, unit mismatch, null semantics |
| Empty UI state |
Fetch never ran, filter mismatch, wrong auth or scoping |
| Intermittent failure |
Race, stale cache, background mutation, provider variability |
| Build break |
Import drift, type-contract break, config mismatch |
If the proposed fix does not explain why the symptom happened, it is probably still a patch.
6. Generate More Than One Fix
Do not lock onto the first plausible solution.
| Fix class |
Best for |
Tradeoff |
| Local patch |
Clear isolated mistake |
Fastest, but may miss recurrence prevention |
| Guardrail |
Bad inputs or state transitions |
Safer, but may hide deeper issues if overused |
| Structural fix |
Repeated or systemic failures |
Highest confidence long-term, but higher change cost |
Generate at least two candidate fixes whenever the root cause is not trivial.
Compare candidate fixes by
- blast radius
- reversibility
- recurrence prevention
- alignment with existing patterns
- verification cost
Pick the option that solves the root cause with the smallest justified surface area.
7. Implementation Rules
- Fix the cause, not only the symptom.
- Add the smallest regression-proofing artifact that fits: test, guard, or doc rule.
- Keep the proof close to the fix: failing case before, passing case after.
- If the fix touches a shared pattern, look for sibling sites that may carry the same defect.
8. Verification Rules
The fix is not complete until the original failure mode is proven closed.
| Verification type |
Question it answers |
| Repro test |
Can I still trigger the original bug? |
| Regression test |
Will this exact class of bug return silently? |
| Neighbor check |
Did the fix break adjacent behaviour? |
| Blast-radius check |
Did the changed boundary affect another subsystem? |
| Explanation check |
Can I explain why this fix works? |
Verification minimum
- Reproduce the failure before the fix when possible.
- Show the failure no longer occurs after the fix.
- Check one neighbouring path that could regress.
- Record the root cause in one sentence.
9. Reflection and Prevention
After the fix, ask:
- Was this a one-off or a repeated class of issue?
- Should this become an eval, lint rule, or doc rule?
- Did the real delay come from locating the bug or deciding the fix?
- What clue should future agents notice sooner?
If the same class of bug could reasonably recur, promote the learning into a prevention mechanism.
Verification
Do NOT Use When
| Instead, use |
Why |
debugging |
Executing scientific-method debugging on an already-localized bug. Debugging owns the per-technique RCA loop; this skill owns the workflow that produces the localization. |
code-review |
Reviewing not-yet-broken code for quality and correctness. Code-review is proactive at PR scope; this skill is reactive once a failure has been observed. |
refactor |
Restructuring code for clarity or maintainability when nothing is broken. Refactor is for healthy code; this skill is for broken code. |
diagnosis |
Triaging an unknown failure into a problem class before debugging begins. Diagnosis owns the per-incident triage; this skill owns the locate-to-fix workflow that runs after triage. |
pattern-recognition |
Identifying the recurring class behind many bugs and proposing a structural rule. Pattern-recognition feeds prevention into the reflection step of this workflow but does not own the per-bug localization. |
lint-overlay |
Adding the lint rule that automates prevention of the bug class. Lint-overlay owns the rule machinery; this skill decides whether a recurring bug warrants a rule. |
tool-call-strategy |
Deciding which tool (Grep / Glob / Read) to use during search-space reduction. Tool-call-strategy owns the tool selection; this skill owns the workflow within which the tools are used. |
graph-audit |
Performing dependency and structural audits across the codebase graph. Graph-audit owns the structural perspective; this skill owns the per-bug perspective. |
context-graph |
Understanding the relationships between files and modules to estimate blast radius. Context-graph owns the relationship model; this skill consumes it during fix-comparison. |
1---2name: problem-locating-solving3description: Use when locating a bug in an unfamiliar codebase, tracing a failure from symptom to source, or choosing between candidate fixes after the symptom is observed but before a patch lands. Covers the locate-to-solve workflow: problem-statement contract, search-space reduction, boundary-based fault localization, good-vs-bad path comparison, binary search through a call chain, minimal repro, root-cause isolation, fix option comparison, blast-radius review, and post-fix verification. Do NOT use for broad task planning once the bug is localized, test-pyramid design, or performance forensics.4license: MIT5---6
7# Problem Locating and Solving
8
9## Coverage
10
11End-to-end bug localization workflow: problem-statement construction, search-space reduction by symptom type, boundary-based fault localization (entry-point tracing, differential comparison, binary search, minimal repro, search-before-read), root-cause isolation (symptom vs cause analysis with stop conditions), multi-option fix generation across local-patch / guardrail / structural classes, blast-radius comparison between candidates, implementation rules that bind the fix to a regression-proofing artifact, five verification types (repro test, regression test, neighbor check, blast-radius check, explanation check), and a four-question post-fix reflection that promotes one-off fixes into prevention mechanisms when the class could recur.
12
13## Philosophy
14
15The most common debugging failure is not lack of skill — it is skipping steps. Agents jump from symptom to fix without isolating the root cause, which produces patches that hide bugs instead of removing them. This skill exists for the gap between "something is wrong" and "the right fix is verified."
16
17Every step in the loop has been added because skipping it caused a real false fix. Knowing debugging theory is not enough — you need a repeatable way to find the failing boundary, isolate the actual cause, compare solution options, and prove the fix closes the problem without widening the blast radius. The loop is the process; intuition without the loop produces patches that look like fixes and re-emerge under different inputs two days later.
18
19## Workflow
20
21Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.
22
23## 1. The Locate-to-Solve Loop
24
25Use this loop in order. Skipping steps creates false fixes.
26
271. Define the problem precisely.
282. Bound the search space.
293. Locate the first failing boundary.
304. Isolate the root cause.
315. Generate multiple fix options.
326. Choose the lowest-blast-radius fix that prevents recurrence.
337. Verify with regression evidence.
348. Reflect on what should now be prevented or documented.
35
36## 2. Problem Statement Contract
37
38Before searching the codebase, write the problem in a concrete form.
39
40| Field | Required question |
41| --- | --- |
42| What | What is failing? |
43| Where | Which route, job, component, file, or workflow shows the failure? |
44| When | Under what timing, input, environment, or user state does it happen? |
45| Expected | What should happen instead? |
46| Actual | What observable result occurs now? |
47| Impact | Why does this matter: correctness, UX, security, cost, or trust? |
48
49If one of these is missing, the search space is still too loose.
50
51## 3. Bound the Search Space
52
53Do not search the whole repo emotionally. Reduce the space first.
54
55### Search-space reduction table
56
57| Symptom type | Start boundary | Fastest first move |
58| --- | --- | --- |
59| Route / API failure | Request handler → service → query | Find the route entry point and first downstream call |
60| UI bug | Visible component → state source → async edge | Identify the first component that renders wrong data |
61| Data mismatch | Read model → transform → source table | Compare the final number against the nearest prior stage |
62| Scheduled job issue | Cron trigger → worker → provider call | Find where the run first diverges from normal logs |
63| Build / test failure | First failing file → import chain → config | Start from the first deterministic error, not the last cascade |
64
65### Bounding rules
66
67- Prefer the first failing boundary over the final visible symptom.
68- Prefer the smallest reproducible path over the full production path.
69- Prefer one confirmed stack trace or failing assertion over broad speculation.
70- If you cannot name the likely subsystem, you are still in discovery, not fixing.
71
72## 4. Locate the First Failing Boundary
73
74The critical move is to find the first point where reality stops matching the expected flow.
75
76| Technique | Use when | Result |
77| --- | --- | --- |
78| Entry-point tracing | You know the failing route or component | Narrows owner path quickly |
79| Differential comparison | Good path vs bad path exists | Exposes the divergence point |
80| Binary search through the path | Flow has many stages | Cuts search space fast |
81| Minimal repro | Failure is noisy or stateful | Produces a smaller truth surface |
82| Search-before-read | Codebase is unfamiliar | Finds candidate files without flooding context |
83
84### Boundary questions
85
86- Where is the first bad value observed?
87- What was the last known-good step immediately before it?
88- Is the failure caused by code, data, environment, or timing?
89- What single check would prove which of those four buckets owns it?
90
91## 5. Root Cause Isolation
92
93Symptoms are not causes. A cause explains why the symptom appears.
94
95### Cause-isolation pattern
96
971. State the symptom.
982. Ask what immediate condition makes that symptom possible.
993. Ask what created that condition.
1004. Stop only when the answer identifies a fixable logic, data, config, or process cause.
101
102### Symptom vs cause table
103
104| Symptom | Likely cause form |
105| --- | --- |
106| Timeout | Query shape, retry loop, blocking external dependency |
107| Wrong total | Missing component, double count, unit mismatch, null semantics |
108| Empty UI state | Fetch never ran, filter mismatch, wrong auth or scoping |
109| Intermittent failure | Race, stale cache, background mutation, provider variability |
110| Build break | Import drift, type-contract break, config mismatch |
111
112If the proposed fix does not explain why the symptom happened, it is probably still a patch.
113
114## 6. Generate More Than One Fix
115
116Do not lock onto the first plausible solution.
117
118| Fix class | Best for | Tradeoff |
119| --- | --- | --- |
120| Local patch | Clear isolated mistake | Fastest, but may miss recurrence prevention |
121| Guardrail | Bad inputs or state transitions | Safer, but may hide deeper issues if overused |
122| Structural fix | Repeated or systemic failures | Highest confidence long-term, but higher change cost |
123
124Generate at least two candidate fixes whenever the root cause is not trivial.
125
126### Compare candidate fixes by
127
128- blast radius
129- reversibility
130- recurrence prevention
131- alignment with existing patterns
132- verification cost
133
134Pick the option that solves the root cause with the smallest justified surface area.
135
136## 7. Implementation Rules
137
138- Fix the cause, not only the symptom.
139- Add the smallest regression-proofing artifact that fits: test, guard, or doc rule.
140- Keep the proof close to the fix: failing case before, passing case after.
141- If the fix touches a shared pattern, look for sibling sites that may carry the same defect.
142
143## 8. Verification Rules
144
145The fix is not complete until the original failure mode is proven closed.
146
147| Verification type | Question it answers |
148| --- | --- |
149| Repro test | Can I still trigger the original bug? |
150| Regression test | Will this exact class of bug return silently? |
151| Neighbor check | Did the fix break adjacent behaviour? |
152| Blast-radius check | Did the changed boundary affect another subsystem? |
153| Explanation check | Can I explain why this fix works? |
154
155### Verification minimum
156
1571. Reproduce the failure before the fix when possible.
1582. Show the failure no longer occurs after the fix.
1593. Check one neighbouring path that could regress.
1604. Record the root cause in one sentence.
161
162## 9. Reflection and Prevention
163
164After the fix, ask:
165
166- Was this a one-off or a repeated class of issue?
167- Should this become an eval, lint rule, or doc rule?
168- Did the real delay come from locating the bug or deciding the fix?
169- What clue should future agents notice sooner?
170
171If the same class of bug could reasonably recur, promote the learning into a prevention mechanism.
172
173## Verification
174
175- [ ] I can state the problem in concrete expected-vs-actual terms.
176- [ ] I have reduced the search space before opening lots of files.
177- [ ] I know the first failing boundary, not just the final symptom.
178- [ ] I can explain the root cause in one sentence.
179- [ ] I considered more than one fix when the cause was non-trivial.
180- [ ] I verified the original failure path and one neighbouring path.
181- [ ] I captured any new prevention rule if this problem class could recur.
182
183## Do NOT Use When
184
185| Instead, use | Why |
186|---|---|
187| `debugging` | Executing scientific-method debugging on an already-localized bug. Debugging owns the per-technique RCA loop; this skill owns the workflow that produces the localization. |
188| `code-review` | Reviewing not-yet-broken code for quality and correctness. Code-review is proactive at PR scope; this skill is reactive once a failure has been observed. |
189| `refactor` | Restructuring code for clarity or maintainability when nothing is broken. Refactor is for healthy code; this skill is for broken code. |
190| `diagnosis` | Triaging an unknown failure into a problem class before debugging begins. Diagnosis owns the per-incident triage; this skill owns the locate-to-fix workflow that runs after triage. |
191| `pattern-recognition` | Identifying the recurring class behind many bugs and proposing a structural rule. Pattern-recognition feeds prevention into the reflection step of this workflow but does not own the per-bug localization. |
192| `lint-overlay` | Adding the lint rule that automates prevention of the bug class. Lint-overlay owns the rule machinery; this skill decides whether a recurring bug warrants a rule. |
193| `tool-call-strategy` | Deciding which tool (Grep / Glob / Read) to use during search-space reduction. Tool-call-strategy owns the tool selection; this skill owns the workflow within which the tools are used. |
194| `graph-audit` | Performing dependency and structural audits across the codebase graph. Graph-audit owns the structural perspective; this skill owns the per-bug perspective. |
195| `context-graph` | Understanding the relationships between files and modules to estimate blast radius. Context-graph owns the relationship model; this skill consumes it during fix-comparison. |
aibot88