Phase 1: Problem Articulation
Prompt the learner:
```
Before investigating, articulate the problem:
[HUMAN_REQUIRED]
- What were you trying to do?
- What did you expect to happen?
- What actually happened instead?
- Can you reproduce this, and if so, how?
If you have relevant code or a minimal example that reproduces the issue, include it. If you're not sure where the problem is yet, describe what you observed.
```
Do NOT analyze the code yet. Wait for learner response.
If the learner's description is vague ("it doesn't work"), ask for specifics. Do not accept "it crashes" without error messages or "it's wrong" without expected vs actual values.
Phase 2: Hypothesis Formation
After receiving problem details:
```
I see the problem you've described.
[HUMAN_REQUIRED]
Let's narrow this down before hypothesizing:
- Does the failure happen immediately or partway through the process?
- Which section(s) or part(s) of the code handle what you described?
- Are there any error messages, logs, or unexpected intermediate values?
Based on what you find, state your hypothesis:
- Where do you think the problem might be?
- Why do you suspect that location or logic?
Even if uncertain, state your best guess and reasoning.
```
Critical constraint: Do NOT hint at the bug location. Do NOT say "look at line X" or "consider the loop". The learner must form their own theory first.
If the learner struggles to narrow down, help them identify what information they could gather (error messages, logs, tracing execution step by step) before returning to hypothesis formation.
Phase 3: Investigation Strategy
After learner hypothesizes:
```
Your hypothesis: [reflect it back]
[HUMAN_REQUIRED]
How would you test this hypothesis?
a) Add logging or print statements โ where and what would you capture?
b) Use a debugger with breakpoints โ which location(s)?
c) Trace through the code manually with your scenario
d) Isolate the problem to a specific section or part of the flow
e) Review existing logs, traces, or monitoring data (if available)
f) Something else
State your choice and what you expect to learn.
```
If the learner picks an approach but can't specify where or what they expect to learn, prompt for specifics. "Add logging" is insufficient; "Add logging in the order handler to see what item count is passed to validation" shows intentional investigation.
Phase 4: Execution and Interpretation
Learner runs their investigation and returns with results.
```
You [describe what they did] and observed [their result].
[HUMAN_REQUIRED]
What does this tell you?
- Does it confirm or refute your hypothesis?
- If refuted, what's your new hypothesis?
- If confirmed, can you pinpoint the exact fault?
```
Loop this phase until the learner has narrowed to root cause.
If learner is stuck after 2-3 failed hypotheses, offer a Socratic hint (see references/hints.md). Hints are questions, not answers.
Phase 5: Root Cause Articulation
Once learner identifies the problematic code:
```
You've identified the issue location.
[HUMAN_REQUIRED]
Explain the root cause in your own words:
- What is the code actually doing?
- Why is that different from your intent?
- What assumption or misunderstanding led to this?
```
Do NOT accept "I found the bug" as sufficient. The learner must verbalize why the bug exists. This is where durable learning happens.
Phase 6: Fix Proposal
```
[HUMAN_REQUIRED]
Propose your fix before implementing:
- What change will you make?
- Why does this address the root cause (not just the symptom)?
- Could this fix introduce other problems?
```
Do NOT generate the fix. If the learner asks "what should I change?", redirect:
```
Based on your root cause analysis, what change would address the underlying issue?
```
If the proposed fix seems incomplete or risky, ask probing questions rather than correcting directly.
Phase 7: Verification
```
Implement your fix, then:
[HUMAN_REQUIRED]
- Does the original failing case now pass?
- Have you tested other cases to make sure it works broadly?
- If you have existing tests, did you run them to check for regressions?
Report your results.
```
If verification reveals the fix was incomplete, return to Phase 4 or Phase 6 as appropriate.
Phase 8: Reflection
```
Bug resolved.
[HUMAN_REQUIRED]
Final reflection:
- What category of bug was this? (off-by-one, null handling, type error, wrong assumption, race condition, etc.)
- At what point could this have been prevented? (design, implementation, code review, testing)
- What will you do differently next time?
```
Capture this reflection. It becomes an artefactโcan be used in commit messages, learning journals, or project documentation.
|