---
name: planning-implementations
description: >-
  Use when a feature, refactor, or multi-file change needs to be designed before
  coding. Triggers: plan X, design the implementation, how should we build X,
  create an implementation plan.
---

# Planning Implementations

Produce a comprehensive, phased implementation plan grounded in actual codebase
research, with measurable success criteria and no unresolved decisions.

## Interaction mode

This skill leans **Collaborative** by default. For the full Collaborative-vs-Direct protocol and override rules, see the Interaction Modes reference in the `ai-research-workflows:using-research-workflows` skill.

## Starting the skill

If no topic is given, enter Collaborative mode and ask what to plan (and check
`docs/rse/specs/` (then legacy `.agents/`) for existing research/prior-art). If the topic is given without a
research doc, look for `docs/rse/specs/research-*.md` matches and suggest running
`ai-research-workflows:researching` first if none are found — then proceed on user
preference.

## Process

### Step 1: Context Gathering

- Read all mentioned files **completely** before anything else.
- Check `docs/rse/specs/research-*.md` (and legacy `.agents/research-*.md`, `.agents/prior-art-*.md`) for relevant context.
- Investigate related files, existing patterns, integration points, and test
  coverage in parallel where possible.
- Only ask questions that code cannot answer (product decisions, ambiguous
  scenarios). Never ask "which database?" — read the code.
- In Collaborative mode, present findings and focused questions before
  proceeding.

### Step 2: Research & Discovery

- Investigate in parallel: existing patterns, integration points, available
  dependencies, current test coverage.
- **Wait for all research to complete** before synthesizing.
- In Collaborative mode, present design options with pros/cons and a
  recommendation; get approval before continuing.

### Step 3: Plan Structure (Collaborative mode)

- Propose a phased breakdown with a one-line objective per phase.
- Get feedback before writing detailed steps.

### Step 4: Plan Writing

Generate filename from the topic slug (`plan-<slug>.md`). Read the template:
`assets/plan-template.md`.

**Required sections:**

1. Overview — what, why, high-level how
2. Current State Analysis — existing code with `file:line` references
3. Desired End State — observable success outcomes
4. What We're NOT Doing — explicit scope boundaries
5. Implementation Approach — technical strategy and key decisions
6. Implementation Phases — phased tasks with file paths and verification steps
7. Success Criteria — split into Automated and Manual (see below)
8. Testing Strategy — unit, integration, manual
9. References — research docs, files analyzed, external docs

Each phase needs: a clear objective, tasks with `path/to/file.ext:lines`,
dependencies on prior phases, and verification steps.

#### Bite-sized, test-first tasks

Each phase's tasks must be **executable steps an engineer can follow without
guessing**, sequenced test-first. Write the actual content, not a description:

- Sequence each unit of work as: write the failing test → run it, watch it fail
  → implement the minimal code → run the test, watch it pass → commit.
- Show the actual code or the exact command for any step that changes code or
  runs something — never a paraphrase.
- Reference an exact `path/to/file.ext:line` for every task.

(For numerical/research code, the "failing test" is an assertion against a known
result, analytic case, or invariant — see `ai-research-workflows:hardening-research-code`.)

#### Blocking rule: NO placeholders

A step that says *what* to do without showing *how* is a plan failure. Never
ship any of these — resolve each before saving:

- "TBD", "TODO", "implement later", "fill in details".
- "Add appropriate error handling" / "add validation" / "handle edge cases" —
  name the specific cases and show how each is handled.
- "Write tests for the above" without the actual test code.
- "Similar to Phase N" — repeat the code; phases may be executed out of order.
- Any reference to a type, function, or file not defined in some task.

#### Success Criteria split

**Automated Verification** — commands agents can run without human intervention
(`make test`, `pytest`, file-existence checks, linters).

**Manual Verification** — steps requiring human judgment (UI behavior, UX, edge
cases, performance under real conditions).

#### Blocking rule: NO open questions

If an uncertainty surfaces while writing, **stop**, then either research the
code to resolve it or ask the user. Resume only after it is resolved. A plan
section titled "Open Questions" with unresolved items is **not acceptable**.

### Step 5: Review & Iterate (Collaborative mode)

Present a summary (approach, phase count, criteria counts) and ask for feedback
on phasing, success criteria, technical approach, and edge cases.

For major revisions use the `ai-research-workflows:iterating-plans` skill.

## References and output

- Ground the plan in `docs/rse/specs/research-*.md` (and legacy `.agents/research-*.md`, `.agents/prior-art-*.md`);
  incorporate `docs/rse/specs/experiment-*.md` (or legacy `.agents/experiment-*.md`) when present.
- List all referenced docs in the References section with relative markdown links.
- Create `docs/rse/specs/` if needed; write to `docs/rse/specs/plan-<slug>.md`.
- To revise an existing plan use `ai-research-workflows:iterating-plans`; to execute use
  `ai-research-workflows:implementing-plans`.

## Common Mistakes

- **Confirming approach too late** — writing a detailed multi-phase plan before the user has approved the overall strategy wastes effort; in Collaborative mode, get approach sign-off after Step 2.
- **Placeholder tasks** — "add appropriate error handling", "write tests for the above", or any step that states intent without the concrete code/command is a plan the executor cannot follow; write the actual content.
- **Tests bolted on at the end** — lumping all tests into a trailing Testing Strategy section produces tests-last code; sequence tasks test-first (the failing test before the implementation) within each phase.
- **Vague success criteria** — "works well" or "passes tests" is not a criterion; every item must be a concrete, runnable command or an observable human-verifiable outcome.
- **Unsplit Automated vs Manual** — lumping all criteria together hides what requires human judgment; always separate the two categories explicitly.
- **Leaving open questions in the "final" plan** — a plan section titled "Open Questions" with unresolved items ships ambiguity to the implementer; resolve or explicitly defer every question before saving the plan.
- **Skipping scope boundaries** — omitting the "What We're NOT Doing" section lets scope creep in silently; fill it out even when the answer seems obvious.

## Quality checklist

Before completing the plan verify:

- [ ] All referenced files read completely
- [ ] All research completed and incorporated
- [ ] User consulted on approach and structure (Collaborative mode)
- [ ] Official template used
- [ ] Saved to `docs/rse/specs/plan-<slug>.md`
- [ ] Every phase has `file:line` references
- [ ] Phase tasks are bite-sized and test-first (failing test before implementation)
- [ ] No placeholder tasks ("add appropriate error handling", "write tests for the above", or intent-without-code)
- [ ] Success criteria split into Automated and Manual
- [ ] Criteria are measurable and concrete
- [ ] "What We're NOT Doing" section is filled out
- [ ] NO open questions remain
- [ ] References section links to research and experiment docs