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

#$ARGUMENTS

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.0 Resolve Output Mode

Determine OUTPUT_FORMAT before any other phase fires. Output mode is exclusive — the plan is written as either markdown (.md) OR HTML (.html), never both. Precedence: CLI arg > config > default (md), with a hard pipeline-mode override.

Read config (pre-resolved at skill load): !cat "$(git rev-parse --show-toplevel 2>/dev/null)/.compound-engineering/config.local.yaml" 2>/dev/null || echo '__NO_CONFIG__'

Resolution steps:

1. CLI arg. Scan $ARGUMENTS for a token starting with the literal prefix output:. If found, strip it from arguments before treating the remainder as the feature description, and match its value case-insensitively against md and html.
   • output: alone (no value) → no-op, fall through to step 2.
   • output:<unknown> (e.g., output:pdf) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-generation menu after final resolution: Ignored unknown output: value '<value>' — using <resolved_format> instead. where <resolved_format> is the value OUTPUT_FORMAT actually resolved to after steps 2-4. Do not hardcode md in the note — that misleads users when config has set HTML.
2. Config. If step 1 did not resolve and the pre-resolved YAML above has an active (non-commented) plan_output: key whose value matches md or html (case-insensitive), use it. Missing, invalid, or commented values fall through silently. Critical: lines starting with # are YAML comments and must be ignored — the shipped config template includes commented examples like # plan_output: html to document the option, and matching those as active settings would silently force HTML mode on every run without the user having opted in.
3. Default. Otherwise OUTPUT_FORMAT=md.
4. Pipeline override. When invoked from LFG or any disable-model-invocation context, force OUTPUT_FORMAT=md regardless of steps 1-3. ce-work and other automated downstream consumers parse markdown reliably; HTML in pipeline runs is unnecessary friction.

Token-parsing convention: only literal-prefix flag tokens (output:, mode:, delegate: where applicable) are consumed and stripped. Other <word>:<word> tokens — including conventional commit prefixes like feat:, fix:, chore: that may appear inside a feature description — pass through verbatim.

Load the format-rendering reference based on the resolved value. Section content is the same in either format; presentation differs. Both references are paired with references/plan-sections.md, which describes what the plan contains regardless of format.

• When OUTPUT_FORMAT=md, read references/markdown-rendering.md for format principles.
• When OUTPUT_FORMAT=html, read references/html-rendering.md for format principles.

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

• Routing is keyed on file extension first, then frontmatter. HTML plans (.html) are always software plans — the html-rendering invariant forbids YAML frontmatter, so frontmatter absence is not a non-software signal for HTML. Treat the visible-header metadata (title, date) as the frontmatter equivalent.
  • .html plan: short-circuit to Phase 5.3 (Confidence Check and Deepening) in interactive mode. Never route to references/universal-planning.md based on missing YAML.
  • .md plan WITH YAML frontmatter: short-circuit to Phase 5.3 in interactive mode.
  • .md plan WITHOUT YAML frontmatter (non-software plans use a simple # Title heading with Created: date instead): 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.

The Phase 5.3 short-circuit 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.

Resume preserves the existing artifact's format, except pipeline mode. When resuming an existing plan, the resume run writes back in whatever format the existing artifact uses — markdown if the existing file is .md, HTML if it is .html — so a resume doesn't silently change the artifact shape. Explicit output: arguments on this run override (e.g., resuming an .html plan with output:md switches the artifact to markdown). Pipeline mode (LFG, any disable-model-invocation context) always wins per Phase 0.0: even when resuming an existing .html plan, pipeline runs force OUTPUT_FORMAT=md so downstream automation receives the markdown shape it expects. The resume rewrites the markdown file at the parallel path (<plan-basename>.md) and the original .html is left in place untouched.

0.1a Recognize Approach-Altitude Requests

Some requests are better answered one level up: produce a grounded approach-plan — a plan for how the deliverable will be made — and hold there, rather than zero-shotting the deliverable. This runs after Phase 0.1's resume and deepen fast paths (so "deepen the plan" and resume short-circuit first) and before Phase 0.1b's domain split (so the capability is domain-general — it applies to software and knowledge-work alike).

Two entries, with very different gating:

Explicit (always honored, ungated). When the user asks for the approach itself — "plan for a plan", "plan the approach", "plan how you'll do X", "don't do it yet -- just plan how you'd approach it" — enter approach altitude and hold at the approach. Do NOT begin the deliverable. Key on language that asks for the approach to producing something, not the something. This is a distinct signal from "deepen"/"strengthen" (the Phase 0.1 deepening fast path) and from a normal plan request.

Proactive (rare, conservative). When the user gives a plain request with no approach-language, offer an approach-plan only when both of these are clearly high:

• Method uncertainty — the core approach is genuinely unsettled: competing methodologies that would yield different deliverables, unclear how disparate sources or constraints combine, or an outcome stated only at the value level ("something I can actually use"). This is not satisfied by a task whose core method is obvious but whose rollout, sequencing, scope, or ordering has routine variants (big-bang vs. incremental, batch order, phased vs. one-shot) — those are ordinary plan decisions the Phase 0.7 scoping synthesis already surfaces as call-outs, not method-uncertainty. A large or mechanical change (a 40-endpoint migration, a wide rename, a framework bump) is typically costly but method-obvious; cost alone never fires the offer.
• Cost of getting it wrong — the deliverable is expensive or slow to produce and a wrong approach wastes real effort (heavy inputs to process, a long synthesis, a large or risky change).

If either is low, stay silent and plan/do normally. When borderline, stay silent. Assess this from request shape and input metadata only — do not read the inputs yet (recon happens after the offer is accepted). When the offer does fire, it is a single dismissible line naming the specific signal (e.g., "Three heavy sources are about to get synthesized and you might want them weighted differently -- want my approach first, or should I just go?") — never a blocking question, never a ceremony. Because the explicit path above is always available, a missed offer is cheap; the failure mode to avoid is the new-hammer nag — opening turns with "want me to plan the approach first?" when the method is obvious.

Stay disjoint from the other approach surfaces (R16). An investigative or analytical request with no approach-language and not-both-signals-high is NOT an approach-altitude request — it must pass through this gate untouched to Phase 0.1b, where answer-seeking's plan-of-attack handles it; the gate's earlier position must not intercept it. "Deepen the plan" and resume are already short-circuited by Phase 0.1. The Phase 0.7 / 5.1.5 scoping synthesis and the Phase 5.3 deepening pass operate on a deliverable already committed to; approach altitude operates before that commitment. Full distinctions: references/approach-altitude.md.

On entry (explicit, or an accepted offer), read references/approach-altitude.md and follow it. Otherwise continue to Phase 0.1b unchanged.

0.1b Classify Task Domain

If the task asks to build, modify, refactor, deploy, or architect software (code, schemas, infrastructure), continue to Phase 0.2.

Classify by task-type, not topic. A request that merely references code, a repo, an API, or a database is not automatically software work: building or modifying code is software; investigating or analyzing it is an answer-seeking question. "How often does X star repos — is it a big deal?" or "how does our approach compare to Y?" route to references/universal-planning.md (answer-seeking), not the implementation-plan path.

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 or *-requirements.html (ce-brainstorm emits whichever extension matches its resolved output format; both are valid upstream requirements docs and either may be carried as the plan's origin:).

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 Scoping Synthesis

Surface call-outs to the user — the specific forks in scope or approach where user input materially changes the plan — 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.

Read references/synthesis-summary.md before composing the scoping synthesis. It carries the affirmability test, keep-test criteria, detail test, summary shape budgets, granularity rules, anti-patterns, revision-vs-confirmation discipline, doc-shape routing, soft-cut behavior, self-redirect support, the worked PII compression example, and full headless-mode routing — all required for a well-shaped synthesis.

Required gate output — do not skip; silent proceeding is not allowed. Compose an internal three-bucket scope draft (Stated / Inferred / Out of scope — internal thinking that feeds plan-body routing at Phase 5.2, not the chat output below). Derive call-outs (specific forks where user input materially changes the plan), then emit one of the two literal templates below in chat before continuing to Phase 1.

Synthesis is pre-plan-write. The agent does NOT yet know how plan-write will sequence the work. Do not claim PR count ("one PR"), commit/branch shape, effort or time estimates, Implementation Unit boundaries, or exact file paths in the synthesis. The synthesis surfaces decisions knowable at THIS point — for the solo variant, that's the user's request plus the Phase 0.4 bootstrap dialogue plus the agent's own internal three-bucket draft. Phase 1 research has not happened yet and there is no upstream brainstorm; do not claim grounding from either. Plan-write produces the rest. This rule holds even when the agent has formed plan-write opinions earlier in the session — those stay internal until plan-write.

Summary shape: the summary is a scope claim — what the plan will target, what it will not — at affirm-or-redirect level. NOT an enumeration of Implementation Units. Form is prose, bullets, or mix; tier budgets are ceilings, not targets (Lightweight 1-3 lines; Standard up to 3-5 lines or 2-4 bullets; Deep up to 4-6 lines or 3-6 bullets). 1-2 lines per bullet, conversational not documentary. Less is correct when there isn't more to say. See reference for keep test, detail test, and source-vocabulary discipline.

Do NOT enumerate the touch surface. Sentences like "The touch surface is...", "This plan touches...", "The implementation reaches into..." are plan-pitch leaks. File paths, module names, directory introductions, and per-file change descriptions belong in the plan body (Implementation Units at Phase 5.2), not the synthesis. The synthesis names what the plan targets, not where the code lives.

Pre-emit scans. Before emitting the synthesis, scan the output:

• Bare ID references (AE\d+, R\d+, F\d+, A\d+, U\d+) → replace with plain names.
• File paths (path/like.md, path/like.py, etc.) → cut unless the path IS the topic of an explicit fork in the call-outs.

Tier guard on auto-proceed: the auto-proceed path (announce without waiting for confirmation) fires only when plan depth is Lightweight AND zero call-outs survive. Standard and Deep plans always fire the confirmation gate, even with zero call-outs — substance earns the checkpoint, not interaction history.

Confirmation template (Standard/Deep regardless of call-out count, or any tier with one or more call-outs surviving):

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

[scope claim — what the plan will target, what it will not; affirm-or-redirect level; NOT an enumeration of Implementation Units]

**Call outs:** (omit this header when zero forks survived the keep test)
- [decision-level fork in 1-2 lines: name the choice and optional one-clause trade-off in parens. NO multi-sentence rationale, NO "my default is X" pitch]

Confirm and I'll proceed to research, drawing on this scope. (You can also redirect to /ce-brainstorm if this is bigger than you initially thought — I'll stop here and load it for you.)

Wait for user confirmation before continuing to Phase 1.

Auto-proceed template (Lightweight with zero call-outs only):

Planning: [1-3 line scope claim]

No open decisions to weigh in on — proceeding to research. Interrupt if I have the scope wrong.

Then continue to Phase 1 without a blocking question.

Headless mode: internal draft is composed but stage 2 (chat-time call-outs) is skipped — no synchronous user to confirm to. Continue to Phase 1 research as normal. At plan-write time (Phase 5.2), Inferred bets from the internal draft 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
• If CONCEPTS.md exists at repo root, read it — its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.

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 and, if so, what kind. Resolve this in three stages: explicit-request priority, intent classification, then the implicit signals below.

Stage 1 — An explicit request takes precedence. If the user prompt or the origin requirements document explicitly asks for external input — a signal that the answer lives outside the repo, such as competitor/prior-art comparison, "what should we borrow", "from the web", "best practices", "official docs", "alternatives to", a market scan, or naming a specific external technology to consult — external research is required, regardless of how strong local patterns look. The list is illustrative; key on the signal, not the exact phrase — any wording that clearly points outside the repo qualifies. The skip conditions below do not apply to an explicit request. The only thing that overrides it is an explicit opt-out ("no web research", "skip external research"): honor that, skip, and note it. Improvement or quality verbs ("improve", "make better") carry no external signal on their own and never trigger research by themselves.

Stage 2 — Classify the research intent (whenever external research will run, from Stage 1 or the implicit signals below) so Phase 1.3 routes correctly. Use this mechanical test, not a fixed phrase list:

• Implementation-guidance — the approach or technology is already settled; the question is how to build it well (best practices, version-specific docs, API constraints, known pitfalls, deprecations).
• Landscape / option-discovery — the question is what options or prior art exist (competitor scans, build-vs-buy, library/provider selection, prior art, market signals, cross-domain analogies).
• Mixed — both: discover an unsettled external option set first, then research the shortlisted choice for implementation guidance.

Stage 3 — Implicit signals decide the call when no explicit request fired.

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
• The plan's recommendations depend on a genuinely external, unsettled option set — which library, provider, or approach to adopt, or what competitors and prior art do — even when local implementation patterns are strong (intent: landscape). Bound this implicit landscape trigger by three gates: (a) the option set genuinely lives outside the repo, (b) the decision materially shapes the plan (a KTD, dependency, or architecture choice — not an incidental detail), and (c) no settled local or team choice already exists. Improvement verbs alone never satisfy this.

Skip external research when (only when Stage 1 found no explicit request — an explicit request is never skipped):

• 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

When an explicit request did fire but a settled local or team choice already exists, narrow the research rather than skipping it — research the current pitfalls, docs, and practices for the chosen library/pattern instead of re-surveying the whole option set.

Announce the decision and the intent 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 (implementation-guidance)."
• "You asked what to borrow from competitors, so I'll run a landscape scan first (landscape/option-discovery)."

1.3 External Research (Conditional)

If Step 1.2 indicates external research is useful, dispatch by the intent classified in Stage 2, using the platform's subagent primitive (Agent/Task in Claude Code, spawn_agent in Codex, subagent in Pi). For ce-web-researcher, pass a focus hint plus the planning context summary and do not pass codebase content — it operates externally.

• Implementation-guidance — run in parallel:
  • Task ce-best-practices-researcher(planning context summary)
  • Task ce-framework-docs-researcher(planning context summary, with exact frameworks/versions from Phase 1.1 where available)
• Landscape / option-discovery — Task ce-web-researcher(focus hint, planning context summary). When the request targets projects on a code host (e.g., "competitors on GitHub"), name the discovery dimensions in the focus hint: project names and URLs, release recency and activity, CLI/UX shape, install path, docs and examples, plugin/extension surfaces, recurring issue themes, and license — treating star counts as a weak signal only.
• Mixed — sequential, not parallel: run ce-web-researcher first to map the landscape and produce a shortlist; then run ce-framework-docs-researcher and/or ce-best-practices-researcher against the shortlisted technologies only when their details materially shape the plan.

Tool-unavailable handling. ce-web-researcher self-checks for web tools and stops if they are missing. Never block on this: if it reports research unavailable, or any researcher fails, warn and proceed, and carry the gap into Phase 1.4 so the plan records it honestly — especially when the user explicitly requested external research, where a silent skip would leave the plan looking evidence-based when it is not.

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, prior art, competitor/landscape findings, and best practices, if gathered
• Related issues, PRs, or prior art
• Any constraints that should materially shape the plan

**Land external findings in decisions,

…(truncated)