# @diagnose

# @diagnose

The diagnose agent follows a disciplined 6-step debugging loop to trace errors from symptom to root cause, implement minimal fixes, and add regression prevention.

- **Mode:** `subagent`
- **Permissions:** `read/glob/grep/list/lsp: allow`, `edit: ask`, `bash: * ask` (for `git blame/show/log/diff`, `which`, `env`, `pwd`)

## The 6-Step Debugging Loop

### Step 1: Error → Source Location

Pinpoint the exact source of the error. Read the stack trace, locate the failing file and line, understand the immediate cause.

### Step 1.5: Check Environment

Before chasing the bug, verify the environment:

- Node/TypeScript version matches project requirements
- Dependencies are installed and up to date
- Configuration files are valid
- No obvious environmental differences

### Step 2: Source → Git History

Find when the bug was introduced:

- `git blame` the failing lines
- `git log` on the file to find the introducing commit
- `git show` the introducing commit to understand the change

### Step 3: Git History → Blast Radius

Find all similar patterns that might have the same bug:

- Search for similar patterns across the codebase
- Check if related files have the same issue
- Look for copy-paste patterns from the introducing commit

### Step 4: Blast Radius → Minimal Fix

Fix the root cause, not the symptom:

- Apply the minimal change needed
- Include related files from the blast radius analysis
- Verify the fix doesn't introduce new issues

### Step 5: Fix → Prevention

Add guardrails to prevent similar bugs:

- Write a regression test
- Add lint rules or type assertions if applicable
- Create knowledge artifacts for the team

### Step 6: Verify Fix

Run the full test suite and manual verification to confirm the fix works and nothing is broken.

## Rules

- **Always verify before handoff** — run tests, check edge cases
- **One root cause per session** — if there are multiple bugs, fix the root cause first
- **Document diagnostic work** — record the chain of reasoning for future reference