stacks-investigate

---
name: stacks-investigate
description: Use when debugging issues in the Stacks project — four-phase root-cause debugging with hypothesis testing and escalation. Enforces "no fixes without root cause." Invoke with /stacks-investigate.
license: MIT
compatibility: Bun >= 1.3.0, TypeScript
allowed-tools: Read Edit Write Bash Grep Glob
---

# /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.

1. **Understand the symptom**: What's happening vs. what should happen?
2. **Reproduce mentally**: Read code paths end-to-end. Trace data flow from input to failure point.
3. **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`)
4. **Map blast radius**: What else touches this code? Use `grep` to 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

1. **When does it fail?** Always, or only under certain conditions? Environment-specific?
2. **Failure mode?** Crash / wrong result / hang / intermittent
3. **Where in the stack?**
   - Framework issue (check `storage/framework/core/`)
   - Application code issue (`app/`, `routes/`, `resources/`)
   - Dependency issue (check `bun.lock` for version changes)
   - Configuration issue (`config/*.ts`)

```
## 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:
1. **Stop and reassess.** Don't generate more hypotheses in a loop.
2. Present what you've ruled out.
3. Ask for additional context.
4. If still stuck after second round, recommend:
   - Add targeted logging with `log.debug()` from `@stacksjs/logging`
   - Write a minimal reproduction case
   - Run `buddy doctor` for system diagnostics

**Never apply a fix just to "see if it helps."**

## Phase 4: Implementation

Only enter when a hypothesis is confirmed.

1. **Explain the root cause** in plain language
2. **Show the minimal fix** — change as little as possible
3. **Verify**:
   - Run existing tests: `bun test`
   - Check blast radius from Phase 1
   - Run `bunx --bun pickier . --fix` for formatting
4. **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-review` to verify — it will check against this investigation's root cause.