# Feature Planner > Upstream feature planning — requirement clarification, constraint discovery, design outline, vertical-slice task breakdown ordered by risk. Hands off to grill-with-docs and tdd. Use when starting new feature work from a vague request and no plan exists yet; if a plan or design already exists, use grill-with-docs to stress-test it instead. - Skill: `ralvarezdev/feature-planner` (Agent Skill) - Install (CLI): `npx skillmds@latest add ralvarezdev/feature-planner` - Raw SKILL.md: https://api.skillmd.com/api/skills/ralvarezdev/feature-planner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: ralvarezdev (https://skillmd.com/u/ralvarezdev) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ralvarezdev/feature-planner --- # Feature Planner The **first step** in the new-feature pipeline. Turns a vague request into a clarified requirement, a thought-through design, and an ordered list of vertical slices small enough to implement test-first. Hands off to [grill-with-docs](../grill-with-docs/SKILL.md) for stress-testing the plan, then to [tdd](../tdd/SKILL.md) for implementation. ## 1. When to invoke - User says "I want to build X", "let's add a feature for Y", "I'm starting on Z". - A request is vague enough that the right *shape* of the work isn't obvious. - A task is large enough that "just start coding" would lead to mid-flight rework. - The user explicitly asks for a plan, breakdown, or task list. If the work fits in one commit and the shape is obvious, **skip planning** and go straight to TDD. Plans pay back when the work is non-trivial. ## 2. The flow ``` Request → Requirement → Constraints → Design outline → Vertical-slice tasks ↓ ↓ ↓ ↓ ↓ "build X" what + why what's fixed shape + risks ordered, testable ``` Each step is a checkpoint with the user. Don't proceed to the next until the current one is confirmed. ## 3. Requirement clarification Distill the request into a one-paragraph description of *what* must be true after the work ships, and *why* it's worth shipping. Two paragraphs at most. Questions to ask before writing the requirement: - **Who is the user?** A human? Another service? A scheduled job? - **What outcome do they get?** Phrase as a present-tense fact: "the user can export their order history as CSV", not "we will build a CSV export feature". - **What's the success criterion?** How does the user (and you) know it's done? A test that fails today and passes when complete. - **What's explicitly out of scope?** Naming exclusions up front prevents scope creep mid-work. **Anti-pattern:** writing a requirement that's actually a design ("we'll add a `/export` endpoint that streams CSV from `users.orders`"). That's the design step; the requirement is what the user gets, not how. ## 4. Constraint discovery Constraints are everything the design must work *within*. Surface them now or they'll surprise you later. Ask the user (and check the code): - **Performance** — latency budgets, throughput, payload size limits. - **Compatibility** — clients on old versions, public API stability, backwards-compatible DB migrations. - **Security & compliance** — auth requirements, audit trails, PII handling, regulatory rules. - **Cost** — anything that bills per call (cloud APIs, LLM tokens, queue messages). - **Existing architecture** — what does this feature have to fit into? Read [CONTEXT.md](../grill-with-docs/CONTEXT.md) for the domain language, check `docs/adr/` for prior decisions ([improve-codebase-architecture §1](../../refactoring/improve-codebase-architecture/SKILL.md#1-glossary)). - **Team & timeline** — who owns the work, what's the deadline, what's the cost of being late. Record constraints in the plan, even if they're "no constraint" — explicit nothing beats implicit nothing. ## 5. Design outline A design outline is **not** a design document. It's a short description of: - **The shape** — where the new code lives (which module, which layer, which bounded context). Use the vocabulary from [hexagonal-arch](../../design/hexagonal-arch/SKILL.md) and [ddd-architect](../../design/ddd-architect/SKILL.md). - **The seams** — what new interfaces are introduced, what existing seams are crossed. One new port? One new adapter? An aggregate gains a method? - **The risks** — the parts you're least sure about. Name them. The first slice in the breakdown will tackle the highest-risk one. - **The alternatives considered** — what other shapes were possible, and why this one wins. Even a one-line "considered X, picked Y because Z" prevents the next person from re-litigating the choice. Skip patterns reflexively. The design isn't "Repository + Strategy + Decorator"; it's "the order intake module gains a `cancel()` method, which raises an `OrderCancelled` domain event, which the shipping module consumes." Pattern names are reached for *if and when* they earn it ([design-patterns §5](../../refactoring/design-patterns/SKILL.md#5-decision-rules)). ## 6. Task breakdown — vertical slices ordered by risk The critical step. Per [tdd's anti-horizontal-slicing rule](../tdd/SKILL.md#anti-pattern-horizontal-slices), break the work into **vertical slices**: each slice delivers one observable behavior end-to-end. Slice properties: - **Independently testable.** Each slice can be merged on its own without breaking what already exists. - **Small.** A slice should fit in one TDD red-green-refactor loop. If it takes a day, it's too big — split. - **Ordered by risk, not by layer.** The first slice tackles the *most uncertain* part of the design — proving the riskiest assumption first. If the riskiest part can't be made to work, you want to know on day one, not at integration. - **Ends in a real assertion.** Each slice's success criterion is a test that fails before the slice starts and passes when it's done. **Wrong (horizontal slicing — common, painful):** 1. Add the database migration. 2. Add the repository code. 3. Add the service code. 4. Add the HTTP handler. 5. Add the tests. **Right (vertical slicing):** 1. **Tracer bullet:** a stub endpoint returns a hardcoded response; one test passes end-to-end (proves the wire works). 2. **Riskiest assumption:** a single happy-path slice runs the real logic, hits the real DB, returns real data; one test. 3. **Edge case A** — one more test, the smallest amount of code to make it pass. 4. **Edge case B** — same. 5. **N. Refactor the now-duplicated bits** as the third occurrence appears ([logic-cleaner §6](../../refactoring/logic-cleaner/SKILL.md#6-duplication-rule-of-three)). ## 7. Output — the plan deliverable A plan is a short markdown document or a structured message the user can react to. Shape: ``` # Plan: ## Requirement ## Constraints - - ... ## Design outline - Shape: - New seams: - Risks: - Alternatives: <"considered X, picked Y because Z" — one line each> ## Tasks (vertical slices, in order) 1. 2. 3. 4. ... N. ``` Keep it tight. A plan that's longer than the code it describes is over-planning. ## 8. Hand-off The plan is the input to the next pipeline step: - **[grill-with-docs](../grill-with-docs/SKILL.md)** — stress-test each decision in the plan with questions. The grilling loop will surface gaps in constraints or risks that weren't obvious during planning. - **[ddd-architect](../../design/ddd-architect/SKILL.md)** — if the feature shapes the domain (new aggregate, new value object, new domain event), apply DDD discipline now. - **[hexagonal-arch](../../design/hexagonal-arch/SKILL.md)** — confirm port placement and dependency direction before the first slice. - **[tdd](../tdd/SKILL.md)** — implement each slice in red-green-refactor; never write all tests first. When the plan changes mid-implementation (and it will), **re-plan the remaining slices, don't continue with stale ones**. Sunk cost on a slice list is real but tiny compared to the cost of building the wrong thing. ## 9. When NOT to plan Planning earns its place when the work is non-trivial and the shape isn't obvious. Skip it for: - **Trivial changes** — a typo fix, a one-line config tweak, a bug fix with a known root cause. - **Exploratory spikes** — when you're learning whether a thing is possible. Spike, learn, discard, *then* plan the real implementation. - **Bug fixes with reproductions** — go straight to a failing test, then fix. - **Pure refactors** — those go through [code-design-refactor](../../refactoring/code-design-refactor/SKILL.md) or [improve-codebase-architecture](../../refactoring/improve-codebase-architecture/SKILL.md). Forcing a plan onto trivial work makes the planning process feel like ceremony and erodes trust in it. Save plans for when they pay back. ## 10. Cross-skill ties - [grill-with-docs](../grill-with-docs/SKILL.md) — next step in the pipeline; stress-tests the plan. - [ddd-architect](../../design/ddd-architect/SKILL.md) — domain-shaping decisions belong here, not in the requirement. - [hexagonal-arch](../../design/hexagonal-arch/SKILL.md) — seam decisions in the design outline. - [tdd](../tdd/SKILL.md) — vertical-slice principle inherited from here; implementation follows. - [improve-codebase-architecture](../../refactoring/improve-codebase-architecture/SKILL.md) — alternative entry point for *refactor* work (not new features); reads the codebase first. - [logic-cleaner](../../refactoring/logic-cleaner/SKILL.md) — rule-of-three justifies waiting on the refactor slice until duplication is real.