Implementation Planning

Write comprehensive implementation plans assuming the executor has zero context. Document everything: which files to touch, complete code, how to test. Bite-sized tasks. DRY. YAGNI. TDD.

The Iron Law

NO IMPLEMENTATION WITHOUT A PLAN FIRST

For multi-step tasks, write the plan before writing code.

When to Use

• MUST: Before implementing features with 3+ steps
• MUST: Before complex refactoring
• SHOULD: When multiple files need coordinated changes
• MAY: Skip for single-file, single-function changes

Bite-Sized Task Granularity

Each step is ONE action (2-5 minutes):

1. Write the failing test - step
2. Run it to verify it fails - step
3. Implement minimal code to pass - step
4. Run tests to verify they pass - step
5. Commit - step

Plan Structure

Header (Required)

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`

**Step 1: Write the failing test**

\`\`\`typescript
import { describe, it, expect } from 'vitest';
import { mock } from 'vitest-mock-extended';
import { getUser, type GetUserDeps } from './get-user';

describe('getUser', () => {
  it('returns NOT_FOUND when user does not exist', async () => {
    const deps = mock<GetUserDeps>();
    deps.db.findUser.mockResolvedValue(null);

    const result = await getUser({ userId: '123' }, deps);

    expect(result.ok).toBe(false);
    if (!result.ok) {
      expect(result.error).toBe('NOT_FOUND');
    }
  });
});
\`\`\`

**Step 2: Run test to verify it fails**

Run: `npm test src/domain/get-user.test.ts`
Expected: FAIL with "Cannot find module './get-user'"

**Step 3: Write minimal implementation**

\`\`\`typescript
import { err, type Result } from '@/result';

export type GetUserDeps = {
  db: { findUser: (id: string) => Promise<User | null> };
};

export async function getUser(
  args: { userId: string },
  deps: GetUserDeps
): Promise<Result<User, 'NOT_FOUND'>> {
  return err('NOT_FOUND');
}
\`\`\`

**Step 4: Run test to verify it passes**

Run: `npm test src/domain/get-user.test.ts`
Expected: PASS

**Step 5: Commit**

\`\`\`bash
git add src/domain/get-user.ts src/domain/get-user.test.ts
git commit -m "feat(user): add getUser with NOT_FOUND handling"
\`\`\`

MUST/SHOULD/NEVER Rules

MUST

• MUST: Include exact file paths (never "in the appropriate file")
• MUST: Include complete code (never "add validation logic")
• MUST: Include exact commands with expected output
• MUST: Follow TDD cycle (test → fail → implement → pass → commit)
• MUST: Save plans to docs/plans/YYYY-MM-DD-<feature-name>.md

SHOULD

• SHOULD: Use fn(args, deps) pattern for new functions
• SHOULD: Use Result types for error handling
• SHOULD: Include type definitions in implementation
• SHOULD: Reference line numbers for modifications

NEVER

• NEVER: Write vague steps ("add appropriate error handling")
• NEVER: Skip the verification steps
• NEVER: Bundle multiple changes in one step
• NEVER: Assume executor knows the codebase

Plan Quality Checklist

Before finalizing:

• Every step is one action (2-5 minutes)
• All file paths are exact
• All code is complete and copy-pasteable
• All commands include expected output
• TDD cycle is clear for each task
• Commit messages follow project conventions

Execution Handoff

After saving the plan:

Plan complete and saved to `docs/plans/<filename>.md`.

Ready to execute? I'll follow TDD workflow for each task.

Integration