The Four Phases

BEFORE attempting ANY fix:

Read Error Messages Carefully
- Full stack traces, not just the first line
- Vitest output includes file paths and line numbers
- TypeScript errors show the full type mismatch

Reproduce Consistently

# Run specific test
pnpm test src/features/workout/__tests__/specific.test.ts

# Run with verbose output
pnpm test --reporter=verbose

Check Recent Changes

git diff HEAD~5 --stat
git log --oneline -10

Gather Evidence in Multi-Component Systems

For Vue/Dexie issues, trace through layers:
```
Component → Composable → Repository → Dexie → IndexedDB
```
Add console.error at each layer to find where it breaks.
Trace Data Flow

See references/root-cause-tracing.md for the complete technique.

Find Working Examples
- Similar working tests in the codebase
- Same component patterns that work
Compare Against References
- Check testing-conventions skill for test patterns
- Check vue-integration-testing for browser mode patterns
- Check repository-pattern for Dexie patterns
Identify Differences
- What's different between working and broken?
- Missing await? Missing resetDatabase()?
- Wrong query priority (getByRole vs getByTestId)?

Form Single Hypothesis
- "I think X is the root cause because Y"
- Write it down, be specific
Test Minimally
- ONE change at a time
- Don't fix multiple things at once
Verify Before Continuing
- Did it work? Yes -> Phase 4
- Didn't work? Form NEW hypothesis
- DON'T add more fixes on top

Create Failing Test Case
- Use vue-integration-testing skill patterns
- Query priority: getByRole > getByText > getByTestId
Implement Single Fix
- ONE change addressing root cause
- No "while I'm here" improvements

Verify Fix

pnpm test           # All tests pass
pnpm type-check     # No type errors
pnpm lint           # No lint errors

If Fix Doesn't Work
- STOP after 3 failed attempts
- Question the architecture, not just the symptom
- Discuss with user before attempting more fixes

Common Issues in This Stack

Symptom: Test passes sometimes, fails in CI or under load.

Common causes:

See: references/condition-based-waiting.md

Symptom: Test passes alone, fails when run with others.

Root cause: Data from other tests polluting state.

Fix pattern:

beforeEach(async () => {
  await resetDatabase()  // ALWAYS first
})

See: references/defense-in-depth.md

Symptom: State updates but UI doesn't reflect changes.

Debug pattern:

import { nextTick } from 'vue'

// After state change
await nextTick()
// Now check DOM

If you think:

STOP. Return to Phase 1.

In references/ directory:

In scripts/ directory:

Phase	Activities	Success Criteria
1. Root Cause	Read errors, reproduce, check changes	Understand WHAT and WHY
2. Pattern	Find working examples, compare	Identify differences
3. Hypothesis	Form theory, test minimally	Confirmed or new hypothesis
4. Implementation	Create test, fix, verify	Bug resolved, tests pass