Feature Planning

Plan features with a senior tech lead who challenges your scope, researches your codebase, and produces structured plans before any code is written.

When to use

Run /uc:feature-mode {description} when you're adding new functionality, making changes that touch multiple files, or working on something where you're unsure about the right approach. Feature mode is for work that benefits from upfront planning.

Not for small fixes. For bugs, use /uc:debug-mode. For library/pattern/market research, run /uc:research.

The 4-stage process

Feature mode follows a mandatory four-stage framework. No stage can be skipped. The full plan — tasks, files, success criteria — is written only in the final stage; the one exception is a lightweight plan skeleton (objective, scope, and an empty task list) scaffolded at the end of Stage 1 so the plan becomes visible on the dashboard the moment its scope is settled.

1. Understand

The AI challenges your feature request before accepting it. It asks "why?", splits vague requests into concrete pieces, identifies hidden complexity, surfaces edge cases, and proposes its own hypotheses about the right approach. This is a dialogue — the AI brings its perspective for you to react to, not just collects requirements. Once the scope is settled, the stage closes by scaffolding the plan skeleton — the plan now appears on the dashboard as "planning", advancing through a "Stage N of 4" indicator until it is approved.

2. Research

Agents survey your codebase and documentation in parallel, finding existing patterns, potential conflicts, and relevant architecture decisions. If external libraries are involved, the cache-first /uc:research skill fetches focused documentation and writes it to the project knowledge base under documentation/technology/research/.

3. Discuss

The AI synthesizes all findings and presents its perspective, including a proposed task breakdown with per-task file estimates, type (code or ops), and executor model (Sonnet / Opus / Fable — Fable needs your explicit approval, since it burns usage at roughly 2× Opus) — task boundaries and classifications are negotiated here, in conversation, before anything is written. You brainstorm the approach together. If the AI identifies genuine concerns, it pushes back — respectfully but firmly. The goal is convergence toward an approach you both believe in. The discussion flows naturally: every response ends with a one-line footer ("say 'proceed to plan' to move on, or keep discussing"), so there is no "are we done?" prompt after each message — you exit by saying so, whenever you're ready.

4. Write

The plan is written to documentation/plans/{NNN}-{name}/README.md with structured tasks. Each task has a description, file list, success criteria, and dependencies. The written plan is then up for review the same way the approach was in Discuss: ask questions, challenge task boundaries, request changes — each response ends with the same footer ("say 'approve' to approve the plan, or keep discussing"). Nothing executes until you explicitly say "approve"; casual agreement doesn't count.

Before that review opens, you're offered a second pair of eyes: a Fable agent that reads the finished plan in a fresh context — none of the planning conversation, only the files, plus the docs and code the plan stands on — and reports where it thinks the plan is wrong. It looks for the things that matter: the wrong solution to the problem, complexity the problem never demanded, an approach out of step with how the field actually solves this, performance it won't reach, business requirements the plan claims but doesn't satisfy. It's opt-in per plan, since Fable burns usage at roughly 2× Opus, and its findings are propositions — you decide which to fold in before you approve.

How scope challenge works

The AI acts as a Head of Technology who refuses to plan until scope is razor-sharp. It will:

  • Ask "why?" — understanding the problem before jumping to solutions
  • Split compound features — "add auth and user management" becomes two separate scoped items
  • Predict implementation challenges — based on experience, where will the real complexity hide?
  • Surface failure modes — what happens when things go wrong?
  • Flag dependencies — what could this break? What needs to exist first?

You'll be asked at least 3 questions before research begins. Even a detailed request makes these questions better, not unnecessary.

Task structure in plans

Each task in a plan is a complete vertical slice — database through API and UI, not split by tech layer. The plan README holds a flat task heading index only; each task's authoritative content lives in its own file at documentation/plans/{plan}/tasks/task-N/task.md. Each task.md includes:

  • Description — what to build
  • Product context — links to relevant product docs and requirements
  • Files — expected files to create or modify
  • Patterns — architecture and standards files the executor must follow
  • Research — per-task pointers to durable research files under documentation/technology/research/, populated from Stage 2's /uc:research results. Each pointer has a one-line "why this matters for this task" gloss.
  • Success criteria — numbered list of how to verify it's done
  • Dependencies — other tasks that must complete first

Task sizing targets ~10-40 files per task, and fewer, larger tasks is the explicit goal — every code task spins up a full Executor + Reviewer + Tester team (ops tasks run a solo Executor), so splitting costs real overhead. Fewer than 10 files gets absorbed into a larger task; more than 40 gets split along feature boundaries only. The proposed breakdown is presented during the Discuss stage (with per-task file estimates and merge justifications) so task boundaries are negotiated in conversation, then confirmed by a sizing gate before the plan is written. The final sizing table lands in the plan README and the approval summary, and any plan exceeding 4 tasks requires your explicit agreement to the split.

Why a separate file per task? During execution, every team member (Executor, Reviewer, Tester) reads its task's directory on startup. Keeping per-task content in dedicated files means spawn prompts carry no inline content, crash re-spawns reload context from disk with zero Lead intervention, and amendments are a simple file edit + broadcast instead of a mass message round-trip.

Stub plans from /uc:roadmap

If you've used /uc:roadmap to decompose your product, feature mode detects existing stub plans automatically. When a stub is found:

  • The scope boundary is already defined — the AI verifies and refines rather than discovering
  • Questions focus on implementation approach and technical decisions, not what to build
  • The stub's Out of Scope section is a hard boundary

What's next

After approving the plan, run /uc:plan-execution {plan-name} to execute it with coordinated agent teams.