write-plan

disable-model-invocation	true
name	write-plan
description	Write a comprehensive, no-placeholder implementation plan as a series of bite-sized tasks, each with exact file paths, real code, TDD steps, and commit instructions. Saves as a GitHub Issue with a [PLAN] prefix. Use after preflight has established what to build.

Write Plan

Write a rigorous implementation plan assuming the engineer has zero context about the codebase and will execute tasks in isolation. Every step must contain everything they need — no references to "fill in later", no vague instructions, no placeholders.

DRY. YAGNI. TDD. Frequent commits.

Scope Check

If the task spans multiple independent subsystems, suggest breaking it into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

Step 1: Map the File Structure

Before defining tasks, map out which files will be created or modified and what each is responsible for. Decomposition decisions get locked in here.

• Each file should have one clear responsibility
• Files that change together should live together — split by responsibility, not by technical layer
• In existing codebases, follow established patterns
• Prefer smaller focused files over large ones that do too much

Step 2: Right-size the Tasks

A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate.

• Fold setup, configuration, and scaffolding into the task whose deliverable needs them
• Split only where a reviewer could meaningfully reject one task while approving its neighbour
• Each task ends with an independently testable deliverable

Step 3: Write the Plan

Document Header

# [Feature Name] Implementation Plan

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

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

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

## Adversarial Audit & Security

[List key edge cases, security hazards, sanitization needs, or potential race conditions identified, and how they are handled in this plan.]

## Global Constraints

[Project-wide requirements — version floors, dependency limits, naming rules,
platform requirements — one line each. Every task implicitly includes this
section.]

---

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`

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact signatures]
- Produces: [what later tasks rely on — exact function names, parameter and
  return types. A task's implementer sees only their own task; this block is
  how they learn the names and types neighbouring tasks use.]

- [ ] **Step 1: Write the failing test**

```typescript
it('specific behaviour', () => {
  const result = fn(input)
  expect(result).toBe(expected)
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test -- tests/path/test.ts`
Expected: FAIL — "fn is not defined"

- [ ] **Step 3: Write minimal implementation**

```typescript
export function fn(input: string): string {
  return expected
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npm test -- tests/path/test.ts`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature"
```

No Placeholders

Every step must contain the actual content an engineer needs. These are plan failures — never write them:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" / "handle edge cases" (without showing how)
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code — the engineer may read tasks out of order)
• Steps that describe what to do without showing how
• References to types or functions not defined in any task

Step 4: Self-Review

After writing the complete plan, check it against the original spec with fresh eyes.

1. Spec coverage — can you point to a task for each requirement? List gaps.
2. Placeholder scan — search for any of the patterns listed above. Fix them.
3. Type consistency — do types, method signatures, and property names match across tasks? A function called clearLayers() in Task 3 but clearAllLayers() in Task 7 is a bug.

Fix issues inline. If a spec requirement has no task, add the task.

Step 5: Save as GitHub Issue

1. Verify there is a GitHub remote: gh repo view --json nameWithOwner — if it fails, stop and tell the user.
2. Create the issue:

   gh issue create --title "[PLAN] <feature-name>" --body "<full plan content>"
   

3. Tell the user the issue URL and ask how they want to proceed: inline execution in this session, or they'll drive it themselves.