メニュー
Create structured plans for multi-step work, including software and non-software tasks. Use when asked to plan, break down implementation, plan from requirements, or deepen an existing plan; prefer ce-brainstorm for exploratory framing.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | ce-plan |
| description | Create structured plans for multi-step work, including software and non-software tasks. Use when asked to plan, break down implementation, plan from requirements, or deepen an existing plan; prefer ce-brainstorm for exploratory framing. |
| argument-hint | [optional: feature description, requirements doc path, plan path to deepen, or any task to plan] [output:html] |
Note: The current year is 2026. Use this when dating plans and searching for recent documentation.
ce-brainstorm defines WHAT to build by creating a requirements-only unified plan. ce-plan enriches that same artifact with HOW to build it. ce-work executes implementation-ready plans. A prior brainstorm is useful context but never required — ce-plan works from any input: a requirements-only unified plan, a legacy 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.
Every normal interactive ce-plan branch that produces a plan artifact or checkpoint is incomplete until its owning handoff question is presented. For software implementation-plan runs that continue past Phase 0.1b, that boundary is Phase 5.4's post-generation handoff menu. Non-software plan-seeking and approach-altitude branches use the terminal handoff in the reference workflow they route to; do not force those branches through Phase 5.4 after they have been told to skip subsequent phases. Answer-seeking is the exception: it may end after delivering the answer unless the universal-planning reference says to offer save/share.
For software implementation-plan runs, writing the plan file, running the confidence check, and running or skipping ce-doc-review are intermediate milestones, not completion. This remains true when the user's prompt says only "create a plan", "write the doc", "run ce-doc-review", or similar. The only exception is pipeline mode (LFG or any disable-model-invocation context), where the caller owns the next step after the plan file, confidence check, and headless document review are complete.
Before any response that could end a software implementation-plan run, verify that the plan path is known, the headless review state or documented skip state is summarized, and the user has been asked: "Plan ready at <absolute path to plan>. What would you like to do next?" If the menu fits the platform's blocking-question tool, ask it there; otherwise render the numbered handoff options in chat and wait. If the user selects an action, execute the Phase 5.4 routing for that selection before treating the skill as complete.
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_question in Antigravity CLI (agy), 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.
The feature description is the input this skill was invoked with — what to plan, present in the current prompt or conversation, whether the user provided it directly or a calling skill passed it (e.g. lfg in mode:pipeline).
If no feature description was provided, 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, JJ workspaces, and teammates.
ce-brainstorm produced a requirements-only unified plan, planning should enrich it in place rather than re-inventing behavior or creating a second artifact.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.Every plan should contain:
A plan is ready when an implementer can start confidently without needing the plan to write the code for them.
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: in-prompt request > user-stated preference > config > default (md), with a hard pipeline-mode override.
Read config. Resolve <workspace-root> at runtime by running jj workspace root with the shell tool. If that fails because this is not a JJ workspace, use the current working directory as <workspace-root> only for repo-local .tmp storage and skip workspace config. Then read <workspace-root>/.rocketclaw/config.local.yaml with the native file-read tool when the JJ root resolved. If the file does not exist, fall through to the defaults below.
Resolution steps:
output: shorthand or in plain language ("make the plan a webpage", "I want this in HTML"). On an explicit format, match it case-insensitively to md/html, and ignore the output: shorthand token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "add an HTML export feature" or "plan the CSV importer" is the work, not a doc-format request — do not switch on it.
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 the remaining precedence steps. Do not hardcode md in the note — that misleads users when config has set HTML.md/html case-insensitively). A remembered preference is more current than the rarely-edited config, so it overrides the config in step 3. Do not open or search instruction files to find it — act only on a preference already present in your context; if none is, fall through to the config.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.OUTPUT_FORMAT=md.disable-model-invocation context, force OUTPUT_FORMAT=md regardless of steps 1-4. 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:, the exact confirm:auto/confirm:ask forms, delegate: where applicable) are consumed and stripped. Other <word>:<word> tokens — including project-defined description prefixes and any unrecognized confirm:<value> (e.g., a confirm: delete-account modal 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.
OUTPUT_FORMAT=md, read references/markdown-rendering.md for format principles.OUTPUT_FORMAT=html, read references/html-rendering.md for format principles.Resolve the scoping-confirmation setting. Also before any gate fires, determine SKIP_SCOPING_CONFIRM (boolean, default false) — whether the pre-plan scoping-synthesis confirmation gates (Phase 0.7 solo, Phase 5.1.5 brainstorm-sourced) proceed without waiting for the user. This skips only that scoping confirmation; it never suppresses genuine blocking questions (Phase 0.4 routing, Phase 0.5 product blockers, Phase 2 architecture questions, source-doc disambiguation) or the Phase 5.4 post-generation menu. Precedence mirrors output mode:
confirm:auto skips the gate for this run; confirm:ask forces it on for this run. Honor an equivalent plain-language instruction the same way ("just write it, don't ask me to confirm" → skip; "ask me before writing the plan" → ask). Consume and strip the token only for the two recognized values confirm:auto and confirm:ask. A bare confirm: or any other value (e.g., confirm:delete-account) is not a flag — leave it verbatim in the feature description and fall through (this is narrower than output:, which strips unknown values: confirm has only two valid values, and a description can legitimately begin with a word like "confirm:").plan_skip_scoping_confirm: key matching true/false. Commented (#-prefixed) or invalid values fall through silently.ask — the gate fires per the existing tier rules.Pipeline / disable-model-invocation runs already skip the chat confirmation (headless mode), so this setting is moot there.
If the user references an existing plan file or there is an obvious recent matching plan in docs/plans/:
ce-work, so there is no progress to preserve across editsA requirements-only unified plan is not a resume target. A docs/plans/ file with artifact_readiness: requirements-only is an enrichment input, not an existing plan to resume — do not fire the update-or-create confirm for it. Fall through to Phase 0.2, which enriches it in place to implementation-ready. This matters most for the hands-off ce-brainstorm -> lfg flow: lfg hands ce-plan the requirements-only path in disable-model-invocation pipeline mode, where no user is present to answer a resume prompt. More generally, in pipeline mode the resume choice is made automatically (default to in-place update of the referenced plan) and never prompted.
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):
.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.
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:
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.
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.
Before asking planning questions, resolve the upstream product source in this order:
artifact_contract: unified-plan/v1 and artifact_readiness: requirements-only, this run enriches that same file in place. If it is already artifact_readiness: implementation-ready, treat it as a resume/deepening target. If it is a legacy docs/brainstorms/*-requirements.{md,html} file, use it as a legacy origin and write a new unified plan in docs/plans/.docs/plans/*.{md,html} for visible/frontmatter metadata containing artifact_contract: unified-plan/v1, artifact_readiness: requirements-only, and product_contract_source: ce-brainstorm. Skip a superseded sibling: if a requirements-only candidate has a same-basename file in the other format (<basename>.md / <basename>.html) that is already implementation-ready, a format conversion superseded it — the implementation-ready sibling is canonical; do not re-enrich the stale requirements-only copy.docs/brainstorms/ for files matching *-requirements.md or *-requirements.html. These remain readable historical inputs; do not migrate or rewrite them.Relevance criteria: A Product Contract source is relevant if:
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.
If a relevant requirements-only unified plan exists:
ce-plan will enrich that same file to artifact_readiness: implementation-ready.ce-doc-review, PR review) when there is no separate brainstorm file to diff against. For a substantive product-scope change (not a clarification), pause and confirm with the user before writing implementation units.output: conversion or pipeline override requires a new canonical path; when conversion happens, report old path and new canonical path.If a relevant legacy requirements document exists:
(see origin: <source-path>)If no relevant Product Contract source exists, planning may proceed from the user's request directly and will create a complete unified plan with product_contract_source: ce-plan-bootstrap.
If no relevant requirements document exists, or the input needs more structure:
ce-brainstorm as a suggestion — but always offer to continue planning here as wellce-brainstorm — its blindspot pass maps the territory's decision surface before requirements are extracted — but honor their choice to continue here; Phase 2's unfamiliar-territory scaffolding then appliesThe planning bootstrap should establish:
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:
ce-brainstorm againIf 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):
docs/plans/, not cwd's).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.
If the origin document contains Resolve Before Planning or similar blocking questions:
If true product blockers remain:
ce-brainstorm to resolve themClassify the work into one of these plan depths:
If depth is unclear, ask one targeted question and then continue.
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 Product Contract source (no requirements-only unified plan and no legacy *-requirements doc; product_contract_source: ce-plan-bootstrap) 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 — upstream-sourced invocations (unified-plan enrichment or legacy brainstorm) 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, the literal confirmation and auto-proceed templates, 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). Derive call-outs (specific forks where user input materially changes the plan), run the pre-emit scans, then emit the solo-variant synthesis and wait for user confirmation before continuing to Phase 1. The summary is a scope claim — what the plan will target, what it will not, at affirm-or-redirect level — never an enumeration of Implementation Units, file paths, or PR/sequencing shape (plan-write owns those, and they are not knowable yet). Emit the confirmation or auto-proceed template as specified in references/synthesis-summary.md (loaded above) rather than reconstructing it here.
Blocking decision: auto-proceed — announce without waiting — only when plan depth is Lightweight AND zero call-outs survive. Standard and Deep always fire the confirmation gate, even with zero call-outs.
Headless / opt-in skip: in headless mode, or when SKIP_SCOPING_CONFIRM resolved to skip in Phase 0.0, do not block — compose the internal draft, skip the chat-time confirmation, and route Inferred bets to a ## Assumptions section at plan-write (Phase 5.2). The skip covers only this scoping confirmation; Phase 0.4 routing, Phase 0.5 blockers, Phase 2 questions, source-doc disambiguation, and the Phase 5.4 menu still fire. Announcement wording and full routing: references/synthesis-summary.md ("Headless mode", "When to skip the blocking confirmation").
All specialist research and deepening prompts used in this phase are skill-local prompt assets under references/agents/. When dispatching one, read the matching file and seed a generic subagent with that prompt content plus the task-specific context below. Do not dispatch standalone agents by type/name.
Model tiering lives in this caller, not in prompt assets. Local prompt files have no frontmatter. Use the platform's mid-tier model for external/organizational research prompts such as slack-researcher and web-researcher when the current harness exposes a known override; otherwise omit the override and inherit. Use inherited model for high-judgment architecture, migration, and planning-deepening prompts unless the harness has an established cheaper capable tier.
Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents:
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 strategyCONCEPTS.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.Resolve the project profile from the shared cache first. The agnostic profile (stack, deps, conventions, structure) is identical at this JJ revision, so reuse it instead of having repo-research-analyst re-derive technology/architecture/conventions every run. Set SKILL_DIR to this skill's directory and run the helper (protocol in references/repo-profile-cache.md):
SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
python3 "$SKILL_DIR/scripts/repo-profile-cache.py" get
On HIT, load the profile JSON as your agnostic grounding. On MISS, dispatch a generic subagent with references/agents/repo-profiler.md to derive it, write its JSON to a file, then python3 "$SKILL_DIR/scripts/repo-profile-cache.py" put <file> (re-set SKILL_DIR in that call — shell vars don't persist between Bash invocations). On NO-CACHE — or if the call errors or returns nothing — derive it inline and skip the put; never block on the cache. Pass the resulting profile to repo-research-analyst below so it skips the agnostic scopes. The cached profile covers only root conventions — if the work targets a subdirectory with its own scoped instruction file (a nested AGENTS.md/CLAUDE.md), read that fresh; subdirectory-scoped instructions are deliberately excluded from the cache.
Run these agents in parallel:
references/agents/repo-research-analyst.md — scope: patterns (the question-specific slice; the agnostic technology/architecture/conventions grounding comes from the cached profile passed in its context — the profile's stack/topology/conventions keys cover those analyst scopes). Pass the planning context summary and the cached profile.references/agents/learnings-researcher.md — pass the planning context summary.Agent-native planning triage (conditional) — consider broadly, dispatch selectively. Dispatch a generic subagent with references/agents/agent-native-planning-strategist.md in parallel with the local research agents when the request, origin document, or repo research indicates any of:
Do not dispatch for cosmetic, layout-only, animation-only, brand, low-value preference, or narrow work in a product with no agent surface. If the signal is borderline, do not dispatch; carry only a short future parity consideration when it affects a high-value domain action. Include any resulting findings in consolidation as planning inputs, not as a standalone advice appendix.
Collect:
docs/solutions/STRATEGY.md is present — flag any plan decisions that pull away from the active tracks or the stated approachSlack context (opt-in) — never auto-dispatch. Route by condition:
references/agents/slack-researcher.md and 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.Decide whether the plan should carry a lightweight execution direction signal.
Look for signals such as:
When the signal is clear, carry it forward silently in the relevant implementation units.
Ask the user only if the direction would materially change sequencing or risk and cannot be responsibly inferred.
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:
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:
Leverage the repo research prompt's technology context:
The cached project profile's stack/versions (or, when uncached, the repo-research-analyst Technology & Infrastructure summary) gives you the technology context. Use it to make sharper external research decisions:
framework-docs-researcher local prompt so it fetches version-specific documentationAlways lean toward external research when:
Skip external research when (only when Stage 1 found no explicit request — an explicit request is never skipped):
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:
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) where available; otherwise run the work inline or serially. Read the selected prompt asset from references/agents/ and seed a generic subagent with it. For web-researcher.md, pass a focus hint plus the planning context summary and do not pass codebase content — it operates externally.
references/agents/best-practices-researcher.md with the planning context summary.references/agents/framework-docs-researcher.md with the planning context summary and exact frameworks/versions from Phase 1.1 where available.references/agents/web-researcher.md with the focus hint and 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.web-researcher local prompt first to map the landscape and produce a shortlist; then run the framework-docs-researcher and/or best-practices-researcher local prompts against the shortlisted technologies only when their details materially shape the plan.Tool-unavailable handling. 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.
Summarize:
Land external findings in decisions, not an appendix. Any external research that ran must surface where it changes a choice — Key Technical Decisions rationale, Alternatives, Risks, or Sources & Research — not as a detached list with no bearing on the plan. If a finding shaped nothing, it was not load-bearing; do not pad the plan with it.
Mark whether external research was load-bearing. Record a single internal flag: did external findings materially shape a KTD, Alternative, Scope boundary, or Risk? This flag answers only that question — it does not gate whether research runs (Phase 1.2 owns that decision). Phase 5.3.2 reads it to decide whether to enter a confidence-scoring pass.
Record requested-but-unavailable. If the user explicitly requested external research but it could not run (web tools unavailable, researcher failed), state that in the plan as an assumption or open question rather than presenting the plan as externally grounded.
If the current classification is Lightweight and Phase 1 research found that the work touches any of these external contract surfaces, reclassify to Standard:
.github/workflows/, Dockerfile, deployment scripts)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."
For Standard or Deep plans, or when user flow completeness is still unclear, run:
references/agents/spec-flow-analyzer.md with the planning context summary and research findings.Use the output to:
Build a planning question list from:
For each question, decide whether it should be:
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).
Scaffold questions on unfamiliar territory. When the user has signaled they lack working knowledge of the area a question lives in — an explicit "I don't know X", or earlier answers showing they cannot evaluate options rather than merely haven't decided — do not ask the question naked. Present it as a taught decision: the realistic options, one clause each on the trade-off that matters for this plan, and a recommended default. If the user still cannot evaluate, record the default as an explicit assumption in the plan instead of extracting a guess. In pipeline mode (LFG, any disable-model-invocation context) this scaffolding never presents anything — resolve to the recommended default and record it as an explicit assumption in the plan.
Do not run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution.
<type> from the repository's present artifact-classification vocabularydocs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
docs/plans/ if it does not existYYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.mdFor 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.
Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic JJ revision.
Good units are:
Avoid:
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.
When the plan's technical approach has shape that prose alone doesn't carry well — architecture across components, sequencing across processes, state machines, branching gates, lifecycles, quantitative comparisons — include a High-Level Technical Design section that conveys the shape. The exact form (component diagram, sequence, swim lane, flowchart, state machine, decision matrix, pseudo-code grammar, bar chart for sizing concerns) is the agent's call per artifact — pick what makes the content land fastest for the reader.
See references/plan-sections.md for the section catalog including HTD's "include when material" criterion. See the format-rendering reference loaded at Phase 0.0 for how visualizations render in the target format (mermaid in markdown, inline SVG in HTML — with the layout-legibility principles around halo, contrast, and label placement when in HTML).
When the plan's approach is a one-paragraph pattern application that prose conveys directly, skip the section. The presence of HTD should earn its keep with content that genuinely benefits from visualization.
Plan diagrams render authoritative content alongside the prose — they are not "directional sketches." Do not add hedging captions like "directional guidance for review, not implementation specification" to plan diagrams; the prose-is-authoritative rule already governs disagreement, and the hedging weakens the diagram unnecessarily.
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:
When to skip it:
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.
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 JJ history 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:
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.
Every feature-bearing unit should include the test file path in **Files:**.
Use Execution note sparingly. Good uses include:
Execution note: Start with a failing integration test for the request/response contract.Execution note: Add characterization coverage before modifying this legacy parser.Execution note: Implement new domain behavior test-first.Execution note: This is mostly packaging/config; prefer install/runtime smoke verification over unit coverage.Do not expand units into literal RED/GREEN/REFACTOR substeps.
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:
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.
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.
Lightweight
Standard
Deep
For sufficiently large, risky, or cross-cutting work, add the sections that genuinely help:
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.
Compose the plan using two paired references:
references/plan-sections.md — the section contract. Describes what the plan contains: the outcome the plan must enable for downstream consumers, the hard floor (Summary, Problem Frame, Requirements, KTDs, Implementation Units), the include-when-material catalog (HTD, Scope Boundaries, Open Questions, System-Wide Impact, Risks & Dependencies, Acceptance Examples, Documentation/Operational Notes, Sources & Research), the agency-driven escape hatch (introduce new sections when content warrants), and the ID/content rules.markdown-rendering.md OR html-rendering.md) — how to present the sections in the resolved output format.The section catalog is the same regardless of format. Format-specific principles (table-vs-prose by content shape, ID prefix format, diagram rendering, etc.) live in the rendering reference.
Omit "include when material" sections that don't carry information for this specific plan. Filling a section with placeholder prose is worse than omitting it.
---) 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./Users/name/Code/project/src/file.ts. Use src/file.ts instead. Absolute paths make plans non-portable across machines, JJ workspaces, 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 throughoutRED/GREEN/REFACTOR instructionsBefore finalizing, check:
ce-brainstormExecution noteTest expectation: none -- [reason] annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)### Deferred to Follow-Up Work rather than mixed with true non-goals?If the plan originated from a requirements document, re-read that document and verify:
ce-brainstormOutside 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 sequencingSurface plan-time call-outs 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 on the forks that matter.
Fires whenever Phase 0.2 resolved an upstream Product Contract source — a requirements-only unified plan (an explicit path, or a discovered product_contract_source: ce-brainstorm plan in docs/plans/) or a legacy *-requirements.{md,html} brainstorm doc — AND not on Phase 0.1 fast paths (resume normal, deepen-intent). The new ce-brainstorm -> ce-plan <unified-plan> enrichment flow is brainstorm-sourced and MUST fire this gate, just like legacy flows. Skip Phase 5.1.5 only in solo invocation (no upstream source found; product_contract_source: ce-plan-bootstrap) — solo plans handled their synthesis in Phase 0.7.
Read references/synthesis-summary.md before composing the scoping synthesis. It carries the affirmability test, keep-test criteria, detail test, summary shape budgets, the literal confirmation and auto-proceed templates, granularity rules, anti-patterns, revision-vs-confirmation discipline, doc-body reading rules, 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). Derive call-outs (specific forks where user input materially changes the plan), run the pre-emit scans, then emit the brainstorm-sourced synthesis and wait for user confirmation before continuing to Phase 5.2. Its summary is two parts — a 1-2 sentence restatement of the brainstorm's scope in the brainstorm's own vocabulary, then the plan-specific scoping decisions the brainstorm did not make (full-brainstorm coverage vs. narrowed subset; adjacent refactors in or out; test scope at scenario level) — each affirmable without reading code, and never an enumeration of Implementation Units, file paths, or PR/sequencing shape. Emit the confirmation or auto-proceed template as specified in references/synthesis-summary.md (loaded above) rather than reconstructing it here.
Blocking decision: auto-proceed — announce without waiting — only when plan depth is Lightweight AND zero call-outs survive. Standard and Deep always fire the confirmation gate, even with zero call-outs.
Headless / opt-in skip: in headless mode, or when SKIP_SCOPING_CONFIRM resolved to skip in Phase 0.0, do not block — compose the internal draft, skip the chat-time confirmation, and route Inferred bets to a ## Assumptions section at plan-write (Phase 5.2). The skip covers only this scoping confirmation; Phase 0.4 routing, Phase 0.5 blockers, Phase 2 questions, source-doc disambiguation, and the Phase 5.4 menu still fire. Announcement wording and full routing: references/synthesis-summary.md ("Headless mode", "When to skip the blocking confirmation").
Reasoning elevation (Claude Code only). Before authoring the plan, if positively Claude Code (CLAUDECODE=1, not Cursor/Codex), load references/reasoning-elevation.md and follow it — it may dispatch the interpret-findings-then-author step to a higher-reasoning model when the user has opted in, and it owns the completion-time discoverability tip. On any non-Claude host, skip it entirely — proceed on the session model with no mention. If a prompt names a model this skill does not recognize on this harness, proceed on the session model without comment.
REQUIRED: Write the plan file to disk before presenting any options.
HTML note: ce-doc-review is markdown-only today. HTML plans still render the
unified artifact, but the Phase 5.3.8 document-review autofix pass is skipped
for HTML by the format gate in references/plan-handoff.md.
Use the Write tool to save the complete plan to the resolved format's extension:
docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.<md|html>
Extension follows OUTPUT_FORMAT from Phase 0.0 — .md when markdown, .html when HTML. Sequence number NNN is derived from existing plan files in docs/plans/ regardless of extension (count both .md and .html) to ensure unique daily ordering.
Compose the plan using the content from references/plan-sections.md and the format-specific principles from the rendering reference loaded at Phase 0.0 (markdown-rendering.md OR html-rendering.md).
Write tight. A section being material is not license to pad it. Hold every kept section to the prose-economy discipline in references/plan-sections.md: lead with the decision or outcome, one idea per sentence, a requirement or unit is intent plus at most one qualifier, defer forks to Open Questions rather than specifying both arms, resolve superseded text in place rather than stacking strata. Before declaring the plan written, run the named test there — could the implementer find a contradiction in each section in one pass?
Write the unified plan artifact according to references/plan-sections.md.
Babysits or watches an open GitHub PR until merge-ready, continuously reacting to new review comments and CI failures throughout the PR's life. Use when asked to 'babysit the PR', 'watch the PR', monitor, or keep an eye on a PR over time — not a one-shot request to resolve review comments or debug one CI failure (those are separate skills). GitHub only, including GitHub Enterprise.
Explore vague or ambitious ideas into a right-sized requirements-only unified plan. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning. Also use when the user must scope work in territory they say they do not know ("I know nothing about X but need to...") or asks for a blindspot pass — mapping the decision surface before questions begin. Not for executing already-specified work — direct implementation, debugging, or code review where no product scope is left to decide. Not for a decisive verdict on whether to adopt or switch to a specific external technology, library, or platform — brainstorming scopes what to build, not whether to commit to an outside option.
Structured code review for bugs, regressions, tests, and standards. Use before PRs or when asked for review; interactive mode can fix locally, while mode:agent reports only for pipeline callers.
Commit with JJ, push through `jj git` interoperability, and open or update a GitHub PR. Use when asked to ship/open a PR or only write, rewrite, or apply a PR description.
Create a JJ commit with a clear, repository-appropriate message. Use when the user asks to commit or save current working-copy changes.
Diagnosis loop for bugs and failing behavior. Use for errors, stack traces, regressions, failed tests, issue-tracker bugs, stuck investigations after failed fixes, or asks to debug/fix a bug.