Imported from mopeyjellyfish/flywheel (plugins/fw/skills/plan/SKILL.md). Install upstream with npx skills add mopeyjellyfish/flywheel --skill plan. Copyright stays with the author.

Create Technical Plan

Use the actual current date from runtime context when dating plans and searching for recent documentation.

$fw:brainstorm defines WHAT to build. $fw:plan defines HOW to build it. $fw:work executes the plan only after the user explicitly approves that next step. A prior brainstorm is useful context but not required — planning can start from a requirements doc, a bug report, a feature idea, or a rough description.

When directly invoked, always plan. Never classify a direct invocation as "not a planning task" and exit the workflow. If the input is unclear, ask clarifying questions or use the planning bootstrap to establish enough context, but stay in planning.

This workflow produces a durable implementation plan. It is a read-only, collaborative stage. It does not implement code, run tests, or silently transition into execution-time work. After the plan file exists and the confidence check completes, it must run document-review on that plan and end with a user choice that explicitly offers $fw:deepen, review-finding follow-up, a pause, or starting $fw:work.

When planning starts from a requirements, spec, or design document whose review state is unknown, offer source document review before drafting the plan. Use that review to catch simplification, feasibility, scope, and supportability issues that should be resolved by questions or brainstorming before planning continues.

Interaction Method

Follow ../references/host-interaction-contract.md.

Call the exact host question tool named in ../references/host-interaction-contract.md when that tool is available. Do not ask for raw 1/2/3 replies when the host already offers a choice surface.

When the workflow spans multiple material steps, use the host task-tracking tool named in ../references/host-interaction-contract.md to create and maintain a short task list.

Ask one question at a time. Prefer concise single-select choices when natural options exist.

When multiple implementation or reliability postures are viable, present a short predicted choice list with the recommended label first and rely on the host's native freeform final path when it exists. When a planning question has a predictable answer space, prefer the same recommended-first portable option shape instead of a broad open-ended prompt.

Prefer to ask at least one targeted planning question when the answer would materially improve scope, sequencing, tradeoffs, or execution safety. Treat the user's answers and corrections as part of the planning record, not as throwaway chat.

Reference Loading Map

Do not load every reference file by default. Load only what the current phase needs:

Read references/universal-planning.md only when the task is clearly a non-software planning problem.
Read references/visual-communication.md only when the plan structure would materially benefit from a dependency graph, interaction diagram, or comparison table.
Read ../references/research/research-brief-contract.md when deciding whether a saved docs/research/ brief is fresh and in-scope enough to reuse.
Read ../references/research/activation-heuristics.md when deciding whether to reuse a saved brief, skip external research, or run targeted follow-up research.
Read ../references/research/source-ranking-and-synthesis.md when current external guidance, standards, or best practices materially affect the plan.
Read ../decision/SKILL.md when planning reveals an unresolved durable decision, existing decision-record conflict, or terminology conflict that would change the plan.
Read ../decision/references/decision-record-format.md only when the plan must review or cite a durable decision-record shape.
Read ../decision/references/context-format.md only when planning must read or update project context, glossary, or bounded-context terminology.
Read ../references/architecture-code-quality/activation-heuristics.md when deciding whether the work is architecture-bearing enough to need explicit boundary or pattern decisions.
Read ../references/architecture-code-quality/pattern-families.md when the plan must compare named patterns or architectural styles.
Read ../references/architecture-code-quality/output-contract.md when drafting Architecture and Pattern Decisions or equivalent specialist sections.
Read references/unit-examples.md only when drafting implementation units, choosing test posture, or repairing output that is drifting from the required unit schema.
Read references/issue-slice-export.md only when the user asks to create, export, or prepare issue-ready vertical slices from the plan.
Read references/deepening-workflow.md only when Phase 5.3 determines the plan should be strengthened after the first draft is written.
Read references/plan-handoff.md only after the plan file exists on disk and the confidence check is complete.
Read ../references/workflow-gates.md after the plan file exists and before presenting the final user choice.
Read ../observability/references/service-readiness-matrix.md only when the work changes runtime behavior, contracts, retries, queues, migrations, or other blast-radius-sensitive service boundaries.

Core Principles

Use requirements as the source of truth — if $fw:brainstorm produced a requirements document, planning should build from it rather than re-inventing behavior.
Decisions, not code — capture approach, boundaries, files, dependencies, risks, and test scenarios. Do not pre-write implementation code or shell choreography.
Research before structuring — explore the codebase, prior learnings, and external guidance when warranted before finalizing the plan.
Right-size the artifact — small work gets a compact plan. Large work gets more structure. The planning boundary stays the same.
Separate planning from execution discovery — resolve planning-time questions here. Explicitly defer execution-time unknowns to implementation.
Keep the plan portable — the plan should work as a durable document, review artifact, or issue body without embedding tool-specific executor instructions.
Keep planning approval-gated — a plan should be understandable enough for the user to review what will be worked on before work begins.
Plan vertical behavior slices by default — implementation units should each deliver one coherent user-facing, workflow-facing, API-facing, or contract-facing outcome through the necessary code, tests, docs, evals, and supporting artifacts. Horizontal units such as "write all tests," "edit all service files," "update all docs," or "refresh all generated artifacts" are allowed only for true prerequisites, mechanical sweeps, or final reconciliation, and must be marked as exceptions with a reason.
Default behavior changes to TDD — feature work, bug fixes, public contract changes, regression-prone paths, and behavior-preserving refactors must plan a tdd posture unless an explicit exception applies. Use characterization for fragile existing behavior that must be pinned first, and no-new-tests only for generated, configuration-only, documentation- only, trivial mechanical, or otherwise disproportionate units. State the exception and verification path whenever the unit is not tdd.
Plan the testing strategy, not just the code changes — every software plan should state how new or changed behavior will be tested, which existing test idioms to follow, whether to extend current tests or add new ones, and which public contracts must stay protected. Exact test or coverage commands belong to the host project's instructions or $fw:work, not the plan. When TDD fits, each material hypothesis should map to a concrete red signal and a green completion signal.
Make runtime tradeoffs explicit — when a plan changes retries, fallbacks, queue behavior, health checks, or other operationally meaningful boundaries, present the current repo truth, likely failure modes, blast radius, viable options, and the recommended posture.
Make architecture and pattern choices explicit when warranted — when the work changes boundaries, ownership, named patterns, or distributed posture, record the chosen option, rejected alternatives, and the clean-code constraints work must preserve.
Prefer reusable research to redundant reruns — match fresh docs/research/ briefs first, then run only the narrow follow-up research needed to close planning gaps. Fold the decision-changing findings and recommendation into plan decisions instead of creating a side report by default.
Honor durable context and decisions — when the work is domain, boundary, architecture, workflow-contract, or terminology bearing, search existing context and decision records before finalizing the plan. Surface contradictions as open decisions or route to decision; do not silently overwrite settled project language or choices.

Plan Quality Bar

Every plan should contain:

a clear problem frame and scope boundary
concrete requirements traceability back to the request or origin document
repo-relative file paths for the proposed work
explicit test file paths for feature-bearing implementation units
decisions with rationale, not just tasks
relevant context and decision records, or an explicit note that none were found or needed
existing patterns or code references to follow
implementation units that are atomic enough to map cleanly to execution tasks and likely commit boundaries
implementation units organized as vertical behavior slices by default, with any horizontal prerequisite, mechanical sweep, or reconciliation unit explicitly justified
per implementation unit, an explicit test posture chosen from tdd, characterization, or no-new-tests, with a brief reason
per implementation unit, an explicit execution mode chosen from serial or parallel-ready, with a brief reason
an explicit testing strategy that defaults behavior-bearing work to TDD, aligns with AGENTS.md, CLAUDE.md, and local testing references when present, and assumes repo tooling exists even when command discovery is deferred
for tdd units, 1-3 material hypotheses with explicit red and green proof points grounded in existing or new tests
clear public-contract coverage for any changed user-facing, API, CLI, schema, event, or integration behavior
enumerated test scenarios for each feature-bearing unit
clear dependencies and sequencing
for architecture-bearing work, an explicit Architecture and Pattern Decisions section or equivalent that names current repo truth, candidate options, the chosen direction, rejected lighter/heavier options, and clean- code constraints for execution
for runtime-risky work, an explicit decision surface covering current behavior, top failure modes, blast radius, viable options, and the chosen recommendation
for runtime-risky work, explicit coverage of the applicable service-readiness dimensions: contracts, state, failure modes, observability, rollout, recovery, and validation ownership
enough detail that the next agent or human can start without rediscovering the project's testing posture or file-level patterns

A plan is ready when an implementer can start confidently without needing the plan to write the code for them, and when the user can review what execution would do before deciding whether to $fw:deepen the plan or start $fw:work. The handoff should also make it easy for the user to see what changed during planning, what remains open, what the review pass found, and what execution would start with.

Feature Description

<feature_description> #$ARGUMENTS </feature_description>

If the feature description above is empty, ask the user: "What would you like to plan? Describe the task, goal, or project you have in mind."

If the input is present but unclear or underspecified, do not abandon the workflow. Ask one or two clarifying questions, or use the planning bootstrap to establish enough structure.

IMPORTANT: All file references in the plan document must use repo-relative paths such as src/models/user.rb, never absolute paths.

Workflow

Phase 0: Resume, Source, and Scope

0.1 Resume Existing Plan Work When Appropriate

If the user references an existing plan file or there is an obvious recent matching plan in docs/plans/:

read it
confirm whether to update it in place or create a new plan
if updating, preserve completed checkboxes and revise only the still-relevant sections

Deepen intent: The word "deepen" in reference to a plan is the primary trigger for the deepening fast path. When the user says "deepen the plan", "deepen my plan", or "run a deepening pass", the target document is a plan in docs/plans/, not a requirements document.

Words like "strengthen", "confidence", "gaps", and "rigor" are not enough on their own to trigger a holistic deepening pass. Prefer to confirm before entering the fast path unless the user clearly targeted the plan as a whole.

Once the plan is identified and appears complete:

if the plan lacks YAML frontmatter, route to references/universal-planning.md for editing or deepening instead of the software deepening flow
otherwise short-circuit to Phase 5.3 in interactive mode

Normal editing requests should not trigger the fast path.

0.1b Classify Task Domain

If the task involves building, modifying, or architecting software, continue.

If the task is a non-software multi-step goal worth planning, read references/universal-planning.md and follow that workflow instead.

If the task is genuinely ambiguous, ask before routing.

For quick help, factual lookups, or single-step tasks, only skip the planning workflow when this skill was auto-selected rather than directly invoked.

0.2 Find Upstream Requirements Document

Before asking planning questions, search docs/brainstorms/ for files matching *-requirements.md.

Treat a requirements document as relevant when:

the topic semantically matches the feature description
it appears to cover the same user problem or scope
it is recent enough to still be trustworthy, unless the content is obviously still current or obviously stale

If multiple source documents match, ask which one to use.

0.3 Use the Source Document as Primary Input

If a relevant requirements document exists:

read it thoroughly
announce that it will serve as the origin document for planning
carry forward:
- problem frame
- requirements and success criteria
- scope boundaries
- key decisions and rationale
- dependencies or assumptions
- outstanding questions, preserving whether they are blocking or deferred
use it as the primary input to planning and research
reference important carried-forward decisions in the plan with (see origin: <source-path>)
do not silently omit source content

If no relevant requirements document exists, planning may proceed from the user's request directly.

0.4 Planning Bootstrap

If no relevant requirements document exists, or the input needs more structure:

assess whether the request is already clear enough for direct technical planning
if the ambiguity is mainly product framing, user behavior, or scope definition, recommend $fw:brainstorm as a suggestion — but still offer to continue planning here
if the user wants to continue here, establish:
- problem frame
- intended behavior
- scope boundaries and obvious non-goals
- success criteria
- blocking questions or assumptions

Keep the bootstrap brief.

If major product questions remain unresolved:

recommend $fw:brainstorm again
if the user still wants to continue, require explicit assumptions before proceeding

If the request turns out to be a symptom without a known root cause, say so clearly and do a brief investigation first rather than pretending planning can start responsibly. If the issue is already understood and the fix is obvious, suggest $fw:work as a faster alternative while still allowing planning.

0.5 Classify Outstanding Questions Before Planning

If the origin document contains Resolve Before Planning or similar blockers:

review each one
reclassify it into planning-owned work only if it is actually a technical, architectural, or research question
keep it as a blocker if it would change product behavior, scope, or success criteria

If true product blockers remain:

surface them clearly
call the host question tool:
1. Resume $fw:brainstorm (Recommended) - resolve behavior, scope, or success criteria before planning
2. Continue with assumptions - convert each blocker into an explicit assumption or decision, then continue planning

Do not continue planning while true blockers remain unresolved.

0.6 Offer Source Document Review Before Planning

If the primary input is a requirements, spec, or design document and it was not just reviewed in the current session, ask:

Review the source document before planning?

Call the host question tool with a portable 2-3 option menu:

Review first (Recommended) - run document-review on the source document to find simplification, feasibility, scope, and supportability issues before drafting the implementation plan
Continue planning - draft the plan from the current document and capture any uncertainty as explicit assumptions or deferred planning questions
Return to brainstorm - resolve product or scope questions before planning; include this option only when the source document has material ambiguity

Skip the prompt only when the document was already reviewed in this session, the document contains clear recent review evidence, or the user explicitly asks to plan without another review.

If the user chooses review first, run document-review on the source document. Use mode:headless in automated or pipeline contexts. After review:

route product behavior, scope, success criteria, or definition-of-done findings back to $fw:brainstorm or explicit user questions before planning
carry technical feasibility, sequencing, validation, rollout, and supportability findings into the plan as constraints or implementation units
if residual P0 or P1 findings remain, ask whether to resolve them first or continue with explicit assumptions before drafting the plan

0.7 Assess Plan Depth

Classify the work into one of these depths:

Lightweight — small, well-bounded, low ambiguity
Standard — normal feature or bounded refactor with some technical decisions to document
Deep — cross-cutting, strategic, high-risk, or highly ambiguous work

If depth is unclear, ask one targeted question and then continue.

Phase 1: Gather Context

1.1 Local Research (Always Runs)

Build a concise planning context summary:

if an origin document exists, summarize its problem frame, requirements, and key decisions
otherwise use the feature description directly

Always do local research:

inspect relevant parts of the codebase
identify technology, architecture, patterns, and likely touched files
read AGENTS.md and CLAUDE.md guidance when present and when it materially affects the plan, especially testing methodology, workflow expectations, and project idioms
inspect nearby tests, helpers, fixtures, and naming patterns for the target area so the plan can say whether to extend existing coverage or create new tests
read relevant entries from the active repo's docs/solutions/ or other durable learnings when they exist; search solution frontmatter by files_touched, module, tags, problem_type, component, and title before reading full docs. Prefer doc_status: active and follow superseded_by when present
when the active repo has docs/research/, search that local store by frontmatter and title before broad external research; match on topic, keywords, reuse_targets, and title. Prefer matching fresh briefs whose reuse_targets include plan, and use freshness_basis plus reuse_targets to decide whether they still fit

When the platform supports delegated or parallel bounded research and policy allows it, you may split local research into small focused passes, for example:

repo patterns and touched files
prior learnings or solutions
architecture and blast radius

If such delegation is unavailable, do the equivalent work directly.

Slack context is opt-in. If Slack tools exist and the user asked for them, gather organizational context. If tools exist but the user did not ask, note that Slack context is available on request.

When the work is runtime-risky, read ../observability/references/service-readiness-matrix.md and capture only the dimensions that materially apply to this change. Do not force a full matrix when the change is local and low-blast-radius.

1.1b Detect Execution Posture Signals

Decide whether the plan should carry a lightweight execution posture signal. Default to TDD for behavior-bearing units. Use another posture only when the change is generated, configuration-only, documentation-only, mechanical, styling/text-only with no unit-testable behavior, characterization-first, or not reasonably testable at planning time.

For each implementation unit, choose exactly one test posture:

tdd — use when the unit changes externally observable behavior, a public contract, a bug fix, a regression-prone code path, or a behavior-preserving refactor that is reasonably testable now. This posture requires explicit red and green proof points and tells $fw:work to load the tdd skill before implementation.
characterization — use when the first planning need is to lock current behavior in a fragile, legacy, or poorly understood area before changing it. State what behavior must be pinned and why a test-first failing proof point is not the right first move for that unit.
no-new-tests — use only for configuration-only, mechanical, generated, documentation-adjacent, or otherwise disproportionate work. State why new tests are not warranted and how completion will still be verified.

Look for:

repo instructions already prescribing TDD or another testing flow
explicit TDD or test-first requests
feature work, bug fixes, public contract changes, or refactors where a red-green-refactor loop will improve quality
characterization-first needs in fragile or legacy areas
configuration-only or infrastructure-only edits with little direct behavioral surface
repo instructions or durable references that prescribe testing methodology or test layering
repo context showing the target area is historically brittle or weakly tested

When the signal is clear, carry it forward explicitly in relevant implementation units and summarize the overall posture mix in ## Testing Strategy. Ask the user only if the posture would materially change sequencing or risk and cannot be responsibly inferred.

Do not turn this into exact command choreography. If test or coverage tooling is not already documented in repo instructions, assume it exists and let $fw:work discover the concrete command path during execution.

When TDD fits, frame the work as a red -> green -> refactor loop at plan level:

identify the existing or new test that should fail first
identify the passing condition that proves the unit is complete
keep the plan at the level of proof points, not literal coding steps
usually capture 1-3 material hypotheses per unit, not every trivial assertion

A material hypothesis is one externally observable behavior, contract change, or regression risk worth proving. Do not explode this into line-by-line assertions or every branch-level detail.

1.2 Decide on External Research

Before deciding to browse broadly, check whether a matching saved research brief already covers the topic. Treat a fresh matching brief as the default external-context input for planning. If the brief is stale or only partially answers the question, keep it as context and decide whether targeted follow-up research is needed rather than restarting the topic from zero.

Based on the origin document, user signals, local findings, and any saved research brief, decide whether external research or targeted follow-up research adds value.

Lean toward external research or targeted follow-up research when:

the topic is high-risk: security, payments, privacy, external APIs, migrations, compliance
the codebase lacks relevant local patterns
local patterns exist only in adjacent domains, not the exact one being planned
the user is exploring unfamiliar territory
a saved brief exists but freshness or one open thread still needs a narrow update

Skip external research when:

the codebase already shows strong direct local patterns
the user already knows the intended shape
additional external context would add little practical value
a matching fresh brief already covers the current-practice questions

Announce the decision briefly before continuing.

1.3 External Research (Conditional)

If external research is useful, gather only the smallest set of sources that materially improve the plan or close the unresolved gap from a saved brief. Prefer official docs and primary sources for technical questions. Parallelize independent research threads only when policy and tools allow it.

1.4 Consolidate Research

Summarize:

relevant codebase patterns and file paths
relevant testing idioms, fixtures, helpers, and contract-test patterns
relevant institutional learnings
matching saved research briefs, their freshness basis, and any targeted follow-up that refreshed or narrowed them
organizational context from Slack, if gathered
external references and best practices, if gathered
the recommendation-bearing takeaway those research inputs imply for the plan
related issues, PRs, or prior art
constraints that materially shape the plan

1.4b Reclassify Depth When Research Reveals External Contract Surfaces

If the current classification is Lightweight and research shows that the work touches external contract surfaces, reclassify to Standard.

Examples:

environment variables consumed externally
exported public APIs or CLI flags
CI/CD configuration files
shared interfaces consumed downstream
documentation or workflows linked externally

1.5 Flow and Edge-Case Analysis (Conditional)

For Standard or Deep plans, or when flow completeness is still unclear:

identify missing edge cases, state transitions, and handoff gaps
tighten requirements trace and verification strategy
add only the flow details that materially improve the plan

If the platform supports a specialist analysis pass and policy allows it, you may use one. Otherwise perform the analysis directly.

Phase 2: Resolve Planning Questions

Build a planning question list from:

deferred questions in the origin document
gaps discovered in repo or external research
technical decisions required to produce a useful plan

For each question, decide whether it should be:

resolved during planning — knowable from repo context, documentation, or user choice
deferred to implementation — depends on code changes, runtime behavior, or execution-time discovery

Ask the user only when the answer materially affects architecture, scope, sequencing, or risk and cannot be responsibly inferred.

Do not run tests, build the app, or probe runtime behavior in this phase.

Phase 3: Structure the Plan

3.1 Title and File Naming

draft a clear, searchable title such as feat: Add user authentication
determine the plan type: feat, fix, or refactor
build the filename using: docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
create docs/plans/ if it does not exist
determine the next sequence number for that date
keep the descriptive name concise and kebab-cased

3.2 Stakeholder and Impact Awareness

For Standard or Deep plans, briefly consider who is affected — end users, developers, operations, or other teams — and reflect that where useful in System-Wide Impact.

3.3 Break Work into Implementation Units

Break the work into logical implementation units. Each unit should usually be a meaningful change an implementer could land as an atomic commit and track as one execution task.

Good units are:

focused on one component, behavior, or integration seam
usually touching a small related file cluster
ordered by dependency
small enough that execution can track them one-for-one in the host task tool
independent enough that sibling units can be marked parallel-ready only when their write sets and reasoning truly do not collide
concrete enough for execution without pre-writing code
checkable with - [ ] syntax

Avoid:

micro-steps
units spanning unrelated concerns
units that hide multiple independently completable changes behind one checkbox
units that almost certainly require shared-write reconciliation but still pretend to be parallel-safe
units so vague an implementer still has to invent the plan

3.4 High-Level Technical Design (Optional)

Before detailing units, decide whether an overview would help a reviewer validate the intended approach.

Use the medium that best fits the work:

Work involves...	Best overview form
DSL or API surface design	Pseudo-code grammar or contract sketch
Multi-component integration	Mermaid sequence or component diagram
Data pipeline or transformation	Data flow sketch
State-heavy lifecycle	State diagram
Complex branching logic	Flowchart
Mode/flag combinations or multi-input behavior	Decision matrix
Single-component with non-obvious shape	Pseudo-code sketch

Frame every sketch with:

This illustrates the intended approach and is directional guidance for review, not implementation specification.

Keep sketches concise.

3.4b Output Structure (Optional)

For greenfield plans that create a new directory structure, include an ## Output Structure section when the layout itself is a meaningful design decision.

Skip it when:

the plan only modifies existing files
only 1-2 files are created in an existing directory

3.5 Define Each Implementation Unit

For each unit, include:

Vertical slice — the behavior, workflow contract, API contract, or user outcome delivered end to end by this unit; for a horizontal exception, name it as horizontal exception and explain why it cannot be a vertical slice
Goal
Requirements
Dependencies
Execution mode — exactly one of serial or parallel-ready, with a brief reason
Files — repo-relative file paths to create, modify, or test
Test posture — exactly one of tdd, characterization, or no-new-tests, with a brief reason
Approach
Execution note — optional sequencing or rollout note; do not use this to restate the test posture
Technical design — optional when the unit's approach is non-obvious
Patterns to follow
Test scenarios — specific cases right-sized to complexity and risk
Red signal — for TDD-appropriate work, the failing test or assertion that should go red before implementation
Green signal — for TDD-appropriate work, the passing condition that gives the worker ground truth that the unit is complete
Verification — observable outcomes, not shell scripts

Feature-bearing units and other materially testable code changes should include test file paths in **Files:**.

Use Execution mode deliberately:

serial — keep the unit ordered or inline even if the file list looks small, because it establishes shared decisions, touches cross-cutting seams, or is otherwise not a good parallel batch candidate
parallel-ready — the unit is intentionally bounded so $fw:work may consider it for concurrent execution after dependencies are satisfied and a fresh shared-write safety check passes

Default to serial unless the unit is genuinely independent enough that later execution should not have to infer that posture from scattered hints.

For TDD-appropriate units, every meaningful hypothesis should be anchored to an existing or new test that can fail before the code change and pass after it. The goal is to give the worker a concrete truth source for completion, not just generic coverage intent.

Use the testing fields distinctly:

Test scenarios — the behaviors or cases the unit must cover
for no-new-tests units with no behavioral surface, use n/a -- [reason]
Red signal — the failing test or assertion that proves the work is not done yet; required for tdd, omitted or marked n/a otherwise
Green signal — the passing condition that proves the primary hypothesis is satisfied; required for tdd, omitted or marked n/a otherwise
Verification — only additional evidence beyond the main proof point; use none when the green signal is sufficient

Do not copy the same sentence into all four fields.

Use vertical slices as the default unit boundary:

a slice should include the production changes, tests, docs, config, migrations, generated artifacts, and proof needed for that one behavior when those artifacts are in scope
do not create one unit for all tests, another for all implementation, and a final unit for all docs, configs, migrations, or generated artifacts
do not split by layer, file type, package, or artifact type unless the work is genuinely mechanical or preparatory
when a prerequisite or reconciliation unit is unavoidable, mark it clearly as a horizontal exception and keep it serial unless repo truth proves it can run independently

For TDD units, the vertical slice should map to the first observable behavior or tracer bullet that $fw:work can take red, green, and then refactor before moving to the next slice.

If the output starts drifting from this schema, stop and read references/unit-examples.md before continuing.

When a unit changes a public contract, call that out explicitly in the **Approach:**, **Test scenarios:**, or both. Public contracts include user-facing behavior, request/response shapes, exported APIs, CLI flags, event payloads, schema-visible behavior, and integration boundaries consumed by other systems.

Use Execution note sparingly. Use Execution mode precisely. parallel-ready is permission for bounded concurrent execution later, not a vague hope that parallelism might work out.

Do not turn units into verbose process theater. When TDD fits, capture the red and green proof points without spelling out full coding choreography.

3.6 Keep Planning-Time and Implementation-Time Unknowns Separate

If something matters but is not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it now.

Phase 4: Write the Plan

Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution.

4.1 Plan Depth Guidance

Lightweight

keep the plan compact
usually 2-4 units
omit optional sections that add little value

Standard

use the full core template, omitting optional sections that add no value
usually 3-6 units
include risks, deferred questions, and system-wide impact when relevant

Deep

use the full core template plus optional analysis sections where warranted
usually 4-8 units
group units into phases when that improves clarity

4.1b Optional Deep Plan Extensions

For sufficiently large, risky, or cross-cutting work, add only the sections that genuinely help:

Alternative Approaches Considered
Success Metrics
Dependencies / Prerequisites
Risk Analysis & Mitigation
Phased Delivery
Documentation Plan
Operational / Rollout Notes
Future Considerations only when they materially affect current design

4.2 Core Plan Template

Omit clearly inapplicable optional sections, especially for Lightweight plans.

---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # include when planning from a requirements doc
deepened: YYYY-MM-DD  # optional, set when the confidence check substantively strengthens the plan
---

# [Plan Title]

## Overview

[What is changing and why]

## Problem Frame

[Summarize the user/business problem and context. Reference the origin doc when present.]

## Requirements Trace

- R1. [Requirement or success criterion this plan must satisfy]
- R2. [Requirement or success criterion this plan must satisfy]

## Scope Boundaries

- [Explicit non-goal or exclusion]

### Deferred to Separate Tasks

- [Work that will be done separately]: [Where or when]

## Context & Research

### Relevant Code and Patterns

- [Existing file, class, component, or pattern to follow]

### Institutional Learnings

- [Relevant active-repo `docs/solutions/` insight]

### Saved Research Briefs

- [Relevant `docs/research/` brief, freshness basis, and why it still applies]

### External References

- [Relevant external docs or best-practice source, if used]

## Key Technical Decisions

- [Decision]: [Rationale]

## Testing Strategy

- **Project testing idioms:** [What `AGENTS.md`, `CLAUDE.md`, local tests, or
  durable refs say to follow]
- **Posture selection rule:** [Per unit choose exactly one of `tdd`,
  `characterization`, or `no-new-tests`, and use repo context to justify it]
- **Plan-level posture mix:** [Briefly summarize which units are expected to use
  `tdd`, `characterization`, and `no-new-tests`, and why that split fits this
  plan]
- **Material hypotheses:** [For each `tdd` unit, identify 1-3 externally
  observable behaviors, contract changes, or regression risks worth proving]
- **Red -> green proof points:** [For each TDD-appropriate unit, name the
  existing or new failing test to start from and the passing condition that
  proves the hypothesis]
- **Tooling assumption:** [Assume repo test and coverage tooling exists. Use
  documented project instructions when present; otherwise let `$fw:work`
  discover the concrete commands]
- **Public contracts to protect:** [User-facing flows, APIs, CLI flags, event
  payloads, schema-visible behavior, integrations]
- **Primary test surfaces:** [Which suites, layers, or file clusters should
  carry the coverage]
- **Test patterns to mirror:** [Existing tests, helpers, fixtures, factories,
  or support utilities to extend]

## Dependencies And Parallelism

- **Critical path:** [Unit 1 -> Unit 3 -> Unit 4, or `straight-line`]
- **Parallel-ready sets:** [After Unit 1, Units 2 and 3 may run in parallel, or
  `none`]
- **Serial-only units:** [Units that must stay ordered because they establish
  shared seams, reconcile prior edits, or otherwise should not be batched]

## Open Questions

### Resolved During Planning

- [Question]: [Resolution]

### Deferred to Implementation

- [Question or unknown]: [Why it is intentionally deferred]

## Output Structure

    [directory tree showing new directories and files]

## High-Level Technical Design

> *This illustrates the intended approach and is directional guidance for review, not implementation specification.*

[Pseudo-code grammar, Mermaid diagram, data flow sketch, or state diagram]

## Implementation Units

- [ ] **Unit 1: [Name]**

**Vertical slice:** [Behavior, workflow contract, API contract, or user outcome
delivered end to end; or `horizontal exception` with reason]

**Goal:** [What this unit accomplishes]

**Requirements:** [R1, R2]

**Dependencies:** [None / Unit 1 / external prerequisite]

**Execution mode:** [`serial` | `parallel-ready`] -- [one-sentence reason]

**Files:**
- Create: `path/to/new_file`
- Modify: `path/to/existing_file`
- Test: `path/to/test_file`

**Test posture:** [`tdd` | `characterization` | `no-new-tests`] -- [one-sentence reason]

**Approach:**
- [Key design or sequencing decision]

**Execution note:** [Optional sequencing or rollout note; do not repeat test posture]

**Technical design:** *(optional -- directional guidance, not implementation specification)*

**Patterns to follow:**
- [Existing file, class, or pattern]

**Test scenarios:**
- [Specific input/action -> expected outcome, or `n/a -- [reason]` for a true
  `no-new-tests` unit]

**Red signal:** [Required for `tdd`: existing or new test/assertion expected to
fail before implementation. Otherwise `n/a -- [reason]`]

**Green signal:** [Required for `tdd`: that same test/assertion or contract
check passes when this unit is implemented correctly. Otherwise `n/a -- [reason]`]

**Verification:**
- [Additional evidence beyond the main proof point, or `none` when the green
  signal is sufficient]

## System-Wide Impact

- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
- **Error propagation:** [How failures should travel across layers]
- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
- **API surface parity:** [Other interfaces that may require the same change]
- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
- **Unchanged invariants:** [Existing behaviors this plan explicitly does not change]

## Risks & Dependencies

| Risk | Mitigation |
|------|------------|
| [Meaningful risk] | [How it is addressed or accepted] |

## Documentation / Operational Notes

- [Docs, rollout, monitoring, or support impacts when relevant]

## Sources & References

- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
- Saved research: [docs/research/YYYY-MM-DD-<topic>-research.md](path)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]

4.3 Planning Rules

all file paths must be repo-relative
prefer path plus class, component, or pattern references over brittle line numbers
keep units checkable with - [ ]
shape units so $fw:work can map them directly onto host task items instead of inventing a second execution breakdown
do not include implementation code
pseudo-code sketches and Mermaid diagrams are allowed when they communicate design direction
do not include git commands, commit messages, or exact test command recipes
do not pretend execution-time questions are settled just to make the plan look complete

4.4 Visual Communication in Plan Documents

When the plan contains:

4+ implementation units with non-linear dependencies
3+ interacting surfaces in System-Wide Impact
3+ behavioral modes or variants in Overview or Problem Frame
3+ interacting decisions or alternatives

read references/visual-communication.md.

Phase 5: Final Review, Write File, and Handoff

5.1 Review Before Writing

Before finalizing, check:

the plan does not invent product behavior that should have been defined in $fw:brainstorm
if there was no origin document, the planning bootstrap established enough product clarity to plan responsibly
every major decision is grounded in the origin document or research
when a saved research brief or follow-up research shaped the plan, freshness, source scope, and reuse boundaries stay explicit, and repo truth remains distinct from external guidance
the testing strategy reflects AGENTS.md, CLAUDE.md, local test patterns, and any durable testing references when present
the testing strategy defines per-unit posture choices using exactly tdd, characterization, or no-new-tests
the testing strategy defaults behavior-bearing units to TDD, and records explicit exceptions where that is not the right posture
tdd units define 1-3 material hypotheses rather than a vague or bloated proof-point list
TDD-appropriate units provide clear red and green proof points so the worker has a concrete completion signal
implementation units are atomic enough to map cleanly to host-tracked execution tasks and likely commit boundaries
each unit's Execution mode is explicit, justified, and consistent with its dependencies and likely file overlap
the first serial unit or first eligible parallel-ready batch is obvious from the plan when mixed execution modes exist
Test scenarios, Red signal, Green signal, and Verification are distinct rather than duplicated
each implementation unit is concrete, dependency-ordered, and ready for execution
changed public contracts are matched to explicit coverage expectations
test scenarios are specific and complete enough for the unit's risk profile
the plan contains enough detail for the next implementer to start without re-deriving the project's testing approach
the plan does not hardcode exact test or coverage command recipes that belong in repo instructions or $fw:work
deferred items are explicit and not hidden as fake certainty
any high-level technical design is directional rather than copy-paste-ready
if the plan originated from a requirements document, every meaningful section of the origin document is addressed

5.2 Write Plan File

REQUIRED: Write the plan file to disk before presenting any options.

Save the complete plan to:

docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md

Confirm:

Plan written to docs/plans/[filename]

In automated or pipeline contexts, skip interactive questions and make the needed choices automatically.

5.3 Confidence Check and Deepening

After writing the plan file, automatically evaluate whether the plan needs strengthening.

Two deepening modes exist:

Auto mode — default during plan generation. Findings are synthesized directly into the plan without per-finding approval.
Interactive mode — used when the user explicitly asked to deepen an existing plan. Findings are presented before integration.

The confidence check and document-review are different:

document-review checks coherence, feasibility, scope alignment, simplification pressure, observability/supportability gaps, and role-specific document quality
the confidence check strengthens rationale, sequencing, risk treatment, and system-wide thinking when the plan is structurally sound but still thin

Determine:

plan depth
topic risk profile
whether local grounding is thin enough that a strengthening pass is warranted

If the plan already appears sufficiently grounded, report:

Confidence check passed — no sections need strengthening.

and skip to document review.

When deepening is warranted, read references/deepening-workflow.md and execute that flow.

5.4 Document Review, Final Checks, and Post-Generation Options

After the confidence check, read references/plan-handoff.md and ../references/workflow-gates.md. Document review is mandatory — do not skip it even if the confidence check already ran.

Apply the Plan-Ready gate before offering work. Close with the canonical handoff card: Stage, Artifact, Ready, Open decisions, Evidence, and Next. The Ready field is conditional until the user chooses whether to address review findings, deepen the plan, or start $fw:work.

NEVER CODE. Research, decide, and write the plan.

About