iterative:tech-planning

What this skill does

# Create Technical Plan

Turn a PRD or set of requirements into a structured, executable implementation plan. Write as if the implementer has zero context for the codebase — document the decisions, the reasoning, and enough detail that they can start working without asking clarifying questions.

The plan captures WHAT to build and WHERE. The implementer writes the actual code.

## When to Use

- After `iterative:brainstorming` skill is complete
- When clear requirements exist and need an implementation plan
- Can be invoked standalone with existing requirements

If requirements are vague and no PRD exists, offer to start with `iterative:brainstorming` skill first.

**Note on scope:** Quick scope skips tech-planning entirely — the user implements directly from the brainstorming conversation. Standard scope may also skip tech-planning if the user chooses to implement directly from brainstorming's summary; tech-planning is invoked only when the user explicitly opts in. Full scope always uses tech-planning. Adapt plan depth to scope: a Standard-scope task doesn't need 5 parent tasks with 3 subtasks each — a flat checklist of 3-5 steps is sufficient. Full scope uses the complete structured plan format. Tech-planning is where the HOW lives — file paths, architecture decisions, implementation steps, test scenarios. This complements brainstorming's WHAT (requirements, scope, decisions).

## Key Principles

1. **Understand before structuring** — Explore the codebase and ask questions before writing the plan
2. **Decisions, not code** — Capture architecture choices, query strategies, component boundaries, trade-offs. Leave method names, signatures, and implementation code to the implementer
3. **Concrete test scenarios** — Specific inputs, expected outputs, edge cases to cover. Not full test code, not "test that it works"
4. **Test files are explicit** — Every feature subtask must include the test file path in its `**Files:**` field. Test scenarios without a target test file get skipped during implementation
5. **Right-sized subtasks** — Scoped to a single atomic commit, typically touching 2-3 files. Not too big (5+ files, multiple unrelated changes), not too small (single line, no meaningful test)
6. **Dependencies clear** — Explicit ordering of what depends on what
7. **Verification built-in** — Each subtask has a way to confirm it works

## Plan Quality Bar

Every plan must contain:

- **File paths** — Which files to create or modify
- **Decisions with rationale** — Architecture choices, query strategies, data flow, what was considered and rejected
- **Test scenarios** — Specific inputs, expected outputs, edge cases — not "verify it works"
- **Test file paths** — Every feature subtask includes the test file in `**Files:**` — no test file = tests won't get written
- **Existing patterns to follow** — Reference actual code in the codebase that the implementer should use as a model. Reference by function/class/pattern name, never by line number — line numbers drift as code changes
- **What and why, not how** — Describe what each subtask accomplishes and the key decisions driving it. Don't pre-write the implementation

A plan is ready when an implementer can start working without asking clarifying questions. They know what to build, where to build it, what decisions have been made, and what edge cases to handle. They write the code.

## Workflow

### Phase 0: Detect Resume / Assess Input

1. If user references an existing plan document or topic: load the document, summarize current state, and let the user direct what happens next. Build on existing content, update in place.
2. If no PRD AND requirements are vague: ask the user: A) Start with brainstorming first (recommended), B) Proceed with what we have. If brainstorming: invoke `iterative:brainstorming` skill.
3. Otherwise: proceed to Phase 1.

### Phase 1: Gather Context (Q&A + Codebase Exploration)

1. Read PRD (if exists). Check both `docs/prd/` and `docs/brainstorms/` for existing documents. Also check `docs/design-directions/` for design direction docs. If a PRD references a design direction doc, read both — the direction doc contains visual/UX decisions that inform implementation. If only a direction doc exists (no PRD), use it as the requirements input alongside any context from the brainstorming conversation.
2. **Check for open questions.** If the PRD has an Open Questions section, review each question. Technical questions (tagged `[Affects ...]` or implementation-related) should be investigated during codebase exploration below. Non-technical questions that remain unresolved may need the user's input — flag them early.
3. Explore the codebase for: existing patterns and conventions to follow, files and modules that will be affected, test patterns and frameworks in use, related code that informs the design.
4. **Resolve technical open questions.** As codebase exploration answers PRD questions, note the resolution. These findings may trigger PRD updates (see PRD Alignment below).
5. Ask implementation-focused questions ONE AT A TIME: architecture preferences, highest risk areas, testing approach, constraints not in the PRD, existing code patterns to follow or avoid.
6. Gate: continue until approach is clear OR user says "proceed."
7. Do NOT start writing the plan until this phase is complete.

### Phase 2: Structure the Plan

1. Identify major components (become parent tasks, typically 2-5).
2. Break each into subtasks (2-5 per parent, one commit each).
3. Use the standardized subtask format (see template) — every subtask has the same fields so it can be directly converted into tasks.
4. For each subtask, define: dependencies on other subtasks (always present, even if "none"), files to create or modify (including test files for feature subtasks), what the subtask accomplishes and key decisions, test scenarios with specific inputs and expected outputs, how to verify it works.
5. Number subtasks as Parent.Subtask (1.1, 1.2, 2.1) for cross-referencing.

### Phase 3: Write Technical Plan

1. **Branch safety gate.** Before the first commit, check if on the default branch (`main`/`master`). If so, offer: A) Create a feature branch (recommended), B) Continue on default branch. This is a one-time check — once resolved, all subsequent commits in this session go to the chosen branch. Skip if brainstorming already handled this (i.e., already on a feature branch).
2. Create plan document using template in `references/tech-plan-template.md`.
3. Every subtask must meet the Plan Quality Bar above.
4. Reference actual file paths, existing patterns, and conventions from Phase 1.
5. Save to `docs/plans/YYYY-MM-DD-<topic>-tech-plan.md` (ensure directory exists).
6. **Commit the plan.** Don't leave it as an uncommitted change.

### Phase 4: Review and Handoff

1. Present an interactive choice to the user — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex): A) Review the plan (recommended), B) Start implementing, C) I'll take it from here (exit).
2. If review: invoke `plan-review` skill. Plan-review returns findings — tech-planning owns the fix loop.
3. Fix issues identified by plan-review. **Commit the updated plan.**
4. Present an interactive choice — see recommendation logic below: A) Another review round, B) Start implementing, C) I'll take it from here (exit).
5. Repeat steps 2-4 if user chooses another round.
6. If user chooses implementing: invoke `iterative:implementing` skill (implementing handles task creation internally after reading the plan).

**Recommendation logic for step 4.** Shift the recommended option based on what the review found:
- Review found HIGH issues (now fixed) → recommend **another review round** to verify the fixes landed well
- Review found only MEDIUM/LOW issues, or a round came back with no findings → recommend **start implementing** — further rounds will have diminishing returns
- After 3+ rounds → recommend **start implementing** regardless, and note that additional pass