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

• Bug-shaped prompt (user describes broken behavior — "fix the bug where X", error message, regression, "doesn't work"). Surface ce-debug as a route-out option alongside continuing with ce-plan whenever the bug surface is reachable (in cwd OR named repo found at another local path). Stay in ce-plan silently when the named code can't be found anywhere local — paper-planning is the only useful output for unreachable surfaces.

When the bug is at another local path (not cwd):

• Announce the target explicitly before any cross-repo investigation: which path will be read AND where plan outputs will land (default: target repo's docs/plans/, not cwd's).
• Default: proceed from the target repo for both investigation and plan-write. The user can interrupt to redirect (switch context, paper-plan, abandon, etc.). No location menu — the announcement makes the cross-repo nature visible, and the user can speak up if they want something unusual.
• After announcing and proceeding, fire the standard ce-debug routing menu (continue with ce-plan vs switch to ce-debug) — same shape as the in-cwd case. Cross-repo location and ce-debug skill routing are orthogonal decisions; do not merge them into a single question.

Reading code at another path is fine in principle — that's just file access. The harm to avoid is silent operation on the wrong repo, especially writing the plan doc somewhere it won't be discovered (a busyblock plan landing in cli-printing-press/docs/plans/ is a discoverability disaster). The announcement requirement makes the target visible; defaulting to the target repo for both investigation and outputs respects the user's stated intent (they named that repo); the orthogonal ce-debug menu keeps the skill-choice question clean.

The accessibility classification is conservative and may under-suggest in monorepos, dependency bugs, or after renames. Users can always invoke /ce-debug manually.

Headless mode: skip the ce-debug suggestion menu entirely; default to continuing with /ce-plan (the user's explicit invocation). There is no synchronous user to resolve a route-out choice, and auto-routing to ce-debug would change the skill mid-flight without authorization.

• 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.

0.7 Solo-Mode Scope Summary

STOP. Before composing the synthesis, read `references/synthesis-summary.md`. The discipline rules, prose-summary requirement, three-bucket structure, anti-pattern guidance, soft-cut behavior, self-redirect support, content focus for the solo variant, and bucket-content routing into plan body sections all live there. Composing a synthesis without these rules loaded reliably produces malformed output — missing prose summary, implementation-detail leakage, the proposal-pitch anti-pattern. This is not optional supplementary reading; it is the source of truth for how the phase behaves.

Surface a synthesis to the user — the agent's interpretation of scope after the brief Phase 0.4 bootstrap — so scope can be corrected before Phase 1 research is spent. Sub-agent dispatch (repo-research-analyst, learnings-researcher, etc.) is the expensive next step this phase guards against wasted effort on.

Fires only in solo invocation — when Phase 0.2 found no upstream brainstorm doc AND Phase 0.4 stayed in ce-plan (did not route to ce-debug, ce-work, or universal-planning) AND Phase 0.5 cleared (no unresolved blockers) AND not on Phase 0.1 fast paths (resume normal, deepen-intent). Each guard is an explicit conditional. Skip Phase 0.7 entirely when any guard fails — brainstorm-sourced invocations defer to Phase 5.1.5 instead.

Headless mode: synthesis is composed but not confirmed (no synchronous user). Continue to Phase 1 research as normal. At plan-write time (Phase 5.2), Inferred bets route to a ## Assumptions section in the plan instead of Key Technical Decisions. See references/synthesis-summary.md Headless mode for the full routing.

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
• If STRATEGY.md exists, read it and include the relevant pieces (target problem, approach, active tracks) in the summary so downstream research and planning decisions are anchored to product strategy

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/
• Product strategy context when STRATEGY.md is present — flag any plan decisions that pull away from the active tracks or the stated approach

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 it verbatim so the researcher focuses on gaps. Include findings in consolidation.
• Tools available + user didn't ask: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
• No tools + user asked: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."

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

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 ce-repo-research-analyst's technology context:

The ce-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 ce-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:

• Task ce-best-practices-researcher(planning context summary)
• Task ce-framework-docs-researcher(planning context summary)

1.4 Consolidate Research

Summarize:

• Relevant codebase patterns and file paths
• Relevant institutional learnings
• Organizational context from Slack conversations, if gathered (prior discussions, decisions, or domain knowledge relevant to the feature)
• 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:

• Task ce-spec-flow-analyzer(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

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

Each unit carries a stable plan-local U-ID assigned in Phase 3.5 (U1, U2, …). U-IDs survive reordering, splitting, and deletion: new units take the next unused number, gaps are fine, and existing IDs are never renumbered. This lets ce-work reference units unambiguously across plan edits.

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:

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.4b Output Structure (Optional)

For greenfield plans that create a new directory structure (new plugin, service, package, or module), include an ## Output Structure section with a file tree showing the expected layout. This gives reviewers the overall shape before diving into per-unit details.

When to include it:

• The plan creates 3+ new files in a new directory hierarchy
• The directory layout itself is a meaningful design decision

When to skip it:

• The plan only modifies existing files
• The plan creates 1-2 files in an existing directory — the per-unit file lists are sufficient

The tree is a scope declaration showing the expected output shape. It is not a constraint — the implementer may adjust the structure if implementation reveals a better layout. The per-unit **Files:** sections remain authoritative for what each unit creates or modifies.

3.5 Define Each Implementation Unit

Each unit is a level-3 heading carrying a stable U-ID prefix matching the format used for R/A/F/AE in requirements docs: ### U1. [Name]. Number sequentially within the plan starting at U1. Do not render units as bulleted list items or prefix them with - [ ] / - [x] checkbox markers. List-based unit titles fragment in every standard renderer because the per-unit fields (**Goal:**, **Files:**, **Approach:**, etc.) are written flush-left, which terminates CommonMark list continuation and detaches the fields from the unit they describe. Headings render correctly everywhere, are the right semantic match for sections containing multi-block content, and give each unit an anchor link. The plan is a decision artifact; execution progress is derived from git by ce-work rather than stored in the plan body.

Stability rule. Once assigned, a U-ID is never renumbered. Reordering units leaves their IDs in place (e.g., U1, U3, U5 in their new order is correct; renumbering to U1, U2, U3 is not). Splitting a unit keeps the original U-ID on the original concept and assigns the next unused number to the new unit. Deletion leaves a gap; gaps are fine. This rule matters most during deepening (Phase 5.3), which is the most likely accidental-renumber vector.

For each unit, include:

• Goal - what this unit accomplishes
• Requirements - which requirements or success criteria it advances (cite R-IDs, and A/F/AE IDs when origin supplies them)
• Dependencies - what must exist first (cite by U-ID, e.g., "U1, U3")
• 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 or characterization-first
• 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. AE-link convention: when a test scenario directly enforces an origin Acceptance Example, prefix it with Covers AE<N>. (or Covers F<N> / AE<N>.). This is sparse-by-design — most test scenarios are finer-grained than AEs and do not link. Do not force AE links onto tests that only cover lower-level implementation details.
• 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.

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

3.7 Anti-Expansion: Tangential Cleanup and Scope Creep Go to Deferred

Distinct from 3.6 (which is about unknowns at plan time): 3.7 is about known but tangential work that the agent notices while planning but that falls outside the user's confirmed scope. When research surfaces an adjacent refactor, a "while we're here" cleanup, or a scope-adjacent nice-to-have ("we could also add rate limiting"), route it to the existing ### Deferred to Follow-Up Work subsection in Scope Boundaries (Phase 4.2 Core Plan Template), not into active Implementation Units.

This reinforces the synthesis discipline established at Phase 0.7 / Phase 5.1.5 — the user's confirmed scope is what the active plan executes; everything else is deferred. Does NOT impose architectural bias on extend-vs-invent decisions within confirmed scope — that judgment stays with the agent (and is surfaced via the Phase 5.1.5 synthesis when material). The user's explicit ask overrides this default — if the user explicitly requested a refactor, it's in-scope, not deferred.

Phase 4: Write the Plan

NEVER CODE during this skill. Research, decide, and write the plan — do not start implementation.

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.

Alternatives Considered — what to vary. When this section is included, alternatives must differ on how the work is built: architecture, sequencing, boundaries, integration pattern, rollout strategy. Tiny implementation variants (which hash function, which serialization format) belong in Key Technical Decisions, not Alternatives. Product-shape alternatives (different actors, different core outcome, different positioning) belong in ce-brainstorm, not here — surface them back upstream rather than re-litigating product questions during planning.

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]

## Summary

[1-3 line prose summary — what the plan is proposing, in plain language. Forward-looking. With an origin requirements doc, focus on HOW the implementation approaches the work (the WHAT is in origin); without one, carry both WHAT scope and HOW execution. Required for all tiers; skip only for truly-trivial plans (≤ 2 Requirements bullets that echo the prompt).]

---

## Problem Frame

[Backward-looking / situational: the user/business problem and context that motivates this plan. Establishes the pain — does NOT restate the proposal (that lives in Summary). With an origin requirements doc, keep this brief (1-2 sentences plus any plan-specific framing) and link to origin via Sources & References. Without one, carry the full pain narrative. **Omit entirely at Lightweight tier when Summary already carries the situational context** — a focused bug fix or one-line change rarely needs both sections.]

---

<!-- Include ONLY in non-interactive (headless) mode when the agent had Inferred bets that
     were not user-confirmed. Lists the un-validated agent inferences explicitly so downstream
     review (ce-doc-review, ce-work, human PR review) can scrutinize them as bets, not as
     authoritative decisions. Omit entirely in interactive mode — Inferred bets get user-
     corrected in chat and become Key Technical Decisions or are revised away. -->
## Assumptions

*This plan was authored without synchronous user confirmation. The items below are agent inferences that fill gaps in the input — un-validated bets that should be reviewed before implementation proceeds.*

- [Inferred item the agent chose without user confirmation]

---

## Requirements

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

<!-- With an origin requirements doc, R-IDs trace to origin's; without one, R-IDs are derived
     during planning. The optional origin trace sub-blocks below carry forward what's relevant
     when origin actors/flows/acceptance examples exist. -->

**Origin actors:** [A1 (role/name), A2 (role/name), …]
**Origin flows:** [F1 (flow name), F2 (flow name), …]
**Origin acceptance examples:** [AE1 (covers R1, R4), AE2 (covers R3), …]

---

## Scope Boundaries

<!-- Default structure (no origin doc, or origin was Lightweight / Standard / Deep-feature):
     a single bulleted list of explicit non-goals. The optional `### Deferred to Follow-Up Work`
     subsection below may still be included when this plan's implementation is intentionally
     split across other PRs/issues/repos. -->

- [Explicit non-goal or exclusion]

<!-- Optional plan-local subsection — include when this plan's implementation is intentionally
     split across other PRs, issues, or repos. Distinct from origin-carried "Deferred for later"
     (product sequencing) and "Outside this product's identity" (positioning). -->
### Deferred to Follow-Up Work

- [Work that will be done separately]: [Where or when -- e.g., "separate PR in repo-x", "future iteration"]

<!-- Triggered structure: replace the single list above with the three subsections below ONLY
     when the origin doc is Deep-product (detectable by presence of an "Outside this product's
     identity" subsection in the origin's Scope Boundaries). At all other tiers and when no
     origin exists, use the single-list structure above. -->

<!--
### Deferred for later

[Carried from origin — product/version sequencing. Work that will be done eventually but not in v1.]

- [Item]

### Outside this product's identity

[Carried from origin — positioning rejection. Adjacent product the plan must not accidentally build.]

- [Item]

### Deferred to Follow-Up Work

[Plan-local — implementation work intentionally split across other PRs/issues/repos. Distinct from origin's "Deferred for later" (product) and "Outside this product's identity" (positioning).]

- [Item]
-->

---

## Context & Research

### Relevant Code and Patterns

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

### Institutional Learnings

- [Relevant `docs/solutions/` insight]

### External References

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

---

## Key Technical Decisions

- [Decision]: [Rationale]

<!-- With an origin requirements doc, scope this section to plan-time architectural choices —
     product-level decisions are in origin's Key Decisions. Without an origin, both belong here. -->

---

## Open Questions

<!-- With an origin requirements doc, scope this section to plan-time questions; product-level
     open questions stay in origin's Outstanding Questions. -->

### Resolved During Planning

- [Question]: [Resolution]

### Deferred to Implementation

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

---

<!-- Optional: Include when the plan creates a new directory structure (greenfield plugin,
     new service, new package). Shows the expected output shape at a glance. Omit for plans
     that only modify existing files. This is a scope declaration, not a constraint --
     the implementer may adjust the structure if implementation reveals a better layout. -->
## Output Structure

    [directory tree showing new directories and files]

---

<!-- Optional: Include this section only when the work involves DSL design, multi-component
     integration, complex data flow, state-heavy lifecycle, or other cases where prose alone
     would leave the approach shape ambiguous. Omit it entirely for well-patterned or
     straightforward work. -->
## High-Level Technical Design

> *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.*

[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]

---

## Implementation Units

<!-- Each unit carries a stable plan-local U-ID (U1, U2, …) assigned sequentially.
     U-IDs are never renumbered: reordering preserves them in place, splitting keeps the
     original U-ID and assigns the next unused number to the new unit, deletion leaves
     a gap. This anchor is what ce-work references in blockers and verification, so
     stability across plan edits is load-bearing. -->

### U1. [Name]

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

**Requirements:** [R1, R2]

**Dependencies:** [None / U1 / external prerequisite]

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

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

**Execution note:** [Optional test-first, characterization-first, or other execution posture signal]

**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*

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

**Test scenarios:**
<!-- Include only categories that apply to this unit. Omit categories that don't. For units with no behavioral change, use "Test expectation: none -- [reason]" instead of leaving this section blank. -->
- [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]

**Verification:**
- [Outcome that should hold when this unit is complete]

---

## 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 APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]

---

## 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)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]

For larger Deep plans, extend the core template only when useful with sections such as:

## Alternative Approaches Considered

- [Approach]: [Why rejected or not chosen]

---

## Success Metrics

- [How we will know this solved the intended problem]

---

## Dependencies / Prerequisites

- [Technical, organizational, or rollout dependency]

---

## Risk Analysis & Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How addressed] |

---

## Phased Delivery

### Phase 1
- [What lands first and why]

### Phase 2
- [What follows and why]

---

## Documentation Plan

- [Docs or runbooks to update]

---

## Operational / Rollout Notes

- [Monitoring, migration, feature flag, or rollout considerations]

4.3 Planning Rules

• Horizontal rules (`---`) between top-level sections in Standard and Deep plans, mirroring the ce-brainstorm requirements doc convention. Improves scannability of dense plans where many H2 sections sit close together. Omit for Lightweight plans where the whole doc fits on a single screen.
• All file paths must be repo-relative — never use absolute paths like /Users/name/Code/project/src/file.ts. Use src/file.ts instead. Absolute paths make plans non-portable across machines, worktrees, and teammates. When a plan targets a different repo than the document's home, state the target repo once at the top of the plan (e.g., **Target repo:** my-other-project) and use repo-relative paths throughout
• Prefer path plus class/component/pattern references over brittle line numbers
• Do not include implementation code — no imports, exact method signatures, or framework-specific syntax
• Pseudo-code sketches and DSL grammars are allowed in the High-Level Technical Design section and per-unit technical design fields when they communicate design direction. Frame them explicitly as directional guidance, not implementation specification
• Mermaid diagrams are encouraged when they clarify relationships or flows that prose alone would make hard to follow — ERDs for data model changes, sequence diagrams for multi-service interactions, state diagrams for lifecycle transitions, flowcharts for complex branching logic
• Do not include git commands, commit messages, or exact test command recipes
• Do not expand implementation units into micro-step RED/GREEN/REFACTOR instructions
• Do not pretend an execution-time question is 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/variants in Summary or Problem Frame, or 3+ interacting decisions in Key Technical Decisions or alternatives in Alternative Approaches, read references/visual-communication.md for diagram and table guidance. This covers plan-structure visuals (dependency graphs, interaction diagrams, comparison tables) — not solution-design diagrams, which are covered in Section 3.4.

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 ce-brainstorm
• If there was no origin document, the bounded planning bootstrap established enough product clarity to plan responsibly
• Every major decision is grounded in the origin document or research
• Each implementation unit is concrete, dependency-ordered, and implementation-ready
• If test-first or characterization-first posture was explicit or strongly implied, the relevant units carry it forward with a lightweight Execution note
• Each feature-bearing unit has test scenarios from every applicable category (happy path, edge cases, error paths, integration) — right-sized to the unit's complexity, not padded or skimped
• Test scenarios name specific inputs, actions, and expected outcomes without becoming test code
• Feature-bearing units with blank or missing test scenarios are flagged as incomplete — feature-bearing units must have actual test scenarios, not just an annotation. The Test expectation: none -- [reason] annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)
• Deferred items are explicit and not hidden as fake certainty
• If a High-Level Technical Design section is included, it uses the right medium for the work, carries the non-prescriptive framing, and does not contain implementation code (no imports, exact signatures, or framework-specific syntax)
• Per-unit technical design fields, if present, are concise and directional rather than copy-paste-ready
• If the plan creates a new directory structure, would an Output Structure tree help reviewers see the overall shape?
• If Scope Boundaries lists items that are planned work for a separate PR, issue, or repo, are they under ### Deferred to Follow-Up Work rather than mixed with true non-goals?
• U-IDs are unique within the plan and follow the stability rule — no two units share an ID; reordering or splitting did not renumber existing units; gaps from deletions are preserved
• Would a visual aid (dependency graph, interaction diagram, comparison table) help a reader grasp the plan structure faster than scanning prose alone?

If the plan originated from a requirements document, re-read that document and verify:

• The chosen approach still matches the product intent
• Scope boundaries and success criteria are preserved
• Blocking questions were either resolved, explicitly assumed, or sent back to ce-brainstorm
• Every section of the origin document is addressed in the plan — scan each section to confirm nothing was silently dropped
• If origin supplies A/F/AE IDs: every origin R/F/AE that affects implementation is referenced in Requirements, a U-ID unit, test scenarios, verification, scope boundaries, or explicitly deferred. Actors are carried forward when they affect behavior, permissions, UX, orchestration, handoff, or verification. The standard is preservation of product intent, not mandatory ID spam — irrelevant origin IDs may be omitted
• If origin was Deep-product (origin contains an Outside this product's identity subsection): the plan's Scope Boundaries preserves the three-way split — Deferred for later and Outside this product's identity carried verbatim from origin, Deferred to Follow-Up Work reserved for plan-local implementation sequencing

5.1.5 Brainstorm-Sourced Scope Summary

STOP. Before composing the synthesis, read `references/synthesis-summary.md`. The discipline rules, prose-summary requirement, three-bucket structure, anti-pattern guidance, soft-cut behavior, self-redirect support, content focus for the brainstorm-sourced variant, doc-body reading rules, and bucket-content routing into plan body sections all live there. Composing a synthesis without these rules loaded reliably produces malformed output — missing prose summary, implementation-detail leakage, the proposal-pitch anti-pattern. This is not optional supplementary reading; it is the source of truth for how the phase behaves.

Surface the agent's plan-time decisions to the user before Phase 5.2 commits the plan to disk — the latest cheap moment to catch plan-time scope errors. The brainstorm already validated WHAT to build; this phase surfaces HOW the plan will execute.

Fires only when the plan was sourced from an upstream brainstorm doc (Phase 0.2 found a *-requirements.md match) AND not on Phase 0.1 fast paths (resume normal, deepen-intent). Skip Phase 5.1.5 in solo invocation — solo plans handled their synthesis in Phase 0.7.

Headless mode: synthesis is composed but not confirmed (no synchronous user). Proceed to Phase 5.2 plan-write. Inferred bets route to a ## Assumptions section in the plan instead of Key Technical Decisions. See references/synthesis-summary.md Headless mode for the full routing.

5.2 Write Plan File

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

Use the Write tool to save the complete plan to:

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

Confirm (use absolute path so the reference is clickable in modern terminals):

Plan written to <absolute path to plan>

Pipeline mode: If invoked from an automated workflow such as LFG or any disable-model-invocation context, skip interactive questions. Make the needed choices automatically and proceed to writing the plan.

5.3 Confidence Check and Deepening

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

Two deepening modes:

• Auto mode (default during plan generation): Runs without asking the user for approval. The user sees what is being strengthened but does not need to make a decision. Sub-agent findings are synthesized directly into the plan.
• Interactive mode (activated by the re-deepen fast path in Phase 0.1): The user explicitly asked to deepen an existing plan. Sub-agent findings are presented individually for review before integration. The user can accept, reject, or discuss each agent's findings. Only accepted findings are synthesized into the plan.

Interactive mode exists because on-demand deepening is a different user posture — the user already has a plan they are invested in and wants to be surgical about what changes. This applies whether the plan was generated by this skill, written by hand, or produced by another tool.

ce-doc-review and this confidence check are different:

• Use the ce-doc-review skill when the document needs clarity, simplification, completeness, or scope control
• This confidence check strengthens rationale, sequencing, risk treatment, and system-wide thinking when the plan is structurally sound but still needs stronger grounding

Pipeline mode: This phase always runs in auto mode in pipeline/disable-model-invocation contexts. No user interaction needed.

5.3.1 Classify Plan Depth and Topic Risk

Determine the plan depth from the document:

• Lightweight - small, bounded, low ambiguity, usually 2-4 implementation units
• Standard - moderate complexity, some technical decisions, usually 3-6 units
• Deep - cross-cutting, high-risk, or strategically important work, usually 4-8 units or phased delivery

Build a risk profile. Treat these as high-risk signals:

• Authentication, authorization, or security-sensitive behavior
• Payments, billing, or financial flows
• Data migrations, backfills, or persistent data changes
• External APIs or third-party integrations
• Privacy, compliance, or user data handling
• Cross-interface parity or multi-surface behavior
• Significant rollout, monitoring, or operational concerns

5.3.2 Gate: Decide Whether to Deepen

• Lightweight plans usually do not need deepening unless they are high-risk
• Standard plans often benefit when one or more important sections still look thin
• Deep or high-risk plans often benefit from a targeted second pass
• Thin local grounding override: If Phase 1.2 triggered external research because local patterns were thin (fewer than 3 direct examples or adjacent-domain match), always proceed to scoring regardless of how grounded the plan appears. When the plan was built on unfamiliar territory, claims about system behavior are more likely to be assumptions than verified facts. The scoring pass is cheap — if the plan is genuinely solid, scoring finds nothing and exits quickly

If the plan already appears sufficiently grounded and the thin-grounding override does not apply, report "Confidence check passed — no sections need strengthening", then load `references/plan-handoff.md` now and execute 5.3.8 → 5.3.9 → 5.4 in sequence. Document review is mandatory — do not skip it because the confidence check passed. The two tools catch different classes of issues.

5.3.3–5.3.7 Deepening Execution

When deepening is warranted, read references/deepening-workflow.md for confidence scoring checklists, section-to-agent dispatch mapping, execution mode selection, research execution, interactive finding review, and plan synthesis instructions. Execute steps 5.3.3 through 5.3.7 from that file, then return here for 5.3.8.

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

STOP. Load `references/plan-handoff.md` now before continuing. It carries the full instructions for 5.3.8 (document review), 5.3.9 (final checks and cleanup), and 5.4 (post-generation handoff, including the Proof HITL flow, post-HITL re-review, and Issue Creation branching). This load is non-optional — without it, the agent renders the post-generation menu, captures the user's selection, and stops without firing the routed action. Document review at 5.3.8 is also mandatory regardless of whether the confidence check already ran. The default mode is headless (mode:headless) — safe_auto fixes apply silently, remaining findings surface contextually above the menu, and a deeper interactive review is opt-in via free-form prompt.

After document review and final checks, print a one-line summary of the headless review state above the menu (e.g., Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1).), then present the menu. The menu has 5 options when actionable findings remain (proposed_fixes_count + decisions_count > 0) and 4 options otherwise — including the FYI-only case, which hides option 2 because ce-doc-review's walkthrough is gated to actionable findings and would have nothing to walk through. See references/plan-handoff.md for the full rule. Render the 5-option menu as a numbered list in chat per the AGENTS.md narrow exception for legitimate option overflow, with the hint "Pick a number or describe what you want." On platforms whose blocking question tool has no option cap (Codex request_user_input, Pi ask_user), use the platform's blocking tool; when that tool is unavailable or errors (e.g., Codex edit modes where request_user_input is not exposed), fall back to the same numbered-list-in-chat rendering with the "Pick a number or describe what you want." hint. The 4-option case routes through the platform's blocking tool normally (AskUserQuestion in Claude Code — call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), with the same numbered-list-in-chat fallback when no blocking tool is available or the call errors. Never silently skip the question.

Question: "Plan ready at <absolute path to plan>. What would you like to do next?" (use absolute path so the reference is clickable in modern terminals)

Options (5 when actionable findings remain; option 2 dropped and remaining options renumbered otherwise — including FYI-only state): 1. Start `/ce-work` (recommended) - Begin implementing this plan in the current session 2. Run deeper doc review - Walk through the remaining findings interactively (full ce-doc-review walkthrough) 3. Create Issue - Create a tracked issue from this plan in your configured issue tracker (GitHub or Linear) 4. Open in Proof (web app) — review and comment to iterate with the agent - Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others 5. Done for now - Pause; the plan file is saved and can be resumed later

Routing. Act on the user's selection — do not just announce it. Elaborate sub-flows (Proof HITL state machine, Issue Creation tracker detection, post-HITL resync) live in references/plan-handoff.md.

• Start `/ce-work` — Invoke the ce-work skill via the platform's skill-invocation primitive (Skill in Claude Code, Skill in Codex, the equivalent on Gemini/Pi), passing the plan path as the skill argument. Do not merely tell the user to type /ce-work — fire the invocation now so the plan executes in this session.
• Run deeper doc review — Re-invoke the ce-doc-review skill on the plan path without mode:headless so the interactive routing question and walkthrough fire. After it returns, re-render this menu with refreshed counts so the user can pick a next-stage action.
• Create Issue — Detect the project tracker (gh for GitHub, linear for Linear) and create the issue from the plan file as described under "Issue Creation" in references/plan-handoff.md. After creation, display the issue URL and ask whether to proceed to /ce-work via the platform's blocking question tool.
• Open in Proof (web app) — review and comment to iterate with the agent — Load the ce-proof skill in HITL-review mode with the plan file as source file, the plan title as doc title, identity ai:compound-engineering / Compound Engineering, and recommended next step /ce-work. Then follow the post-HITL resync logic in references/plan-handoff.md, which handles the four ce-proof return statuses, re-runs ce-doc-review after material edits, and falls back gracefully on upload failure.
• Done for now — Display a brief confirmation that the plan file is saved and end the turn. Do not start follow-up work without an explicit further user prompt.

If the user types free-form prompts targeting the findings (e.g., "review", "walk through", "deep review"), route as if they picked Run deeper doc review — fire the skill rather than looping back to the menu. For other free-text revisions, accept the input and loop back to this menu after applying the revision.

Completion check: This skill is not complete until the post-generation menu above has been presented, the user has selected an action, and the inline routing for that selection has been executed. Presenting the menu and stopping at the user's selection is not completion — fire the routed action.

Pipeline mode exception: In LFG or any disable-model-invocation context, skip the interactive menu and return control to the caller after the plan file is written, confidence check has run, and ce-doc-review has run in headless mode (per references/plan-handoff.md).

Deepening Workflow

This file contains the confidence-check execution path (5.3.3-5.3.7). Load it only when the deepening gate at 5.3.2 determines that deepening is warranted.

5.3.3 Score Confidence Gaps

Use a checklist-first, risk-weighted scoring pass.

For each section, compute:

• Trigger count - number of checklist problems that apply
• Risk bonus - add 1 if the topic is high-risk and this section is materially relevant to that risk
• Critical-section bonus - add 1 for Key Technical Decisions, Implementation Units, System-Wide Impact, Risks & Dependencies, or Open Questions in Standard or Deep plans

Treat a section as a candidate if:

• it hits 2+ total points, or
• it hits 1+ point in a high-risk domain and the section is materially important

Choose only the top 2-5 sections by score. If deepening a lightweight plan (high-risk exception), cap at 1-2 sections.

If the plan already has a deepened: date:

• Prefer sections that have not yet been substantially strengthened, if their scores are comparable
• Revisit an already-deepened section only when it still scores clearly higher than alternatives

Section Checklists:

Requirements

• Requirements are vague or disconnected from implementation units
• Success criteria are missing or not reflected downstream
• Units do not clearly advance the traced requirements
• Origin requirements are not clearly carried forward
• Origin A/F/AE IDs (when supplied by the upstream brainstorm) are not preserved where planning decisions touch them, or are referenced inconsistently across Requirements, units, and test scenarios

Context & Research / Sources & References

• Relevant repo patterns are named but never used in decisions or implementation units
• Cited learnings or references do not materially shape the plan
• High-risk work lacks appropriate external or internal grounding
• Research is generic instead of tied to this repo or this plan

Key Technical Decisions

• A decision is stated without rationale
• Rationale does not explain tradeoffs or rejected alternatives
• The decision does not connect back to scope, requirements, or origin context
• An obvious design fork exists but the plan never addresses why one path won

Open Questions

• Product blockers are hidden as assumptions
• Planning-owned questions are incorrectly deferred to implementation
• Resolved questions have no clear basis in repo context, research, or origin decisions
• Deferred items are too vague to be useful later

High-Level Technical Design (when present)

• The sketch uses the wrong medium for the work
• The sketch contains implementation code rather than pseudo-code
• The non-prescriptive framing is missing or weak
• The sketch does not connect to the key technical decisions or implementation units

High-Level Technical Design (when absent) (Standard or Deep plans only)

• The work involves DSL design, API surface design, multi-component integration, complex data flow, or state-heavy lifecycle
• Key technical decisions would be easier to validate with a visual or pseudo-code representation
• The approach section of implementation units is thin and a higher-level technical design would provide context

Implementation Units

• Dependency order is unclear or likely wrong
• File paths or test file paths are missing where they should be explicit
• Units are too large, too vague, or broken into micro-steps
• Approach notes are thin or do not name the pattern to follow
• Test scenarios are vague (don't name inputs and expected outcomes), skip applicable categories (e.g., no error paths for a unit with failure modes, no integration scenarios for a unit crossing layers), or are disproportionate to the unit's complexity
• Feature-bearing units have blank or missing test scenarios (feature-bearing units require actual test scenarios; the Test expectation: none annotation is only valid for non-feature-bearing units)
• Verification outcomes are vague or not expressed as observable results
• Existing U-IDs were renumbered after a unit was reordered, split, or deleted (U-IDs are stable: never renumber existing IDs; gaps from deletions are preserved; new units take the next unused number)
• A unit realizing an origin Key Flow does not cite the F-ID, or a unit enforcing an origin Acceptance Example does not cite the AE-ID, when origin supplies them

System-Wide Impact

• Affected interfaces, callbacks, middleware, entry points, or parity surfaces are missing
• Failure propagation is underexplored
• State lifecycle, caching, or data integrity risks are absent where relevant
• Integration coverage is weak for cross-layer work

Risks & Dependencies / Documentation / Operational Notes

• Risks are listed without mitigation
• Rollout, monitoring, migration, or support implications are missing when warranted
• External dependency assumptions are weak or unstated
• Security, privacy, performance, or data risks are absent where they obviously apply

Use the plan's own Context & Research and Sources & References as evidence. If those sections cite a pattern, learning, or risk that never affects decisions, implementation units, or verification, treat that as a confidence gap.

5.3.4 Report and Dispatch Targeted Research

Before dispatching agents, report what sections are being strengthened and why:

Strengthening [section names] — [brief reason for each, e.g., "decision rationale is thin", "cross-boundary effects aren't mapped"]

For each selected section, choose the smallest useful agent set. Do not run every agent. Use at most 1-3 agents per section and usually no more than 8 agents total.

Use fully-qualified agent names inside Task calls.

Deterministic Section-to-Agent Mapping:

Requirements / Open Questions classification

• ce-spec-flow-analyzer for missing user flows, edge cases, and handoff gaps
• ce-repo-research-analyst (Scope: architecture, patterns) for repo-grounded patterns, conventions, and implementation reality checks

Context & Research / Sources & References gaps

• ce-learnings-researcher for institutional knowledge and past solved problems
• ce-framework-docs-researcher for official framework or library behavior
• ce-best-practices-researcher for current external patterns and industry guidance
• Add ce-git-history-analyzer only when historical rationale or prior art is materially missing

Key Technical Decisions

• ce-architecture-strategist for design integrity, boundaries, and architectural tradeoffs
• Add ce-framework-docs-researcher or ce-best-practices-researcher when the decision needs external grounding beyond repo evidence

High-Level Technical Design

• ce-architecture-strategist for validating that the technical design accurately represents the intended approach and identifying gaps
• ce-repo-research-analyst (Scope: architecture, patterns) for grounding the technical design in existing repo patterns and conventions
• Add ce-best-practices-researcher when the technical design involves a DSL, API surface, or pattern that benefits from external validation

Implementation Units / Verification

• ce-repo-research-analyst (Scope: patterns) for concrete file targets, patterns to follow, and repo-specific sequencing clues
• ce-pattern-recognition-specialist for consistency, duplication risks, and alignment with existing patterns
• Add ce-spec-flow-analyzer when sequencing depends on user flow or handoff completeness

System-Wide Impact

• ce-architecture-strategist for cross-boundary effects, interface surfaces, and architectural knock-on impact
• Add the specific specialist that matches the risk:
• ce-performance-oracle for scalability, latency, throughput, and resource-risk analysis
• ce-security-sentinel for auth, validation, exploit surfaces, and security boundary review
• ce-data-integrity-guardian for migrations, persistent state safety, consistency, and data lifecycle risks

Risks & Dependencies / Operational Notes

• Use the specialist that matches the actual risk:
• ce-security-sentinel for security, auth, privacy, and exploit risk
• ce-data-integrity-guardian for persistent data safety, constraints, and transaction boundaries
• ce-data-migration-expert for migration realism, backfills, and production data transformation risk
• ce-deployment-verification-agent for rollout checklists, rollback planning, and launch verification
• ce-performance-oracle for capacity, latency, and scaling concerns

Agent Prompt Shape:

For each selected section, pass:

• The scope prefix from the mapping above when the agent supports scoped invocation
• A short plan summary
• The exact section text
• Why the section was selected, including which checklist triggers fired
• The plan depth and risk profile
• A specific question to answer

Instruct the agent to return:

• findings that change planning quality
• stronger rationale, sequencing, verification, risk treatment, or references
• no implementation code
• no shell commands

5.3.5 Choose Research Execution Mode

Use the lightest mode that will work:

• Direct mode - Default. Use when the selected section set is small and the parent can safely read the agent outputs inline.
• Artifact-backed mode - Use only when the selected research scope is large enough that inline returns would create unnecessary context pressure.

Signals that justify artifact-backed mode:

• More than 5 agents are likely to return meaningful findings
• The selected section excerpts are long enough that repeating them in multiple agent outputs would be wasteful
• The topic is high-risk and likely to attract bulky source-backed analysis

If artifact-backed mode is not clearly warranted, stay in direct mode.

Artifact-backed mode uses a per-run OS-temp scratch directory. Create it once before dispatching sub-agents and capture its absolute path — pass that absolute path to each sub-agent so they write to it directly. Do not use .context/; the artifacts are per-run throwaway that are cleaned up when deepening ends (see 5.3.6b), matching the repo Scratch Space convention for one-shot artifacts. Do not pass unresolved shell-variable strings to sub-agents; they need the resolved absolute path.

SCRATCH_DIR="$(mktemp -d -t ce-plan-deepen-XXXXXX)"
echo "$SCRATCH_DIR"

Refer to the echoed absolute path as <scratch-dir> throughout the rest of this workflow.

5.3.6 Run Targeted Research

Launch the selected agents in parallel using the execution mode chosen above. If the current platform does not support parallel dispatch, run them sequentially instead. Omit the mode parameter when dispatching so the user's configured permission settings apply.

Prefer local repo and institutional evidence first. Use external research only when the gap cannot be closed responsibly from repo context or already-cited sources.

If a selected section can be improved by reading the origin document more carefully, do that before dispatching external agents.

Direct mode: Have each selected agent return its findings directly to the parent. Keep the return payload focused: strongest findings only, the evidence or sources that matter, the concrete planning improvement implied by the finding.

Artifact-backed mode: For each selected agent, pass the absolute <scratch-dir> path captured earlier and instruct the agent to write one compact artifact file inside that directory, then return only a short completion summary. Each artifact should contain: target section, why selected, 3-7 findings, source-backed rationale, the specific plan change implied by each finding. No implementation code, no shell commands.

If an artifact is missing or clearly malformed, re-run that agent or fall back to direct-mode reasoning for that section.

If agent outputs conflict:

• Prefer repo-grounded and origin-grounded evidence over generic advice
• Prefer official framework documentation over secondary best-practice summaries when the conflict is about library behavior
• If a real tradeoff remains, record it explicitly in the plan

5.3.6b Interactive Finding Review (Interactive Mode Only)

Skip this step in auto mode — proceed directly to 5.3.7.

In interactive mode, present each agent's findings to the user before integration. For each agent that returned findings:

1. Summarize the agent and its target section — e.g., "The ce-architecture-strategist reviewed Key Technical Decisions and found:" 2. Present the findings concisely — bullet the key points, not the raw agent output. Include enough context for the user to evaluate: what the agent found, what evidence supports it, and what plan change it implies. 3. Ask the user using the platform's blocking question tool when available (see Interaction Method):

• Accept — integrate these findings into the plan
• Reject — discard these findings entirely
• Discuss — the user wants to talk through the findings before deciding

If the user chooses "Discuss", engage in brief dialogue about the findings and then re-ask with only accept/reject (no discuss option on the second ask). The user makes a deliberate choice either way.

When presenting findings from multiple agents targeting the same section, present them one agent at a time so the user can make independent decisions. Do not merge findings from different agents before showing them.

After all agents have been reviewed, carry only the accepted findings forward to 5.3.7.

If the user accepted no findings, report "No findings accepted — plan unchanged." Then proceed directly to Phase 5.4 (skip document-review and synthesis — the plan was not modified). This interactive-mode-only skip does not apply in auto mode; auto mode always proceeds through 5.3.7 and 5.3.8. No explicit scratch cleanup needed — $SCRATCH_DIR is OS temp and will be cleaned up by the OS; leaving it in place preserves the rejected agent artifacts for debugging.

If findings were accepted and the plan was modified, proceed through 5.3.7 and 5.3.8 as normal — document-review acts as a quality gate on the changes.

5.3.7 Synthesize and Update the Plan

Strengthen only the selected sections. Keep the plan coherent and preserve its overall structure.

In interactive mode: Only integrate findings the user accepted in 5.3.6b. If some findings from different agents touch the same section, reconcile them coherently but do not reintroduce rejected findings.

Allowed changes:

• Clarify or strengthen decision rationale
• Tighten requirements trace or origin fidelity
• Reorder or split implementation units when sequencing is weak — but never renumber existing U-IDs. Reordering preserves U-IDs in their new order (e.g., U1, U3, U5 reordered is correct; renumbering to U1, U2, U3 is not). Splitting keeps the original U-ID on the original concept and assigns the next unused number to the new unit. Renumbering breaks ce-work blocker and verification references that were written against the original IDs
• Add missing pattern references, file/test paths, or verification outcomes
• Expand system-wide impact, risks, or rollout treatment where justified
• Reclassify open questions between Resolved During Planning and Deferred to Implementation when evidence supports the change
• Strengthen, replace, or add a High-Level Technical Design section when the work warrants it and the current representation is weak
• Strengthen or add per-unit technical design fields where the unit's approach is non-obvious
• Add or update deepened: YYYY-MM-DD in frontmatter when the plan was substantively improved

Do not:

• Add implementation code — no imports, exact method signatures, or framework-specific syntax. Pseudo-code sketches and DSL grammars are allowed
• Add git commands, commit choreography, or exact test command recipes
• Add generic Research Insights subsections everywhere
• Rewrite the entire plan from scratch
• Invent new product requirements, scope changes, or success criteria without surfacing them explicitly
• Renumber existing U-IDs as part of reordering, splitting, deletion, or "tidying" the unit list. Deepening is the most likely accidental-renumber vector — preserve U-IDs even when the new order would look cleaner with sequential numbering

If research reveals a product-level ambiguity that should change behavior or scope:

• Do not silently decide it here
• Record it under Open Questions
• Recommend ce-brainstorm if the gap is truly product-defining

Plan Handoff

This file contains post-plan-writing instructions: document review, post-generation options, and issue creation. Load it after the plan file has been written and the confidence check (5.3.1-5.3.7) is complete.

5.3.8 Document Review

After the confidence check (and any deepening), run the ce-doc-review skill with mode:headless on the plan file. Pass mode:headless <plan-path> as the skill arguments. When this step is reached, it is mandatory — do not skip it because the confidence check already ran. The two tools catch different classes of issues.

Headless is the default at this phase because most users want to start work after planning, not adjudicate every reviewer concern up front. Headless applies safe_auto fixes silently and returns structured findings text — no walkthrough, no per-finding routing, no blocking prompts. The post-generation menu (see 5.4) offers Run deeper doc review as a first-class option so users can opt into the full interactive walkthrough when they want it.

The confidence check and ce-doc-review are complementary:

• The confidence check strengthens rationale, sequencing, risk treatment, and grounding
• Document-review checks coherence, feasibility, scope alignment, and surfaces role-specific issues

Capture the headless envelope so it can drive the contextual summary above the post-generation menu:

• The number of fixes auto-applied
• The count of remaining findings, broken out by user-facing bucket (proposed fixes, decisions, FYI observations)
• The severity breakdown of decisions and proposed fixes (specifically the P0/P1 count, since those benefit from explicit user attention)

When ce-doc-review returns "Review complete", proceed to Final Checks.

Pipeline mode: Pipeline runs (LFG or any disable-model-invocation context) also run ce-doc-review with mode:headless and the plan path — the headless mode is identical to the interactive default at this phase. No further routing is offered in pipeline mode; the caller decides what to do with the returned findings. Address any P0/P1 findings before returning control to the caller.

5.3.9 Final Checks and Cleanup

Before proceeding to post-generation options:

• Confirm the plan is stronger in specific ways, not merely longer
• Confirm the planning boundary is intact
• Confirm origin decisions were preserved when an origin document exists

If artifact-backed mode was used:

• Clean up the temporary scratch directory after the plan is safely updated
• If cleanup is not practical on the current platform, note where the artifacts were left

5.4 Post-Generation Options

Pipeline mode: If invoked from an automated workflow such as LFG or any disable-model-invocation context, skip the interactive menu below and return control to the caller immediately. The plan file has already been written, the confidence check has already run, and ce-doc-review has already run — the caller (e.g., lfg) determines the next step.

Path format: Use absolute paths for chat-output file references — relative paths are not auto-linked as clickable in most terminals.

Summary line above the menu (always): Print a single concise line summarizing the headless review state — e.g., Doc review applied 3 fixes. 2 decisions, 1 proposed fix, 4 FYI observations remain (1 at P1). When no fixes were applied and no findings remain, print Doc review clean — no fixes needed. This line establishes what the autofix pass did so the user has the context to choose between the menu options below.

Question: "Plan ready at <absolute path to plan>. What would you like to do next?"

Options: 1. Start `/ce-work` (recommended) - Begin implementing this plan in the current session 2. Run deeper doc review - Walk through the remaining findings interactively (full ce-doc-review walkthrough) 3. Create Issue - Create a tracked issue from this plan in your configured issue tracker (GitHub or Linear) 4. Open in Proof (web app) — review and comment to iterate with the agent - Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others 5. Done for now - Pause; the plan file is saved and can be resumed later

Menu rendering: The menu has 5 options, which exceeds the AskUserQuestion 4-option cap. Per the AGENTS.md narrow exception for legitimate option overflow, render this menu as a numbered list in chat with the hint "Pick a number or describe what you want." rather than trimming to fit the cap. Each option is a distinct destination/workflow and none are removable without losing real user choice (deeper review, issue creation, Proof, ce-work, and pause are each separately requested in practice). On platforms where blocking question tools have no option cap (e.g., Codex request_user_input, Pi ask_user), use the platform's blocking tool with all 5 options. When the platform's blocking tool is unavailable or errors (e.g., Codex edit modes where request_user_input is not exposed, or ask_user returns no match), fall back to the same numbered-list-in-chat rendering with the "Pick a number or describe what you want." hint — the same fallback the AskUserQuestion overflow path uses. Never silently skip the question.

Hide `Run deeper doc review` when no actionable findings remain. Show option 2 only when the headless envelope reports proposed_fixes_count + decisions_count > 0 — i.e., at least one gated_auto or manual finding at confidence anchor 75 or 100. Drop the option in any other case, including FYI-only state. FYI observations (anchor 50) do not enter ce-doc-review's interactive routing question or walkthrough — that flow is gated to actionable findings — so a Run deeper doc review option that only has FYIs to show is a dead-end: ce-doc-review would re-dispatch the persona team, find the same FYIs, skip the routing question, and fall through to the terminal question with nothing to walk through. The user paid the dispatch cost for no engagement surface. When option 2 is dropped, the menu becomes 4 options (1, 3, 4, 5 above), falls back to AskUserQuestion on Claude Code, and renumbers 1-4 in display so users see a clean sequence. The summary line above the menu still names the FYI count when present (Doc review applied 3 fixes. 2 FYI observations remain.) so the user sees what was found, even though there is no menu action attached to it — the FYIs are visible in the headless envelope text the menu rendered alongside.

Based on selection (the bare per-option routing is also stated inline in the SKILL.md so it cannot be missed when this reference is not loaded; the elaborate sub-flows below are the reason this reference still exists):

• Start `/ce-work` -> Invoke the ce-work skill via the platform's skill-invocation primitive (Skill in Claude Code, Skill in Codex, the equivalent on Gemini/Pi), passing the plan path as the skill argument. Do not merely tell the user to type /ce-work — fire the invocation now so the plan executes in this session.
• Run deeper doc review -> Re-invoke the ce-doc-review skill on the plan path without mode:headless so the interactive routing question and walkthrough fire. The headless pass already applied safe_auto fixes and recorded its findings in the session, so the interactive pass picks up where headless stopped — its R29 suppression rule prevents prior-round Skipped/Deferred entries from re-raising. After it returns, re-render this menu with the refreshed counts so the user can pick what to do next.
• Create Issue -> Follow the Issue Creation section below
• Open in Proof (web app) — review and comment to iterate with the agent -> Load the ce-proof skill in HITL-review mode with:
• source file: docs/plans/<plan_filename>.md
• doc title: Plan: <plan title from frontmatter>
• identity: ai:compound-engineering / Compound Engineering
• recommended next step: /ce-work (shown in the ce-proof skill's final terminal output)

Follow references/hitl-review.md in the ce-proof skill. It uploads the plan, prompts the user for review in Proof's web UI, ingests each thread by reading it fresh and replying in-thread, applies agreed edits as tracked suggestions, and syncs the final markdown back to the plan file atomically on proceed.

When the ce-proof skill returns:

• status: proceeded with localSynced: true -> the plan on disk now reflects the review. Re-run ce-doc-review on the updated plan before re-rendering the menu — HITL can materially rewrite the plan body, so the prior ce-doc-review pass no longer covers the current file and section 5.3.8 requires a review before any handoff option is offered. Then return to the post-generation options with the refreshed residual findings.
• status: proceeded with localSynced: false -> the reviewed version lives in Proof at docUrl but the local copy is stale. Offer to pull the Proof doc to localPath using the ce-proof skill's Pull workflow. If the pull happened, re-run ce-doc-review on the pulled file before re-rendering the options (same 5.3.8 rationale — the local plan was materially updated by the pull). If the pull was declined, include a one-line note above the menu that <localPath> is stale vs. Proof — otherwise Start /ce-work or Create Issue will silently use the pre-review copy.
• status: done_for_now -> the plan on disk may be stale if the user edited in Proof before leaving. Offer to pull the Proof doc to localPath so the local plan file stays in sync. If the pull happened, re-run ce-doc-review on the pulled file before re-rendering the options (same 5.3.8 rationale). If the pull was declined, include the stale-local note above the menu. done_for_now means the user stopped the HITL loop — it does not mean they ended the whole plan session; they may still want to start work or create an issue.
• status: aborted -> fall back to the options without changes.

If the initial upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the options — don't leave them wondering why the option did nothing.

• Done for now -> Display a brief confirmation that the plan file is saved and end the turn. Do not start follow-up work without an explicit further user prompt.
• Free-form prompts that target the findings (e.g., the user types "review", "walk through", "deep review" instead of picking a numbered option) -> route as if they had picked Run deeper doc review. Do not loop back to the menu without firing the deeper review.
• Other free-form input -> Accept revisions to the plan and loop back to options.

Issue Creation

When the user selects "Create Issue", detect their project tracker:

1. Read AGENTS.md (or CLAUDE.md for compatibility) at the repo root and look for project_tracker: github or project_tracker: linear. 2. If project_tracker: github:

   gh issue create --title "<type>: <title>" --body-file <plan_path>

3. If project_tracker: linear:

   linear issue create --title "<title>" --description "$(cat <plan_path>)"

4. If no tracker is configured, ask the user which tracker they use with 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 asking in chat only when no blocking tool exists or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip. Options: GitHub, Linear, Skip. Then:

• Proceed with the chosen tracker's command above
• Offer to persist the choice by adding project_tracker: <value> to AGENTS.md, where <value> is the lowercase tracker key (github or linear) — not the display label — so future runs match the detector in step 1 and skip this prompt
• If Skip, return to the options without creating an issue

5. If the detected tracker's CLI is not installed or not authenticated, surface a clear error (e.g., "gh CLI not found — install it or create the issue manually") and return to the options.

After issue creation:

• Display the issue URL
• Ask whether to proceed to /ce-work using the platform's blocking question tool

Synthesis Summary

Synthesis ≠ plan doc. The synthesis is the scope/decisions checkpoint that plan-write (Phase 5.2) consumes as input. The plan itself is written from the confirmed synthesis. The synthesis names the scope or plan-time decisions (what files to touch, which patterns to extend, what's deferred) at decision-level. The plan body expands those decisions into directional sketches (file paths, test scenarios, approach descriptions) per the Planning Rules — but never into exact method signatures, framework syntax, or code spec (Phase 4.3 forbids those in the plan body too). If the synthesis reads like a plan preview, it's misshaped — re-cut to scope/decisions-only.

Three-bucket structure is a chat-time artifact only. It does its scope-confirmation job in dialogue with the user, then dissolves when Phase 5.2 writes the plan: Stated content informs Requirements, Inferred content informs Key Technical Decisions / Implementation Units (interactive mode) or ## Assumptions (non-interactive mode), Out-of-scope content informs Scope Boundaries. The plan has no parallel ## Synthesis section — only the prose summary embeds, as ## Summary. See "Doc shape after confirmation" below for the routing.

This content is loaded when a synthesis-summary phase fires in ce-plan. There are two variants — they share structure but differ in timing and content focus:

• Solo variant (Phase 0.7): fires after Phase 0.4 bootstrap and Phase 0.6 depth classification, before Phase 1 research begins. Catches scope misinterpretation before sub-agent dispatch is spent. Full breadth — problem frame, intended behavior, success criteria, in/out scope.
• Brainstorm-sourced variant (Phase 5.1.5): fires after Phase 1 research, before Phase 5.2 plan-write. Focuses on plan-time decisions (which files/modules to touch, which patterns extended vs. introduced new, test scope, refactor scope). Brainstorm-validated WHAT is assumed and not re-stated.

Both variants share the three-bucket structure, open prose feedback, soft-cut behavior, and the doc-shape routing. In non-interactive (headless) mode, both compose the synthesis but skip the user confirmation step — Inferred bets route to a ## Assumptions section in the plan rather than to Key Technical Decisions. See "Headless mode (shared)" below for the full routing.

---

Three-bucket structure (shared)

Every synthesis is structured in three labeled buckets. Items may appear in two buckets when meaningfully both — flag the inclusion-then-exclusion as Inferred so the reader sees the agent's reasoning.

• Stated — what the user said directly (in the original prompt, prior conversation, dialogue answers, or the upstream brainstorm doc when present). Items here have explicit user-language anchors.
• Inferred — what the agent assumed to fill gaps. Scope boundaries the user never explicitly named, success criteria extrapolated from intent, technical assumptions made because the brief interview didn't probe them. The "Inferred" list is the most actionable bucket — items here are the agent's bets that the user can correct.
• Out of scope — deliberately excluded items. Adjacent work the agent considered but decided not to include, refactors, nice-to-haves, future-work items.

---

Synthesis structural discipline (shared)

Both variants share these structural rules. They address failure modes where the synthesis becomes a Phase 5.2 (plan-write) preview instead of a scope checkpoint.

Prose lives inside the synthesis section, immediately after the lead-in line and before the Stated bucket — not as a separate prose block above the synthesis. Putting extensive prose ABOVE the synthesis (an approach pitch, files-touched bullets, rationale block) inverts the structure: the synthesis becomes a footnote to the proposal instead of the proposal being a 1-3 line gloss on the synthesis.

Anti-pattern: synthesis as plan-pitch. Plan-body content — file paths, code shapes, sentinel strings, exact error messages, "Recommendation" / "Behavior when X" / "Why this shape" rationale — does not belong in the synthesis regardless of where it appears: not in a block above the buckets, not inside the prose summary, and not nested in an Inferred bullet's commentary or sub-bullets. The position rule and the content rule are independent: a structurally-legal placement (inside a bucket bullet) does not legitimize plan-body content. If you find yourself writing it anywhere, stop. That content is Phase 5.2 (plan-write) territory — it belongs in the plan body the next phase will write, not in the synthesis presentation. The synthesis is a scope/decisions checkpoint: three buckets plus a 1-3 line gloss. Implementation detail leaking into the synthesis (anywhere) is a sign Phases 1-4 (research and structuring) and Phase 5.2 (plan-write) have collapsed into the synthesis-confirmation step.

A revision is not a confirmation. After any user revision (even a trivially-understood swap), integrate the change, re-present the revised synthesis with the change reflected, and wait for explicit confirmation before writing the plan. The loop is:

1. Present synthesis → user responds 2. User confirms → write the plan 3. User revises → integrate, re-present revised synthesis, return to step 1

Plan-write (Phase 5.2) fires only on explicit confirm or after the soft-cut blocking question's "proceed" option. Never write immediately after a revision, even when the revision is small enough that the agent feels it understood — the confirmation step is what makes the synthesis confirmed rather than "agent's last proposal."

---

Granularity: name the decision; don't expand it (shared)

Each Inferred bullet should be affirmable or rejectable by the user without reading code. Name the decision at the granularity that lets the user say "yes" or "I want X instead." Anything more specific is plan-body content — Phase 5.2's job, not synthesis's.

Allowed (when these ARE the decisions being made):

• File / module names — "skip filter in the matcher" when "where to put it" is the choice
• Pattern names — "extends the existing event-skip pattern" when "extend vs. introduce" is the choice
• Column / table names — "user-TZ" or "destination-calendar TZ" when "which source" is the choice
• Approach posture — "DB-side query with Google-side fallback" when "which strategy" is the choice

Not allowed (always plan-body, regardless of variant):

• Line numbers (route.ts:249-255)
• Exact method signatures, call graphs, or implementation flow ("at the top, before include/exclude evaluation, returning ...")
• Exact JSON / response shapes ({pause, cleanup: {eventsDeleted, eventsFailed, errors}})
• HTTP status codes (409, 404, 403)
• Exact event / activity-log / type names (userPauseSet/userPauseEdited/...)
• Exact wording of error messages or UI labels
• SQL syntax or query bodies

The line is drawn slightly differently per variant. Solo (Phase 0.7) stays at the higher level — brainstorm's WHAT hasn't been validated yet, so file/module names are usually too specific; talk in terms of "the rule entity," not "syncRules table." Brainstorm-sourced (Phase 5.1.5) allows the file / module / pattern / column level when those ARE plan-time decisions, but not implementation flow specifics.

Bad-vs-good examples

The test: a scanner reading an Inferred bullet should affirm or reject it without needing to read code. If they would have to look up a column name, method name, or call graph to evaluate the bullet, the granularity is wrong — that's plan-body content.

---

Solo variant (Phase 0.7)

Fires only when:

• Phase 0.2 found no upstream brainstorm doc
• AND Phase 0.4 stayed in ce-plan (did not route to ce-debug, ce-work, or universal-planning)
• AND Phase 0.5 cleared (no unresolved blockers)
• AND not on Phase 0.1 fast paths (resume normal, deepen-intent)

Each guard is an explicit conditional in SKILL.md, not implicit. R2 solo does NOT fire on resume/deepen, route-out, or brainstorm-sourced paths.

Content focus: full-breadth synthesis. Phase 0.4 bootstrap is brief by design ("ask one or two clarifying questions"), so the agent has made substantial inferences before Phase 0.7 fires. The "Inferred" list is especially load-bearing here — surface the agent's bets explicitly.

Counter-warning for rich-context invocations. When the inference source is not just Phase 0.4 bootstrap — e.g., a prior in-conversation validation agent, completed sibling work units earlier in the same session, or a planning artifact already in the conversation — "surface bets explicitly" pulls toward dumping that material verbatim. The granularity rules tighten in this case, not loosen: the agent has more material to compress, not more material to expose. A bet that's already been validated upstream is Stated, not Inferred; a bet whose specifics belong in plan-body is named at decision-level here regardless of how much detail upstream context provided. If recent turns produced detailed code, file paths, or research artifacts, expect the synthesis draft to over-share and compress proactively before presenting.

Why pre-research, not pre-write: research effort would be wasted if scope is wrong. Catching scope errors before sub-agent dispatch (Phase 1.1's repo-research-analyst, learnings-researcher, etc.) saves token and time cost.

Prompt template (solo)

Prose summary discipline (required for all tiers): start with a 1-3 line summary in plain prose describing what scope the plan will target. Forward-looking (what will be planned), not retrospective (what's been discussed in Phase 0.4 bootstrap). The prose's job is to help the user pattern-match against intent before reading bullets — solo invocation has minimal pre-write dialogue, so the prose is especially load-bearing here. Even Lightweight benefits from a gestalt; the only legitimate skip is the truly-trivial case (e.g., the prompt was itself a complete scope statement and the synthesis is one or two Stated bullets that just echo it).

Anti-fluff guidance: lead with the actual thing being planned in plain words. No qualifiers ("comprehensive," "thoughtful," "substantive"). No re-stating the user's prompt. If you can't say what the scope is in 1-3 lines without filler, the synthesis isn't ready yet.

Based on your request and our brief Phase 0.4 bootstrap, here's the scope I'm proposing to plan against:

[1-3 line prose summary — what scope the plan will target, in plain language. Required for all tiers; skip only for truly-trivial cases where the synthesis is ≤ 2 bullets that echo the prompt.]

**Stated** (from your input and our dialogue):
- [item]

**Inferred** (gaps I filled with assumptions — Phase 0.4 is brief by design, so this list is load-bearing; flag anything I got wrong):
- [problem frame inference]
- [success criteria inference]
- [scope boundary inference]
- [technical approach assumption]

**Out of scope** (deliberately excluded):
- [adjacent work]
- [refactor]
- [nice-to-have]

Does this match your intent? Tell me what to add, remove, redirect, or that I got wrong — or just confirm to proceed. (You can also redirect to /ce-brainstorm if this is bigger than you initially thought — I'll stop here and load it for you.)

Use prose for the user response (no AskUserQuestion menu). Justification is Interaction Rule 5(a) in SKILL.md.

---

Brainstorm-sourced variant (Phase 5.1.5)

Fires only when:

• Phase 0.2 found upstream brainstorm doc (brainstorm-sourced invocation)
• AND not on Phase 0.1 fast paths

Content focus: plan-time decisions only. The brainstorm + R1 synthesis already validated WHAT to build; this synthesis surfaces HOW the plan will execute that work — decisions the brainstorm did not make.

Items to surface:

• Files/modules to touch (and not touch) — what the implementation reaches into
• Patterns extended vs. introduced new — architectural decisions the agent made within confirmed scope (R2's content focus, not bias toward either direction)
• Test scope — which existing-but-untested code is in/out of test scope for this work
• Refactor scope — adjacent cleanup, if any, going to deferred items vs. active diff
• Cross-cutting impact — auth, migrations, shared types when they're touched

Reads from doc body, not a synthesis section: brainstorm docs do not have a ## Synthesis section (the synthesis is a chat-time artifact in ce-brainstorm; only the prose summary embeds, as ## Summary). Phase 5.1.5 derives plan-time decisions from the brainstorm doc's body sections — Summary, Problem Frame, Requirements, Key Decisions, Scope Boundaries — plus Phase 1 research. Older brainstorms that may have a legacy ## Synthesis section work fine; that content is treated as supplementary, not authoritative, with the body sections taking precedence.

Why pre-write, not pre-research: brainstorm doc + R1 synthesis already validated WHAT, so research is well-targeted. Plan-time decisions emerge during research and structuring (Phases 1-4), so pre-write catches them at the latest cheap moment — before Phase 5.2 commits the plan to disk.

Prompt template (brainstorm-sourced)

Prose summary discipline (required for all tiers): start with a 1-3 line summary in plain prose describing how the implementation approaches the work at a high level — files/modules touched, patterns extended vs. introduced, scope boundaries the plan honors. Forward-looking (what will be in the plan), not retrospective. Brainstorm-validated WHAT is assumed; the prose summarizes HOW. Even Lightweight benefits from a gestalt; the only legitimate skip is the truly-trivial case (e.g., a one-line refactor where the synthesis is one or two Stated bullets that just echo the prompt).

Anti-fluff guidance: lead with the actual implementation shape in plain words. No qualifiers, no re-stating the brainstorm's WHAT. If the prose just restates the brainstorm's Problem Frame, rewrite it to focus on plan-time decisions.

Based on the upstream brainstorm and Phase 1 research, here's the implementation scope I'm proposing for the plan:

[1-3 line prose summary — how the implementation approaches the work (files/modules, patterns, scope honored), in plain language. Brainstorm-validated WHAT is assumed; this summarizes HOW. Required for all tiers; skip only for truly-trivial cases where the synthesis is ≤ 2 bullets that echo the prompt.]

**Stated** (from brainstorm + research findings):
- [files/modules implicitly named in brainstorm or surfaced by repo-research]
- [patterns identified for extension or reuse]

**Inferred** (plan-time decisions filling gaps the brainstorm didn't resolve):
- [pattern extension vs. new abstraction choice]
- [test scope additions]
- [cross-cutting impact assessment]

**Out of scope** (deliberately excluded):
- [tangential refactors going to Deferred to Follow-Up Work]
- [adjacent untested code intentionally excluded from test scope]

Does this match your intent for HOW to implement? Tell me what to add, remove, or redirect — or just confirm to proceed.

Use prose for the user response. Justification is Interaction Rule 5(a).

---

Soft-cut on circularity (shared)

Track which Stated/Inferred/Out items the user touched per round. The soft-cut blocking question fires only when the same item is revised twice (or a third-round revision targets an item already revised in round two). New-item revisions across rounds proceed without limit.

When the soft-cut fires, use the platform's blocking question tool with two options:

• Proceed with the current revised synthesis
• Stop and redirect — discuss further before [research / plan-write]

Fall back to numbered list in chat only when no blocking tool exists or the call errors. Never silently skip.

---

Headless mode (shared)

When the skill is invoked from an automated workflow such as LFG or any disable-model-invocation context, the skill runs in non-interactive mode (no synchronous user). The artifact is read by downstream skills (ce-doc-review, ce-work) and human reviewers (PR review).

Per-variant behavior (the timing matters for which phases follow):

• Solo variant (Phase 0.7): Phase 0.7 fires before research. In non-interactive mode, compose the synthesis but skip the user confirmation step. Continue to Phase 1 research as normal. Inferred content is held until plan-write (Phase 5.2), where it routes to ## Assumptions.
• Brainstorm-sourced variant (Phase 5.1.5): Phase 5.1.5 fires after research, before plan-write. Compose the synthesis but skip the user confirmation step. Proceed to Phase 5.2 plan-write. Inferred content routes to ## Assumptions.

Shared behavior across both variants:

• No user prompt; no blocking question. Skip the confirmation step.
• Route content with mode-aware shape:
• Stated content → Requirements (user-stated constraints, traced to origin's R-IDs when present)
• Out-of-scope content → Scope Boundaries
• Inferred content → ## Assumptions section in the plan — explicitly labeled as un-validated agent bets. Do NOT route Inferred items into Key Technical Decisions or Implementation Units; that would make un-validated bets indistinguishable from user-confirmed decisions.

The ## Assumptions section appears in non-interactive plans only. Interactive plans don't need it (Inferred bets get user-corrected in chat and become Key Technical Decisions or are revised away).

This restores the audit visibility the original design intended (un-validated bets must not propagate as authoritative content), but surfaces them under their own label rather than hiding them. Downstream review (ce-doc-review, ce-work, human PR review) can scrutinize Assumptions specifically.

---

Self-redirect (shared)

If the user response indicates they're in the wrong skill or want a different workflow:

• Solo variant: common redirects include "this is bigger than I thought — let me brainstorm first" (suggest /ce-brainstorm), "this is just a fix, no plan needed" (suggest /ce-work), or "I need to investigate first" (suggest /ce-debug).
• Brainstorm-sourced variant: less common, but possible — "actually this scope is wrong, take it back to brainstorm" (suggest /ce-brainstorm to revise the upstream doc).

In either case: stop ce-plan, suggest the alternative skill, offer to load it in-session. Don't push back or argue — the user's redirect signal is the deliberate choice.

---

Doc shape after confirmation

After user confirmation (or after the soft-cut decision proceeds), Phase 5.2 writes the plan doc. The three-bucket structure does NOT carry into the plan as a ## Synthesis section. Only the prose summary embeds, replacing the existing ## Overview slot in the plan template (renamed to ## Summary for terminology consistency). Bucket content dissolves into the plan's body sections:

No italic capture-context note (e.g., "Captured at Phase 0.7..."). It would leak engineering process into an artifact whose readers do not need that signal.

The plan's ## Summary and ## Problem Frame must serve distinct purposes: Summary answers "what is this plan proposing?" (forward-looking, 1-3 lines); Problem Frame answers "why does this proposal exist?" (backward-looking, paragraphs). Don't restate the proposal in Problem Frame; don't pad Summary with situational context.

---

What does NOT belong in the synthesis

• Implementation code (no imports, exact method signatures, framework-specific syntax, JSON shapes, exact error message wording)
• Re-statement of the entire brainstorm doc — the synthesis is plan-perspective, not a copy
• Defensive what-ifs and hedges — if a concern is real, state it as Inferred or Out; if speculation, drop it
• Open questions surfaced outside the three buckets — by synthesis time, every scope-shaping question must be in Stated (asked and answered earlier), Inferred (agent's bet for correction), or Out (deliberately excluded). There is no fourth status. If a question genuinely cannot be defaulted, pause synthesis and resolve it before presenting — pick the question shape that matches: a blocking multiple-choice tool when options are bounded and meaningfully distinct, prose when option sets would bias the answer per Interaction Rule 5(a). Integrate the answer, then present synthesis. Never present synthesis with adjacent floating questions — that gives the user no clear resolution path

Universal Planning Workflow

This file is loaded when ce-plan detects a non-software task (Phase 0.1b). It replaces the software-specific phases (0.2 through 5.1) with a domain-agnostic planning workflow.

Before starting: verify classification

The detection stub in SKILL.md routes here for anything that isn't clearly software. Verify the classification is correct before proceeding:

• Is this actually a software task? The key distinction is task-type, not topic-domain. A study guide about Rust is non-software (producing educational content). A Rust library refactor is software (modifying code). If this is actually software, return to Phase 0.2 in the main SKILL.md.
• Is this a quick-help request, not a planning task? Error messages, factual questions, and single-step tasks don't need a plan. Respond directly and exit. Examples: "zsh: command not found: brew", "what's the capital of France."
• Pipeline mode? If invoked from LFG or any disable-model-invocation context: output "This is a non-software task. The LFG pipeline requires ce-work, which only supports software tasks. Use /ce-plan directly for non-software planning." and stop.

Once past these checks, commit to producing a plan. Do not exit because the task looks like a "lookup" or "research question" — the user invoked ce-plan because they want a structured output.

---

Step 1: Assess Ambiguity and Research Need

Evaluate two things before planning:

Would 1-3 quick questions meaningfully improve this plan?

• Default: ask 1-3 questions via Step 1b when the answers would change the plan's structure or content. Always include a final option like "Skip — just make the plan with reasonable assumptions" so the user can opt out instantly.
• Skip questions entirely only when the request already specifies all major variables or the task is simple enough that reasonable assumptions cover it well.

Research need — does this plan depend on facts that change faster than training data?

When research is recommended, do it — don't just offer. Stale recommendations (closed restaurants, rethemed attractions, outdated prices) are worse than no recommendations. The user invoked /ce-plan because they want a good plan, not a disclaimer about training data.

Research decomposition pattern: 1. Identify 2-5 independent research questions based on the task. Good questions target facts the model is least confident about: current prices, hours, availability, recent changes, seasonal specifics. 2. Dispatch parallel research. Prefer user-named surfaces first per Core Principle 8 in SKILL.md; fall back to web search for questions those surfaces don't cover. 3. Collate findings into a brief research summary before proceeding to planning.

Example for "plan a date night in Seattle this Saturday":

• "Best restaurants open late Saturday in Capitol Hill Seattle 2026"
• "Events happening in Seattle [specific date]"
• "Seattle waterfront current status and hours"

Step 1b: Focused Q&A

Ask up to 3 questions targeting the unknowns that would most change the plan. 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 or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

How to ask well:

• Offer informed options, not open-ended blanks. Instead of "When are you going?", try "Mid-week visits have 30-40% shorter lines — are you flexible on timing?" The question should give the user a frame of reference, not just extract information.
• Use multi-select when several independent choices can be captured in one question. This is compact and respects the user's time.
• Always include a final option like "Skip — just make the plan with reasonable assumptions" so the user can opt out at any point.

Focus on the unknowns specific to this task that would change what the plan recommends or how it's structured. Do not ask more than 3 — after that, proceed with assumptions for anything remaining.

Step 2: Structure the Plan

Create a structured plan guided by these quality principles. Do NOT use the software plan template (implementation units, test scenarios, file paths, etc.).

Format: when to prescribe vs. present options

Not every plan should be a single linear path. Match the format to the task:

Example: A date night plan should present 2-3 restaurant options, 2-3 activity options, and a suggested flow — not pick one restaurant and build the whole evening around it. A study plan should prescribe a single weekly progression — not present 3 different curricula to choose from.

Formatting: bullets over prose

• Prefer bullets and tables for actionable content (steps, options, logistics, budgets)
• Use prose only for context, rationale, or explanations that connect the dots
• Plans are for scanning and executing, not reading cover-to-cover

Quality principles

• Actionable steps: Each step is specific enough to execute without further research
• Sequenced by dependency: Steps are in the right order, with dependencies noted
• Time-aware: When relevant, include timing, durations, deadlines, or phases
• Resource-identified: Specify what's needed — tools, materials, people, budget, locations
• Contingency-aware: For important decisions, note alternatives or what to do if plans change
• Appropriately detailed: Match detail to task complexity. A weekend trip needs less structure than a 3-month curriculum. A dinner plan should be concise, not a 200-line document.
• Domain-appropriate format: Choose a structure that fits the domain:
• Itinerary for travel (day-by-day, with times and locations)
• Syllabus or curriculum for study plans (topics, resources, milestones)
• Runbook for events (timeline, responsibilities, logistics)
• Project plan for business or operational tasks (phases, owners, deliverables)
• Research plan for investigations (questions, methods, sources)
• Options menu for preference-driven tasks (curated picks per category)

Step 3: Save or Share

After structuring the plan, ask the user how they want to receive it using 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 or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Question: "Plan ready. How would you like to receive it?"

Options:

1. Save to disk — Write the plan as a markdown file. Ask where:

• docs/plans/ (only show if this directory exists)
• Current working directory
• /tmp
• A custom path
• Use filename convention: YYYY-MM-DD-<descriptive-name>-plan.md
• Start the document with a # Title heading, followed by Created: YYYY-MM-DD on the next line. No YAML frontmatter.

2. Open in Proof (web app) — review and comment to iterate with the agent — Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others. Load the ce-proof skill to create and open the document.

3. Save to disk AND open in Proof — Do both: write the markdown file to disk and open the doc in Proof for review.

Do not offer /ce-work (software-only) or issue creation (not applicable to non-software plans).

Visual Communication in Plan Documents

Section 3.4 covers diagrams about the solution being planned (pseudo-code, mermaid sequences, state diagrams). The existing Section 4.3 mermaid rule encourages those solution-design diagrams within Technical Design and per-unit fields. This guidance covers a different concern: visual aids that help readers navigate and comprehend the plan document itself -- dependency graphs, interaction diagrams, and comparison tables that make plan structure scannable.

Visual aids are conditional on content patterns, not on plan depth classification -- a Lightweight plan about a complex multi-unit workflow may warrant a dependency graph; a Deep plan about a straightforward feature may not.

When to include:

When to skip:

• The plan has 3 or fewer units in a straight dependency chain -- the Dependencies field on each unit is sufficient
• Prose already communicates the relationships clearly
• The visual would duplicate what the High-Level Technical Design section already shows
• The visual describes code-level detail (specific method names, SQL columns, API field lists)

Format selection:

• Mermaid (default) for dependency graphs and interaction diagrams -- 5-15 nodes, no in-box annotations, standard flowchart shapes. Use TB (top-to-bottom) direction so diagrams stay narrow in both rendered and source form. Source should be readable as fallback in diff views and terminals.
• ASCII/box-drawing diagrams for annotated flows that need rich in-box content -- file path layouts, decision logic branches, multi-column spatial arrangements. More expressive than mermaid when the diagram's value comes from annotations within nodes. Follow 80-column max for code blocks, use vertical stacking.
• Markdown tables for mode/variant comparisons and decision/approach comparisons.
• Keep diagrams proportionate to the plan. A 6-unit linear chain gets a simple 6-node graph. A complex dependency graph with fan-out and fan-in may need 10-15 nodes -- that is fine if every node earns its place.
• Place inline at the point of relevance, not in a separate section.
• Plan-structure level only -- unit dependencies, component interactions, mode comparisons, impact surfaces. Not implementation architecture, data schemas, or code structure (those belong in Section 3.4).
• Prose is authoritative: when a visual aid and its surrounding prose disagree, the prose governs.

After generating a visual aid, verify it accurately represents the plan sections it illustrates -- correct dependency edges, no missing surfaces, no merged units.