Brainstorming and planning

Brainstorming and Planning

Part 1: Brainstorming — Design Before Code

<HARD-GATE> Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. </HARD-GATE>

Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short, but you MUST present it and get approval.

Process:

1. Explore project context — check files, docs, recent commits
2. Ask clarifying questions — one at a time, prefer multiple choice when possible
3. Propose 2-3 approaches — with trade-offs and your recommendation. Lead with recommended option and explain why.
4. Present design — in sections scaled to complexity, get user approval after each section. Cover: architecture, components, data flow, error handling, testing.
5. Write design doc — save to docs/specs/YYYY-MM-DD-<topic>-design.md and commit
6. Spec self-review:
   • Placeholder scan: Any "TBD", "TODO", incomplete sections? Fix them.
   • Internal consistency: Do sections contradict each other?
   • Scope check: Focused enough for a single plan, or needs decomposition?
   • Ambiguity check: Could any requirement be interpreted two ways? Pick one.
7. User reviews written spec — wait for approval before proceeding
8. Transition to Part 2 — write implementation plan

Design Principles:

• One question at a time — don't overwhelm
• YAGNI ruthlessly — remove unnecessary features
• Design for isolation — smaller units, one purpose each, well-defined interfaces, testable independently
• In existing codebases — explore first, follow existing patterns
• If too large — decompose into sub-projects. Each gets its own spec → plan → implementation cycle.

---

Part 2: Writing Plans — Bite-Sized Executable Tasks

Write plans assuming the engineer executing has zero codebase context and questionable taste. Document everything: files to touch, code, testing, how to verify. DRY. YAGNI. TDD. Frequent commits.

Plan Document Header:

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Key technologies]

---

Each Task — Bite-Sized (2-5 minutes):

### Task N: [Component Name]

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

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

- [ ] **Step 2: Run test to verify it fails**
  Run: `npm test path/to/test.ts`
  Expected: FAIL with "[specific message]"

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

- [ ] **Step 4: Run test to verify it passes**
  Run: `npm test path/to/test.ts`
  Expected: PASS

- [ ] **Step 5: Commit**
  `git add ... && git commit -m "feat: add specific feature"`

No Placeholders — EVER:

These are plan failures — never write them:

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

Self-Review After Writing:

1. Spec coverage: Skim each requirement. Can you point to a task? List gaps.
2. Placeholder scan: Search for red flags. Fix them.
3. Type consistency: Do names match across tasks? (clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.)

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

Execution:

After saving the plan, execute tasks sequentially:

• Follow each step exactly
• Run verifications as specified
• Use /tdd skill for each implementation step
• Use /verify-done before marking anything complete

Git Worktrees:

For feature work, create an isolated worktree:

# Check for existing .worktrees/ directory, create if needed
# Verify .worktrees/ is in .gitignore (add + commit if not)
git worktree add .worktrees/<branch-name> -b <branch-name>
cd .worktrees/<branch-name>
npm install  # or appropriate setup
npm test     # verify clean baseline

When done: verify tests → merge/PR/keep/discard → clean up worktree.