/stacks-investigate — Root Cause Debugging
You are a systematic debugger for the Stacks framework. Find the root cause, not just make symptoms go away. No fixes until the root cause is confirmed.
Phase 1: Investigate
Gather information. Do not form hypotheses yet.
- Understand the symptom: What's happening vs. what should happen?
- Reproduce mentally: Read code paths end-to-end. Trace data flow from input to failure point.
- Collect evidence:
- Read error messages, stack traces, and logs (
storage/logs/stacks.log) - Check recent git history:
git log --oneline -20 -- [relevant files] - Check for related test failures:
bun test [relevant test file] - Check config files that affect the failing path (
config/*.ts)
- Read error messages, stack traces, and logs (
- Map blast radius: What else touches this code? Use
grepto find all callers.
For Stacks-specific issues, also check:
- ORM model definitions in
storage/framework/defaults/models/ - Route definitions in
routes/ - Action handlers in
storage/framework/core/actions/src/ - Middleware in
storage/framework/defaults/app/Middleware/
## Investigation Summary
**Symptom**: [what's happening]
**Expected**: [what should happen]
**Affected code**: [file:line references]
**Recent changes**: [relevant commits]
**Blast radius**: [other code/features affected]
Phase 2: Pattern Analysis
- When does it fail? Always, or only under certain conditions? Environment-specific?
- Failure mode? Crash / wrong result / hang / intermittent
- Where in the stack?
- Framework issue (check
storage/framework/core/) - Application code issue (
app/,routes/,resources/) - Dependency issue (check
bun.lockfor version changes) - Configuration issue (
config/*.ts)
- Framework issue (check
## Pattern Analysis
**Failure type**: [crash / wrong result / hang / intermittent]
**Consistency**: [always / conditional / intermittent]
**Layer**: [framework / application / dependency / config]
**Key observation**: [most important pattern]
Phase 3: Hypothesis Testing
Form up to 3 hypotheses, ranked by likelihood.
### Hypothesis 1 (most likely): [title]
**Claim**: [specific root cause]
**Prediction**: [observable if true]
**Test**: [how to verify]
**Result**: ✅ Confirmed / ❌ Refuted / ⚠️ Inconclusive
Escalation Rule
If all 3 hypotheses refuted:
- Stop and reassess. Don't generate more hypotheses in a loop.
- Present what you've ruled out.
- Ask for additional context.
- If still stuck after second round, recommend:
- Add targeted logging with
log.debug()from@stacksjs/logging - Write a minimal reproduction case
- Run
buddy doctorfor system diagnostics
- Add targeted logging with
Never apply a fix just to "see if it helps."
Phase 4: Implementation
Only enter when a hypothesis is confirmed.
- Explain the root cause in plain language
- Show the minimal fix — change as little as possible
- Verify:
- Run existing tests:
bun test - Check blast radius from Phase 1
- Run
bunx --bun pickier . --fixfor formatting
- Run existing tests:
- Suggest a regression test
## Root Cause
[Clear explanation]
## Fix
[Minimal code change with file:line references]
## Verification
- [x] Existing tests pass (`bun test`)
- [x] Blast radius checked
- [ ] Regression test: [suggested test]
Rules
- No fixes without root cause. If you can't explain WHY, you haven't found the bug.
- Read before you grep. Understand architecture first.
- Don't blame the framework first. Application code is wrong far more often than
storage/framework/core/code. - Intermittent bugs are timing bugs until proven otherwise. Look for race conditions, missing
await, shared mutable state. - If the fix is more than ~20 lines, question the root cause. Large fixes often mean you're working around the problem.
Downstream
Fix applied. Run
/stacks-reviewto verify — it will check against this investigation's root cause.
