riccardogrin/planning

Feature Planning

Create concrete, implementation-ready plans for features and complex changes.

DO NOT write code during planning. Only explore, research, analyze, and document. Be thorough.

Reference Files

| File | Read When | |------|-----------| | references/discovery-interview.md | Starting the discovery phase or need guidance on what questions to ask | | references/research-strategy.md | Planning external research or launching sub-agents for competitor/pattern research | | references/plan-templates.md | Constructing the plan or reviewing plan quality — contains worked examples |

Scope Check

Before deep planning, gauge the scope:

• Full planning: changes span 3+ files, cross system boundaries, have unclear requirements, or involve architectural tradeoffs
• Light planning: single-file changes with clear requirements — provide a brief execution outline instead of a full spec

For light planning, skip directly to a short outline: what file, what change, why.

Workflow

Phase 1: Discovery Interview

Conduct a thorough interview to surface requirements, constraints, and context the user may not have considered yet.

How to interview:

• Present questions with selectable options — don't ask open-ended questions when you can offer concrete choices
• Batch related questions together. Ask up to 4 independent questions at once, each displayed as its own tab with its own set of options. This reduces back-and-forth and respects the user's time
  • Each question should have a short label (the tab title) and 2-4 options with descriptions explaining tradeoffs
  • Allow multiple selections when choices aren't mutually exclusive
• When to batch: Group questions that are related but independent — answering one doesn't change the others. Example: "Auth method" + "Session storage" + "Token format" can be asked together
• When to ask separately: Ask one at a time when the answer to one question changes what you'd ask next
• Always include your recommendation as the first option (mark it as recommended)
• Skip questions the user has already answered
• Continue until there are no more meaningful questions or the user says they're done

What makes a good question:

• It surfaces a genuine ambiguity or tradeoff the user needs to decide
• It cannot be answered by reading the codebase or applying common sense
• It covers territory the user may not have considered

What makes a bad question:

• You could answer it yourself by reading package.json, the codebase, or the project's AGENTS/CLAUDE.md
• It asks for information the user already provided
• It's generic enough to apply to any project ("What framework are you using?")

If you can determine something from context, state your assumption and move on. Don't ask — inform.

Question domains (not exhaustive — use judgment):

• Problem definition and success criteria
• User-facing behavior and interaction design
• Edge cases, error states, and failure modes
• Performance, scale, and data implications
• Accessibility and internationalization concerns
• Security and privacy considerations
• Tradeoffs between approaches (with your recommendation)
• Migration and backwards-compatibility concerns
• Whether the plan will be executed via an autonomous loop (determines output format)

Read references/discovery-interview.md for detailed question categories and examples of strong vs weak questions.

Phase 2: Research

Go beyond the codebase. Not every plan needs this — skip when the feature is purely internal, the approach is well-established, or the user has provided sufficient context.

When to research:

• The feature involves user-facing patterns where conventions matter (forms, navigation, onboarding, dashboards, etc.)
• There are multiple viable technical approaches and the tradeoffs aren't obvious
• The user is building something they haven't built before
• Competitor or industry patterns would inform better decisions

What to research:

• Competitors and similar products — how do others solve this? What UX patterns are established?
• Technical approaches — what libraries, APIs, or architectural patterns apply? What are the tradeoffs?
• Design patterns — for UI features, what interaction patterns are standard? What accessibility requirements apply?

How to research:

• Launch sub-agents in parallel with focused research questions
• Each sub-agent gets one specific question, not a broad mandate
• Synthesize findings into actionable insights, not raw dumps

Read references/research-strategy.md for guidance on structuring research queries and synthesizing findings.

Phase 3: Codebase Analysis

Explore the codebase systematically. Use sub-agents for parallel exploration when the codebase is large or the feature touches multiple systems.

What to map:

• Relevant files — document paths (not line numbers — code shifts in multi-agent environments)
• Existing patterns — architecture, naming conventions, data flow, component structure
• Dependencies — what systems, files, or modules will be affected by this change
• Similar implementations — existing features that solve analogous problems, to maintain consistency
• Constraints — technical limitations, conventions from AGENTS.md or CLAUDE.md, framework constraints
• Operational context — git history, decision logs, known issues, and "except when" rules — tribal knowledge that doesn't live in code but affects how changes should be made

Document findings as:

• File: path/to/file.ext — what it does, how it's relevant
• Pattern: existing approach used for similar features
• Constraint: technical limitation, convention, or requirement

Phase 4: Plan Construction

Synthesize discovery, research, and analysis into an implementation-ready plan.

Describe outcomes, not mechanical steps. "Make the auth middleware reject expired tokens and return 401" beats "Add an if-statement checking token.exp against Date.now()." Specify what the change should achieve — let the implementer choose the approach.

For each change, specify:

• File path (not line numbers)
• What function, component, class, or section to modify
• What to achieve and how — be specific about the outcome
• Why this change serves the goal
• Dependencies — what must happen first
• Verification — how to confirm this specific change works (specific, observable behavior)

Structuring the plan:

• Flat list (default): Use for plans with ~4 or fewer changes concentrated in one area
• Phased grouping: Use when the plan has 5+ changes or spans multiple systems (data model, API, UI, etc.)
  • Each phase groups related changes that can be implemented and verified together
  • Phases are ordered by dependency — later phases build on earlier ones
  • Each phase should be safely re-runnable — if interrupted, the implementer can restart the current phase without corrupting previous work
  • Each phase ends with a brief validation checkpoint

Plan output format (flat list):

## Goal
[One sentence: what we're building and why]

## Research Insights
[Key findings from external research that informed the plan]
[Skip this section if no external research was done]

## Changes

### 1. [Description]
- **File**: `path/to/file.ext`
- **Target**: `functionName()` / `ComponentName` / relevant section
- **Action**: What specifically to add, modify, or remove
- **Reasoning**: Why this change is needed
- **Depends on**: What must happen first, or "Nothing"
- **Verify**: How to confirm this change works — specific, observable behavior

### 2. [Description]
...

## Edge Cases & Risks
- [Specific scenario and how the plan addresses it]
- [Risk and mitigation strategy]

## Validation
- [ ] Specific, testable acceptance criterion
- [ ] Another criterion
- [ ] Edge case X is handled

Plan output format (phased grouping):

## Goal
[One sentence: what we're building and why]

## Research Insights
[Key findings from external research that informed the plan]
[Skip this section if no external research was done]

## Phase 1: [Phase Name, e.g. "Data Model"]

### 1. [Description]
- **File**: `path/to/file.ext`
- **Target**: `functionName()` / `ComponentName` / relevant section
- **Action**: What specifically to add, modify, or remove
- **Reasoning**: Why this change is needed
- **Depends on**: What must happen first, or "Nothing"
- **Verify**: How to confirm this change works — specific, observable behavior

### 2. [Description]
...

**Checkpoint**: [How to verify this phase works before moving on]

## Phase 2: [Phase Name, e.g. "API Layer"]

### 3. [Description]
...

**Checkpoint**: [How to verify this phase works before moving on]

## Phase 3: [Phase Name, e.g. "UI"]

### 4. [Description]
...

**Checkpoint**: [How to verify this phase works before moving on]

## Edge Cases & Risks
- [Specific scenario and how the plan addresses it]
- [Risk and mitigation strategy]

## Validation
- [ ] Specific, testable acceptance criterion
- [ ] Another criterion
- [ ] Edge case X is handled

For complex features, include test descriptions in the Validation section: what test file, what test case name, and what it asserts.

For multi-session features, optionally add these sections to the plan:

• Progress: Checklist of phases/changes, marked as they're completed
• Decision Log: Implementation-time decisions that deviated from the original plan, with reasoning
• Open Questions: Anything discovered during implementation that needs revisiting

Keep the plan file updated as implementation proceeds — it becomes the source of truth.

Phase 4b: Loop-Ready Output (Optional)

If the user confirmed the plan will be executed via a loop (always ask about loop execution in Phase 1 — phrase it as an option: "Will you implement this via an autonomous loop?"):

1. Write the loop-ready file as IMPLEMENTATION_PLAN.md — always use this exact filename. Place it in the project root by default, or in the project's established plan directory (e.g., docs/plans/IMPLEMENTATION_PLAN.md) if one exists. Never use a custom or descriptive filename — the loop script searches for this exact name
2. Convert each change in the plan to a flat task:
   • - [ ] [Description] — [file path] — [brief approach]
3. Preserve phase ordering if the plan uses phased grouping
4. Each task must be completable in one loop iteration — split large changes if needed
5. Add a Goal section from the plan
6. Add empty Decision Log and Issues Found sections
7. Fold every bit of context a task needs directly into that task's line (and the ## Notes section). There is no separate plan document to point at — IMPLEMENTATION_PLAN.md must be fully self-contained
8. Note: the loop script detects completion by checking for ALL_TASKS_COMPLETE at the start of the file. Include a comment at the top of the generated plan: <!-- When all tasks are done, the loop agent prepends ALL_TASKS_COMPLETE above this line -->

There is only ever one plan file: IMPLEMENTATION_PLAN.md. It holds both the context and the executable task list. Never split the rich context into a second document (e.g. docs/plans/<feature>.md) and have the task list reference it — that produces two plan files, which is exactly what to avoid.

Agent capabilities: Do not assume art or asset tasks are human-only. Agents may have skills for sprite creation, image generation, or other asset work. Plan these as normal tasks — the implementing agent will check its available skills and attempt them. Only mark a task as requiring human input when it genuinely cannot be automated (e.g., subjective creative direction, licensing decisions).

Writing good Verify fields: Use type-appropriate checks so the implementing agent knows what to confirm beyond "does it build?" Common patterns:

• Asset tasks (images, icons, sprites): Verify quality standards (correct dimensions, transparency, format), remove placeholder/generated code, confirm keys/paths match config/data files
• Logic/data tasks: Verify content is logically consistent (e.g., labels make sense, relationships are valid, new entries have all required references), events/hooks are emitted and cleaned up
• UI tasks: Verify layering/z-index doesn't obscure existing UI, visual effects are noticeable (not too subtle), cleanup on unmount/teardown

Tasks that produce temporary placeholders should be marked Done (placeholder) with a follow-up task created immediately.

Persist the Plan

Write the completed plan to a single markdown file so it survives beyond this session.

Produce exactly one plan file, always named IMPLEMENTATION_PLAN.md. Never create a second plan document — no docs/plans/<feature>.md, no companion "full context" file, no descriptive filename like auth-refactor-plan.md or feature-roadmap.md. All context, structure, and tasks live in the one IMPLEMENTATION_PLAN.md. This exact filename is what the loop script and other tooling searches for, and keeping everything in one file is what keeps the plan clear.

• Place IMPLEMENTATION_PLAN.md in the project root by default
• If the project has an established plan directory (e.g., docs/plans/), place it there instead — but the filename must still be exactly IMPLEMENTATION_PLAN.md, and it remains the only plan file
• Format: The plan MUST use the structured format from the plan templates — with the specific sections (Goal, Changes/Phases, Edge Cases, Validation) and numbered changes with File/Target/Action/Verify fields. Never output a generic prose plan or Claude-style plan mode output. Every plan must have actionable structure, not walls of text
• The plan must be a standalone document — readable and actionable in a future session without conversation history. Since it is the only plan file, it cannot defer detail to anything else

This file is temporary. Once the work is fully implemented and audited, the user deletes IMPLEMENTATION_PLAN.md. So nothing in it is a long-term record. Any decision, constraint, rationale, or "why" that must outlive implementation has to be captured where it persists — concise but clear code comments and front matter at the point it's relevant — not left only in the plan. When writing the plan, flag durable knowledge (non-obvious rationale, business logic, gotchas, invariants) so the implementing agent knows to encode it in the code itself before the plan is discarded.

If an IMPLEMENTATION_PLAN.md already exists, do not overwrite or append to it without checking. Read it first. If it is already complete (all tasks done / superseded), it's safe to replace. But if it contains an unfinished plan — open tasks, partial progress — stop and ask the user how to proceed. Offer to write the new plan to a separate, distinctly-named file instead, e.g. [CUSTOM_NAME]_IMPLEMENTATION_PLAN.md (with a descriptive CUSTOM_NAME), so the in-progress plan is preserved. Note that loop tooling searches for the exact name IMPLEMENTATION_PLAN.md, so a custom-named file won't be picked up by the loop until renamed — surface this tradeoff when offering the option.

Phase 5: Spec Stress-Test

After constructing the plan, stress-test it with fresh perspectives. This catches blind spots, underspecified areas, and risks that confirmation bias hides.

Process (3 rounds):

For each round, spawn a Task subagent (subagent_type: "general-purpose") with:

• ONLY the plan text (the subagent has no conversation history — this is the point)
• The prompt: "You are reviewing a feature implementation plan. Find 5-10 points that are underspecified, ambiguous, risky, or missing. Be specific — reference the exact section and explain what's unclear or could go wrong. Don't suggest rewrites — just identify the gaps."

After each round:

1. Present the subagent's findings to the user
2. Ask which findings to address (some may be intentional simplifications)
3. Incorporate accepted feedback into the plan before the next round

When to skip:

• Light planning (single-file, clear scope)
• User explicitly says to skip refinement
• A subagent review turns up no issues

Key constraint: Each subagent must receive ONLY the plan document, not the conversation history. The value comes from fresh eyes with zero context about the decisions that led to the plan.

Phase 6: Plan Review

Before delivering the plan, verify:

• [ ] Someone could implement this without asking further questions
• [ ] Plan is self-contained — all context needed for implementation is in the plan, not just in conversation history
• [ ] Plan respects project conventions (from CLAUDE.md, AGENTS.md, or equivalent project config)
• [ ] File paths reference existing files or are plausible and consistent with the codebase structure
• [ ] Steps are ordered with clear dependency chains
• [ ] Acceptance criteria are specific and testable
• [ ] Every decision includes reasoning (the "why")
• [ ] No vague language — "update", "improve", "fix" always paired with specifics
• [ ] Research insights are incorporated where relevant
• [ ] Edge cases and risks are addressed

Anti-Patterns

| Avoid | Do Instead | |-------|------------| | "Update the authentication system" | "Modify auth/middleware.ts — add validateSession() that checks token expiry" | | "Add error handling" | "Wrap the API call in auth/api.ts with try/catch, show toast on error" | | "Use the standard pattern" | "Follow the existing pattern from user/dao.ts (class-based with explicit types)" | | "Make sure it works" | "Verify: (1) form submits on Enter, (2) inline errors display, (3) submit disabled during request" | | Asking "What framework do you use?" | Read package.json and state: "I see you're using Next.js with App Router" | | Specifying line numbers | Reference file path + function/component name | | Skipping research for novel features | Launch sub-agents to research competitor patterns and technical approaches | | Asking one question then moving on | Continue the interview until all meaningful questions are covered |