ce-plan

# Create Technical Plan **Note: The current year is 2026.** Use this when dating plans and searching for recent documentation. `ce-brainstorm` defines **WHAT** to build. `ce-plan` defines **HOW** to build it. `ce-work` executes the plan. This workflow produces a durable implementation plan. It does **not** implement code, run tests, or learn from execution-time results. If the answer depends on changing code and seeing what happens, that belongs in `ce-work`, not here. ## Interaction Method Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`ask_user` in Copilot CLI). Otherwise, present numbered options in chat and wait for the user's reply before proceeding. Ask one question at a time. Prefer a concise single-select choice when natural options exist. ## Feature Description <feature_description> #$ARGUMENTS </feature_description> **Orchestration arguments:** If `$ARGUMENTS` contains a `run:<run-id>` token (passed by `/lfg` or `/slfg`), recognize and strip it before interpreting the remainder as the feature description. It associates this plan with a shared orchestrated run; you do not need to act on it further. Ignore any other unrecognized `key:value` tokens. **If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind." Do not proceed until you have a clear planning input. **IMPORTANT: All file references in the plan document must use repo-relative paths (e.g., `src/models/user.rb`), never absolute paths (e.g., `/Users/name/Code/project/src/models/user.rb`). This applies everywhere — implementation unit file lists, pattern references, origin document links, and prose mentions. Absolute paths break portability across machines, worktrees, and teammates.** ## Core Principles 1. **Use requirements as the source of truth** - If `ce-brainstorm` produced a requirements document, planning should build from it rather than re-inventing behavior. 2. **Decisions, not code** - Capture approach, boundaries, files, dependencies, risks, and test scenarios. Do not pre-write implementation code or shell command choreography. Pseudo-code sketches or DSL grammars that communicate high-level technical design are welcome when they help a reviewer validate direction — but they must be explicitly framed as directional guidance, not implementation specification. 3. **Research before structuring** - Explore the codebase, institutional learnings, and external guidance when warranted before finalizing the plan. 4. **Right-size the artifact** - Small work gets a compact plan. Large work gets more structure. The philosophy stays the same at every depth. 5. **Separate planning from execution discovery** - Resolve planning-time questions here. Explicitly defer execution-time unknowns to implementation. 6. **Keep the plan portable** - The plan should work as a living document, review artifact, or issue body without embedding tool-specific executor instructions. 7. **Carry execution posture lightly when it matters** - If the request, origin document, or repo context clearly implies test-first, characterization-first, or another non-default execution posture, reflect that in the plan as a lightweight signal. Do not turn the plan into step-by-step execution choreography. ## 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 work being proposed (never absolute paths — see Planning Rules) - Explicit test file paths for feature-bearing implementation units - Decisions with rationale, not just tasks - Existing patterns or code references to follow - Enumerated test scenarios for each feature-bearing unit, specific enough that an implementer knows exactly what to test without inventing coverage themselves - Clear dependencies and sequencing A plan is ready when an implementer can start confidently without needing the plan to write the code for them. ## 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" (or "deepening") in reference to a plan is the primary trigger for the deepening fast path. When the user says "deepen the plan", "deepen my plan", "run a deepening pass", or similar, the target document is a **plan** in `docs/plans/`, not a requirements document. Use any path, keyword, or context the user provides to identify the right plan. If a path is provided, verify it is actually a plan document. If the match is not obvious, confirm with the user before proceeding. Words like "strengthen", "confidence", "gaps", and "rigor" are NOT sufficient on their own to trigger deepening. These words appear in normal editing requests ("strengthen that section about the diagram", "there are gaps in the test scenarios") and should not cause a holistic deepening pass. Only treat them as deepening intent when the request clearly targets the plan as a whole and does not name a specific section or content area to change — and even then, prefer to confirm with the user before entering the deepening flow. Once the plan is identified and appears complete (all major sections present, implementation units defined, `status: active`), short-circuit to Phase 5.3 (Confidence Check and Deepening) in **interactive mode**. This avoids re-running the full planning workflow and gives the user control over which findings are integrated. Normal editing requests (e.g., "update the test scenarios", "add a new implementation unit", "strengthen the risk section") should NOT trigger the fast path — they follow the standard resume flow. If the plan already has a `deepened: YYYY-MM-DD` frontmatter field and there is no explicit user request to re-deepen, the fast path still applies the same confidence-gap evaluation — it does not force deepening. #### 0.2 Find Upstream Requirements Document Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`. **Relevance criteria:** A requirements document is relevant if: - The topic semantically matches the feature description - It was created within the last 30 days (use judgment to override if the document is clearly still relevant or clearly stale) - It appears to cover the same user problem or scope If multiple source documents match, ask which one to use using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding. #### 0.3 Use the Source Document as Primary Input If a relevant requirements document exists: 1. Read it thoroughly 2. Announce that it will serve as the origin document for planning 3. Carry forward all of the following: - Problem frame - Requirements and success criteria - Scope boundaries - Key decisions and rationale - Dependencies or assumptions - Outstanding questions, preserving whether they are blocking or deferred 4. Use the source document as the primary input to planning and research 5. Reference important carried-forward decisions in the plan with `(see origin: <source-path>)` 6. Do not silently omit source content — if the origin document discussed it, the plan must address it even if briefly. Before finalizing, scan each section of the origin document to verify nothing was dropped. If no relevant requirements document exists, planning may proceed from the user's request directly. #### 0.4 No-Requirements-Doc Fallback If no relevant requirements document exists: - 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 `ce-brainstorm` first - If the user wants to continue here anyway, run a short planning bootstrap instead of refusing The planning bootstrap should establish: - Problem frame - Intended behavior - Scope boundaries and obvious non-goals - Success criteria - Blocking questions or assumptions Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm. If the bootstrap uncovers major unresolved product questions: - Recommend `ce-brainstorm` again - If the user still wants to continue, require explicit assumptions before proceeding #### 0.5 Classify Outstanding Questions Before Planning If the origin document contains `Resolve Before Planning` or similar blocking questions: - Review each one before proceeding - 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 - Ask the user, using the platform's blocking question tool when available (see Interaction Method), whether to: 1. Resume `ce-brainstorm` to resolve them 2. Convert them into explicit assumptions or decisions and continue - Do not continue planning while true blockers remain unresolved #### 0.6 Assess Plan Depth Classify the work into one of these plan 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 implementation work If depth is unclear, ask one targeted question and then continue. ### Phase 1: Gather Context #### 1.1 Local Research (Always Runs) Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents: - If an origin document exists, summarize the problem frame, requirements, and key decisions from that document - Otherwise use the feature description directly Run these agents in parallel: - Use the repo-research-analyst skill to: Scope: technology, architecture, patterns. {planning context summary} - Use the learnings-researcher skill to: planning context summary Collect: - Technology stack and versions (used in section 1.2 to make sharper external research decisions) - Architectural patterns and conventions to follow - Implementation patterns, relevant files, modules, and tests - AGENTS.md guidance that materially affects the plan - Institutional learnings from `docs/solutions/` #### 1.1b Detect Execution Posture Signals Decide whether the plan should carry a lightweight execution posture signal. Look for signals such as: - The user explicitly asks for TDD, test-first, or characterization-first work - The origin document calls for test-first implementation or exploratory hardening of legacy code - Local research shows the target area is legacy, weakly tested, or historically fragile, suggesting characterization coverage before changing behavior - The user asks for external delegation, says "use codex", "delegate mode", or mentions token conservation -- add `Execution target: external-delegate` to implementation units that are pure code writing When the signal is clear, carry it forward silently in the relevant implementation units. Ask the user only if the posture would materially change sequencing or risk and cannot be responsibly inferred. #### 1.2 Decide on External Research Based on the origin document, user signals, and local findings, decide whether external research adds value. **Read between the lines.** Pay attention to signals from the conversation so far: - **User familiarity** — Are they pointing to specific files or patterns? They likely know the codebase well. - **User intent** — Do they want speed or thoroughness? Exploration or execution? - **Topic risk** — Security, payments, external APIs warrant more caution regardless of user signals. - **Uncertainty level** — Is the approach clear or still open-ended? **Leverage repo-research-analyst's technology context:** The repo-research-analyst output includes a structured Technology & Infrastructure summary. Use it to make sharper external research decisions: - If specific frameworks and versions were detected (e.g., Rails 7.2, Next.js 14, Go 1.22), pass those exact identifiers to framework-docs-researcher so it fetches version-specific documentation - If the feature touches a technology layer the scan found well-established in the repo (e.g., existing Sidekiq jobs when planning a new background job), lean toward skipping external research -- local patterns are likely sufficient - If the feature touches a technology layer the scan found absent or thin (e.g., no existing proto files when planning a new gRPC service), lean toward external research -- there are no local patterns to follow - If the scan detected deployment infrastructure (Docker, K8s, serverless), note it in the planning context passed to downstream agents so they can account for deployment constraints - If the scan detected a monorepo and scoped to a specific service, pass that service's tech context to downstream research agents -- not the aggregate of all services. If the scan surfaced the workspace map without scoping, use the feature description to identify the relevant service before proceeding with research **Always lean toward external research when:** - The topic is high-risk: security, payments, privacy, external APIs, migrations, compliance - The codebase lacks relevant local patterns -- fewer than 3 direct examples of the pattern this plan needs - Local patterns exist for an adjacent domain but not the exact one -- e.g., the codebase has HTTP clients but not webhook receivers, or has background jobs but not event-driven pub/sub. Adjacent patterns suggest the team is comfortable with the technology layer but may not know domain-specific pitfalls. When this signal is present, frame the external research query around the domain gap specifically, not the general technology - The user is exploring unfamiliar territory - The technology scan found the relevant layer absent or thin in the codebase **Skip external research when:** - The codebase already shows a strong local pattern -- multiple direct examples (not adjacent-domain), recently touched, following current conventions - The user already knows the intended shape - Additional external context would add little practical value - The technology scan found the relevant layer well-established with existing examples to follow Announce the decision briefly before continuing. Examples: - "Your codebase has solid patterns for this. Proceeding without external research." - "This involves payment processing, so I'll research current best practices first." #### 1.3 External Research (Conditional) If Step 1.2 indicates external research is useful, run these agents in parallel: - Use the best-practices-researcher skill to: planning context summary - Use the framework-docs-researcher skill to: planning context summary #### 1.4 Consolidate Research Summarize: - Relevant codebase patterns and file paths - Relevant institutional learnings - External references and best practices, if gathered - Related issues, PRs, or prior art - Any constraints that should materially shape the plan #### 1.4b Reclassify Depth When Research Reveals External Contract Surfaces If the current classification is **Lightweight** and Phase 1 research found that the work touches any of these external contract surfaces, reclassify to **Standard**: - Environment variables consumed by external systems, CI, or other repositories - Exported public APIs, CLI flags, or command-line interface contracts - CI/CD configuration files (`.github/workflows/`, `Dockerfile`, deployment scripts) - Shared types or interfaces imported by downstream consumers - Documentation referenced by external URLs or linked from other systems This ensures flow analysis (Phase 1.5) runs and the confidence check (Phase 5.3) applies critical-section bonuses. Announce the reclassification briefly: "Reclassifying to Standard — this change touches [environment variables / exported APIs / CI config] with external consumers." #### 1.5 Flow and Edge-Case Analysis (Conditional) For **Standard** or **Deep** plans, or when user flow completeness is still unclear, run: - Use the spec-flow-analyzer skill to: planning context summary, research findings Use the output to: - Identify missing edge cases, state transitions, or handoff gaps - Tighten requirements trace or verification strategy - Add only the flow details that materially improve the plan ### 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** - the answer is knowable from repo context, documentation, or user choice - **Deferred to implementation** - the answer 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. Use the platform's blocking question tool when available (see Interaction Method). **Do not** run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution. ### Phase 3: Structure the Plan #### 3.1 Title and File Naming - Draft a clear, searchable title using conventional format such as `feat: Add user authentication` or `fix: Prevent checkout double-submit` - Determine the plan type: `feat`, `fix`, or `refactor` - Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md` - Create `docs/plans/` if it does not exist - Check existing files for today's date to determine the next sequence number (zero-padded to 3 digits, starting at 001) - Keep the descriptive name concise (3-5 words) and kebab-cased - Examples: `2026-01-15-001-feat-user-authentication-flow-plan.md`, `2026-02-03-002-fix-checkout-race-condition-plan.md` - Avoid: missing sequence numbers, vague names like "new-feature", invalid characters (colons, spaces) #### 3.2 Stakeholder and Impact Awareness For **Standard** or **Deep** plans, briefly consider who is affected by this change — end users, developers, operations, other teams — and how that should shape the plan. For cross-cutting work, note affected parties in the System-Wide Impact section. #### 3.3 Break Work into Implementation Units Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic commit. Good units are: - Focused on one component, behavior, or integration seam - Usually touching a small cluster of related files - Ordered by dependency - Concrete enough for execution without pre-writing code - Marked with checkbox syntax for progress tracking Avoid: - 2-5 minute micro-steps - Units that span multiple unrelated concerns - Units that are so vague an implementer still has to invent the plan #### 3.4 High-Level Technical Design (Optional) Before detailing implementation units, decide whether an overview would help a reviewer validate the intended approach. This section communicates the *shape* of the solution — how pieces fit together — without dictating implementation. **When to include it:** | 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 (inputs -> outcomes) | | Single-component with non-obvious shape | Pseudo-code sketch | **When to skip it:** - Well-patterned work where prose and file paths tell the whole story - Straightforward CRUD or convention-following changes - Lightweight plans where the approach is obvious Choose the medium that fits the work. Do not default to pseudo-code when a diagram communicates better, and vice versa. Frame every sketch with: *"This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce."* Keep sketches concise — enough to validate direction, not enough to copy-paste into production. #### 3.5 Define Each Implementation Unit For each unit, include: - **Goal** - what this unit accomplishes - **Requirements** - which requirements or success criteria it advances - **Dependencies** - what must exist first - **Files** - repo-relative file paths to create, modify, or test (never absolute paths) - **Approach** - key decisions, data flow, component boundaries, or integration notes - **Execution note** - optional, only when the unit benefits from a non-default execution posture such as test-first, characterization-first, or external delegation - **Technical design** - optional pseudo-code or diagram when the unit's approach is non-obvious and prose alone would leave it ambiguous. Frame explicitly as directional guidance, not implementation specification - **Patterns to follow** - existing code or conventions to mirror - **Test scenarios** - enumerate the specific test cases the implementer should write, right-sized to the unit's complexity and risk. Consider each category below and include scenarios from every category that applies to this unit. A simple config change may need one scenario; a payment flow may need a dozen. The quality signal is specificity — each scenario should name the input, action, and expected outcome so the implementer doesn't have to invent coverage. For units with no behavioral change (pure config, scaffolding, styling), use `Test expectation: none -- [reason]` instead of leaving the field blank. - **Happy path behaviors** - core functionality with expected inputs and outputs - **Edge cases** (when the unit has meaningful boundaries) - boundary values, empty inputs, nil/null states, concurrent access - **Error and failure paths** (when the unit has failure modes) - invalid input, downstream service failures, timeout behavior, permission denials - **Integration scenarios** (when the unit crosses layers) - behaviors that mocks alone will not prove, e.g., "creating X triggers callback Y which persists Z". Include these for any unit touching callbacks, middleware, or multi-layer interactions - **Verification** - how an implementer should know the unit is complete, expressed as outcomes rather than shell command scripts Every feature-bearing unit should include the test file path in `**Files:**`. Use `Execution note` sparingly. Good uses include: - `Execution note: Start with a failing integration test for the request/response contract.` - `Execution note: Add characterization coverage before modifying this legacy parser.` - `Execution note: Implement new domain behavior test-first.` - `Execution note: Execution target: external-delegate` Do not expand units into literal `RED/GREEN/REFACTOR` substeps. #### 3.6 Keep Planning-Time and Implementation-Time Unknowns Separate If something is important but not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it in the plan. Examples: - Exact method or helper names - Final SQL or query details after touching real code - Runtime behavior that depends on seeing actual test failures - Refactors that may become unnecessary once implementation starts ### 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 implementation units - Omit optional sections that add little value **Standard** - Use the full core template, omitting optional sections (including High-Level Technical Design) that add no value for this particular work - Usually 3-6 implementation 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 implementation units - Group units into phases when that improves clarity - Include alternatives considered, documentation impacts, and deeper risk treatment when warranted #### 4.1b Optional Deep Plan Extensions For sufficiently large, risky, or cross-cutting work, add 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 Do not add these as boilerplate. Include them only when they improve execution quality or stakeholder alignment. #### 4.2 Core Plan Template Omit clearly inapplicable optional sections, especially for Lightweight plans. ```markdown --- 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