Execution System

Purpose: Do the work at high quality with velocity. When to trigger: After clarity is established and priorities are set.

Pre-Flight Checklist

Before writing any code, verify:

• Clarity exists - active-context.md is current with clear success criteria
• Task is prioritized - This is the right thing to work on now
• Success criteria defined - I know exactly what "done" looks like
• Boundaries set - I know what NOT to do

If any are missing → Return to appropriate system.

Execution Protocol

1. Track Progress Visibly

Use TodoWrite at the start:

1. [ ] Step one of implementation
2. [ ] Step two of implementation
3. [ ] Validation step

Update status as you go. The user should always know where you are.

2. Make the Smallest Viable Change

• Don't over-engineer
• Don't add features that weren't requested
• Don't refactor unrelated code
• Don't add "nice to haves"
• Solve the exact problem, nothing more

3. Validate Continuously

After every significant change:

npx tsc --noEmit  # Catch type errors immediately

Don't let errors accumulate. Fix as you go.

4. One Thing at a Time

• Complete one task before starting another
• Don't context-switch mid-implementation
• If blocked, acknowledge it rather than switching
• Mark complete immediately when done

5. Parallel When Independent

Use subagents (Task tool) for truly independent work:

• Research while implementing
• Multiple unrelated fixes
• Exploration while writing

But NOT for dependent steps - those must be sequential.

Quality Gates

Before marking any task complete:

Code Quality

• Types pass (npx tsc --noEmit)
• No lint errors
• Follows existing patterns in codebase
• No unintended side effects

Functionality

• Works for the happy path
• Edge cases considered
• Error states handled
• Loading states present (if UI)

Integration

• Doesn't break existing functionality
• Works with existing data
• API contracts maintained

Documentation (if applicable)

• Complex logic commented
• API changes noted in SOURCE_OF_TRUTH.md
• Breaking changes flagged

Velocity Principles

Do:

• Edit existing files over creating new ones
• Use existing patterns and utilities
• Ask early if blocked (don't spin)
• Ship incrementally
• Commit working states frequently

Don't:

• Invent new patterns when existing ones work
• Gold-plate solutions
• Wait until everything is perfect
• Make changes outside the task scope

Output Tracking

During execution, maintain:

1. Todos - Current task breakdown with status
2. Active context - Updated if scope changes
3. Issues - Any new problems discovered → Identity System

Completion Criteria

A task is ONLY complete when:

1. All acceptance criteria from clarity are met
2. All quality gates pass
3. Type check passes
4. Functionality verified
5. No regressions introduced

Handling Blocks

If you hit a wall during execution:

1. STOP - Don't keep trying the same failing approach
2. DOCUMENT - What was attempted, what failed
3. TRANSITION - Go to Reset System if blocked, or ask user

Never mark something complete that isn't actually done.

Transition

After execution:

• Success → Mark complete, update SOURCE_OF_TRUTH.md if significant
• Partial success → Document what remains, continue or handoff
• Failure → Proceed to Reset System
• New issues discovered → Log to Identity System

Capture Learning: If something important was learned (new pattern, gotcha, or insight), add one line to learnings.md. Keep it brief - this is memory, not documentation.

This is System 4 of 5: Clarity → Identity → Priority → Execution → Reset