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. A prior brainstorm is useful context but never required — ce-plan works from any input: 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 abandon the workflow. If the input is unclear, ask clarifying questions or use the planning bootstrap (Phase 0.4) to establish enough context — but always stay in the planning workflow.

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

When asking the user a question, use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini, ask_user in Pi (requires the pi-ask-user extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

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

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." Then wait for their response before continuing.

If the input is present but unclear or underspecified, do not abandon — ask one or two clarifying questions, or proceed to Phase 0.4's planning bootstrap to establish enough context. The goal is always to help the user plan, never to exit the workflow.

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.
8. Honor user-named resources - When the user names a specific resource — a CLI, MCP server, URL, file, doc link, or prior artifact — treat it as authoritative input, not a suggestion. Discover it if unknown (command -v, fetch, read) before assuming it's unavailable. Use it in place of generic alternatives. If it fails or doesn't exist, say so explicitly rather than silently substituting.

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, revise only the still-relevant sections. Plans do not carry per-unit progress state — progress is derived from git by ce-work, so there is no progress to preserve across edits

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):

• If the plan lacks YAML frontmatter (non-software plans use a simple # Title heading with Created: date instead of frontmatter), route to references/universal-planning.md for editing or deepening instead of Phase 5.3. Non-software plans do not use the software confidence check.
• Otherwise, 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.1b Classify Task Domain

If the task involves building, modifying, or architecting software (references code, repos, APIs, databases, or asks to build/modify/deploy), continue to Phase 0.2.

If the domain is genuinely ambiguous (e.g., "plan a migration" with no other context), ask the user before routing.

Otherwise, read references/universal-planning.md and follow that workflow instead. Skip all subsequent phases. Named tools or source links don't change this routing — they're inputs, handled per Core Principle 8.

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
   • Actors (A-IDs), Key Flows (F-IDs), and Acceptance Examples (AE-IDs) when present — preserve these as constraints that implementation units must honor
   • Requirements and success criteria
   • Scope boundaries (including "Deferred for later" and "Outside this product's identity" subsections when present)
   • 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 Planning Bootstrap (No Requirements Doc or Unclear Input)

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 so, continue to Phase 0.5
• If the ambiguity is mainly product framing, user behavior, or scope definition, recommend ce-brainstorm as a suggestion — but always offer to continue planning here as well
• If the user wants to continue here (or was already explicit about wanting a plan), run the planning bootstrap below

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

If the bootstrap reveals that a different workflow would serve the user better:

• Symptom without a root cause (user describes broken behavior but hasn't identified why) — announce that investigation is needed before planning and load the ce-debug skill. A plan requires a known problem to solve; debugging identifies what that problem is. Announce the routing clearly: "This needs investigation before planning — switching to ce-debug to find the root cause."
• Clear task ready to execute (known root cause, obvious fix, no architectural decisions) — suggest ce-work as a faster alternative alongside continuing with planning. The user decides.

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:

• Task ce-repo-research-analyst(Scope: technology, architecture, patterns. {planning context summary})
• Task ce-learnings-researcher(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, with CLAUDE.md used only as compatibility fallback when present
• Institutional learnings from docs/solutions/

Slack context (opt-in) — never auto-dispatch. Route by condition:

• Tools available + user asked: Dispatch ce-slack-researcher with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass