@fro.bot/systematic 2.0.2 → 2.1.0

package/skills/ce-plan/SKILL.md

@@ -1,596 +1,613 @@
 ---
 name: ce:plan
-description: Transform feature descriptions into well-structured project plans following conventions
-argument-hint: '[feature description, bug report, or improvement idea]'
+description: Transform feature descriptions or requirements into structured implementation plans grounded in repo patterns and research. Use when the user says 'plan this', 'create a plan', 'write a tech plan', 'plan the implementation', 'how should we build', 'what's the approach for', 'break this down', or when a brainstorm/requirements document is ready for technical planning. Best when requirements are at least roughly defined; for exploratory or ambiguous requests, prefer ce:brainstorm first.
+argument-hint: '[feature description, requirements doc path, or improvement idea]'
 ---
 
-# Create a plan for a new feature or bug fix
-
-## Introduction
+# Create Technical Plan
 
 **Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.
 
-Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
+`ce:brainstorm` defines **WHAT** to build. `ce:plan` defines **HOW** to build it. `ce:work` executes the plan.
 
-## Feature Description
+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.
 
-<feature_description> #$ARGUMENTS </feature_description>
-
-**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."
+## Interaction Method
 
-Do not proceed until you have a clear feature description from the user.
+Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
 
-### 0. Idea Refinement
+Ask one question at a time. Prefer a concise single-select choice when natural options exist.
 
-**Check for requirements document first:**
+## Feature Description
 
-Before asking questions, look for recent requirements documents in `docs/brainstorms/` that match this feature:
+<feature_description> #$ARGUMENTS </feature_description>
 
-```bash
-ls -la docs/brainstorms/*-requirements.md 2>/dev/null | head -10
-```
+**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."
 
-**Relevance criteria:** A requirements document is relevant if:
-- The topic (from filename or YAML frontmatter) semantically matches the feature description
-- Created within the last 14 days
-- If multiple candidates match, use the most recent one
+Do not proceed until you have a clear planning input.
 
-**If a relevant requirements document exists:**
-1. Read the source document **thoroughly** — every section matters
-2. Announce: "Found source document from [date]: [topic]. Using as foundation for planning."
-3. Extract and carry forward **ALL** of the following into the plan:
-   - Key decisions and their rationale
-   - Chosen approach and why alternatives were rejected
-   - Problem framing, constraints, and requirements captured during brainstorming
-   - Outstanding questions, preserving whether they block planning or are intentionally deferred
-   - Success criteria and scope boundaries
-   - Dependencies and assumptions, plus any high-level technical direction only when the origin document is inherently technical
-4. **Skip the idea refinement questions below** — the source document already answered WHAT to build
-5. Use source document content as the **primary input** to research and planning phases
-6. **Critical: The source document is the origin document.** Throughout the plan, reference specific decisions with `(see origin: <source-path>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
-7. **Do not omit source content** — if the source document discussed it, the plan must address it (even if briefly). Scan each section before finalizing the plan to verify nothing was dropped.
-8. **If `Resolve Before Planning` contains any items, stop.** Do not proceed with planning. Tell the user planning is blocked by unanswered brainstorm questions and direct them to resume `/ce:brainstorm` or answer those questions first.
+## Core Principles
 
-**If multiple source documents could match:**
-Use **question tool** to ask which source document to use, or whether to proceed without one.
+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.
 
-**If no requirements document is found (or not relevant), run idea refinement:**
+## Plan Quality Bar
 
-Refine the idea through collaborative dialogue using the **question tool**:
+Every plan should contain:
+- A clear problem frame and scope boundary
+- Concrete requirements traceability back to the request or origin document
+- Exact file paths for the work being proposed
+- Explicit test file paths for feature-bearing implementation units
+- Decisions with rationale, not just tasks
+- Existing patterns or code references to follow
+- Specific test scenarios and verification outcomes
+- Clear dependencies and sequencing
 
-- Ask questions one at a time to understand the idea fully
-- Prefer multiple choice questions when natural options exist
-- Focus on understanding: purpose, constraints and success criteria
-- Continue until the idea is clear OR user says "proceed"
+A plan is ready when an implementer can start confidently without needing the plan to write the code for them.
 
-**Gather signals for research decision.** During refinement, note:
+## Workflow
 
-- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
-- **User's intent**: Speed vs thoroughness? Exploration vs execution?
-- **Topic risk**: Security, payments, external APIs warrant more caution
-- **Uncertainty level**: Is the approach clear or open-ended?
+### Phase 0: Resume, Source, and Scope
 
-**Skip option:** If the feature description is already detailed, offer:
-"Your description is clear. Should I proceed with research, or would you like to refine it further?"
+#### 0.1 Resume Existing Plan Work When Appropriate
 
-## Main Tasks
+If the user references an existing plan file or there is an obvious recent matching plan in `docs/plans/`:
+- Read it
+- Confirm whether to update it in place or create a new plan
+- If updating, preserve completed checkboxes and revise only the still-relevant sections
 
-### 1. Local Research (Always Runs - Parallel)
+#### 0.2 Find Upstream Requirements Document
 
-<thinking>
-First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
-</thinking>
+Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`.
 
-Run these agents **in parallel** to gather local context:
+**Relevance criteria:** A requirements document is relevant if:
+- The topic semantically matches the feature description
+- It was created within the last 30 days (use judgment to override if the document is clearly still relevant or clearly stale)
+- It appears to cover the same user problem or scope
+
+If multiple source documents match, ask which one to use using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+#### 0.3 Use the Source Document as Primary Input
+
+If a relevant requirements document exists:
+1. Read it thoroughly
+2. Announce that it will serve as the origin document for planning
+3. Carry forward all of the following:
+   - Problem frame
+   - Requirements and success criteria
+   - Scope boundaries
+   - Key decisions and rationale
+   - Dependencies or assumptions
+   - Outstanding questions, preserving whether they are blocking or deferred
+4. Use the source document as the primary input to planning and research
+5. Reference important carried-forward decisions in the plan with `(see origin: <source-path>)`
+6. Do not silently omit source content — if the origin document discussed it, the plan must address it even if briefly. Before finalizing, scan each section of the origin document to verify nothing was dropped.
+
+If no relevant requirements document exists, planning may proceed from the user's request directly.
+
+#### 0.4 No-Requirements-Doc Fallback
+
+If no relevant requirements document exists:
+- Assess whether the request is already clear enough for direct technical planning
+- If the ambiguity is mainly product framing, user behavior, or scope definition, recommend `ce:brainstorm` first
+- If the user wants to continue here anyway, run a short planning bootstrap instead of refusing
+
+The planning bootstrap should establish:
+- Problem frame
+- Intended behavior
+- Scope boundaries and obvious non-goals
+- Success criteria
+- Blocking questions or assumptions
 
-- task systematic:research:repo-research-analyst(feature_description)
-- task systematic:research:learnings-researcher(feature_description)
+Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm.
 
-**What to look for:**
-- **Repo research:** existing patterns, AGENTS.md guidance, technology familiarity, pattern consistency
-- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
+If the bootstrap uncovers major unresolved product questions:
+- Recommend `ce:brainstorm` again
+- If the user still wants to continue, require explicit assumptions before proceeding
 
-These findings inform the next step.
+#### 0.5 Classify Outstanding Questions Before Planning
 
-### 1.5. Research Decision
+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
 
-Based on signals from Step 0 and findings from Step 1, decide on external research.
+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
 
-**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
+#### 0.6 Assess Plan Depth
 
-**Strong local context → skip external research.** Codebase has good patterns, AGENTS.md has guidance, user knows what they want. External research adds little value.
+Classify the work into one of these plan depths:
 
-**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
+- **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
 
-**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
+If depth is unclear, ask one targeted question and then continue.
 
-Examples:
-- "Your codebase has solid patterns for this. Proceeding without external research."
-- "This involves payment processing, so I'll research current best practices first."
+### Phase 1: Gather Context
 
-### 1.5b. External Research (Conditional)
+#### 1.1 Local Research (Always Runs)
 
-**Only run if Step 1.5 indicates external research is valuable.**
+Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents:
+- If an origin document exists, summarize the problem frame, requirements, and key decisions from that document
+- Otherwise use the feature description directly
 
 Run these agents in parallel:
 
-- task systematic:research:best-practices-researcher(feature_description)
-- task systematic:research:framework-docs-researcher(feature_description)
+- task systematic:research:repo-research-analyst(Scope: technology, architecture, patterns. {planning context summary})
+- task systematic:research:learnings-researcher(planning context summary)
 
-### 1.6. Consolidate Research
+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 AGENTS.md used only as compatibility fallback when present
+- Institutional learnings from `docs/solutions/`
 
-After all research steps complete, consolidate findings:
+#### 1.1b Detect Execution Posture Signals
 
-- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
-- **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
-- Note external documentation URLs and best practices (if external research was done)
-- List related issues or PRs discovered
-- Capture AGENTS.md conventions
+Decide whether the plan should carry a lightweight execution posture signal.
 
-**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
+Look for signals such as:
+- The user explicitly asks for TDD, test-first, or characterization-first work
+- The origin document calls for test-first implementation or exploratory hardening of legacy code
+- Local research shows the target area is legacy, weakly tested, or historically fragile, suggesting characterization coverage before changing behavior
+- The user asks for external delegation, says "use codex", "delegate mode", or mentions token conservation -- add `Execution target: external-delegate` to implementation units that are pure code writing
 
-### 2. Issue Planning & Structure
+When the signal is clear, carry it forward silently in the relevant implementation units.
 
-<thinking>
-Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
-</thinking>
+Ask the user only if the posture would materially change sequencing or risk and cannot be responsibly inferred.
 
-**Title & Categorization:**
+#### 1.2 Decide on External Research
 
-- [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
-- [ ] Determine issue type: enhancement, bug, refactor
-- [ ] Convert title to filename: add today's date prefix, determine daily sequence number, strip prefix colon, kebab-case, add `-plan` suffix
-  - Scan `docs/plans/` for files matching today's date pattern `YYYY-MM-DD-\d{3}-`
-  - Find the highest existing sequence number for today
-  - Increment by 1, zero-padded to 3 digits (001, 002, etc.)
-  - Example: `feat: Add User Authentication` → `2026-01-21-001-feat-add-user-authentication-plan.md`
-  - Keep it descriptive (3-5 words after prefix) so plans are findable by context
+Based on the origin document, user signals, and local findings, decide whether external research adds value.
 
-**Stakeholder Analysis:**
+**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?
 
-- [ ] Identify who will be affected by this issue (end users, developers, operations)
-- [ ] Consider implementation complexity and required expertise
+**Leverage repo-research-analyst's technology context:**
 
-**Content Planning:**
+The repo-research-analyst output includes a structured Technology & Infrastructure summary. Use it to make sharper external research decisions:
 
-- [ ] Choose appropriate detail level based on issue complexity and audience
-- [ ] List all necessary sections for the chosen template
-- [ ] Gather supporting materials (error logs, screenshots, design mockups)
-- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
+- If specific frameworks and versions were detected (e.g., Rails 7.2, Next.js 14, Go 1.22), pass those exact identifiers to framework-docs-researcher so it fetches version-specific documentation
+- If the feature touches a technology layer the scan found well-established in the repo (e.g., existing Sidekiq jobs when planning a new background job), lean toward skipping external research -- local patterns are likely sufficient
+- If the feature touches a technology layer the scan found absent or thin (e.g., no existing proto files when planning a new gRPC service), lean toward external research -- there are no local patterns to follow
+- If the scan detected deployment infrastructure (Docker, K8s, serverless), note it in the planning context passed to downstream agents so they can account for deployment constraints
+- If the scan detected a monorepo and scoped to a specific service, pass that service's tech context to downstream research agents -- not the aggregate of all services. If the scan surfaced the workspace map without scoping, use the feature description to identify the relevant service before proceeding with research
 
-### 3. SpecFlow Analysis
+**Always lean toward external research when:**
+- The topic is high-risk: security, payments, privacy, external APIs, migrations, compliance
+- The codebase lacks relevant local patterns
+- The user is exploring unfamiliar territory
+- The technology scan found the relevant layer absent or thin in the codebase
 
-After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
+**Skip external research when:**
+- The codebase already shows a strong local pattern
+- 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
 
-- task systematic:workflow:spec-flow-analyzer(feature_description, research_findings)
-
-**SpecFlow Analyzer Output:**
+Announce the decision briefly before continuing. Examples:
+- "Your codebase has solid patterns for this. Proceeding without external research."
+- "This involves payment processing, so I'll research current best practices first."
 
-- [ ] Review SpecFlow analysis results
-- [ ] Incorporate any identified gaps or edge cases into the issue
-- [ ] Update acceptance criteria based on SpecFlow findings
+#### 1.3 External Research (Conditional)
 
-### 4. Choose Implementation Detail Level
+If Step 1.2 indicates external research is useful, run these agents in parallel:
 
-Select how comprehensive you want the issue to be, simpler is mostly better.
+- task systematic:research:best-practices-researcher(planning context summary)
+- task systematic:research:framework-docs-researcher(planning context summary)
 
-#### 📄 MINIMAL (Quick Issue)
+#### 1.4 Consolidate Research
 
-**Best for:** Simple bugs, small improvements, clear features
+Summarize:
+- Relevant codebase patterns and file paths
+- Relevant institutional learnings
+- External references and best practices, if gathered
+- Related issues, PRs, or prior art
+- Any constraints that should materially shape the plan
 
-**Includes:**
+#### 1.5 Flow and Edge-Case Analysis (Conditional)
 
-- Problem statement or feature description
-- Basic acceptance criteria
-- Essential context only
+For **Standard** or **Deep** plans, or when user flow completeness is still unclear, run:
 
-**Structure:**
+- task systematic:workflow:spec-flow-analyzer(planning context summary, research findings)
 
-````markdown
----
-title: [Issue Title]
-type: [feat|fix|refactor]
-status: active
-date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
----
+Use the output to:
+- Identify missing edge cases, state transitions, or handoff gaps
+- Tighten requirements trace or verification strategy
+- Add only the flow details that materially improve the plan
 
-# [Issue Title]
+### Phase 2: Resolve Planning Questions
 
-[Brief problem/feature description]
+Build a planning question list from:
+- Deferred questions in the origin document
+- Gaps discovered in repo or external research
+- Technical decisions required to produce a useful plan
 
-## Acceptance Criteria
+For each question, decide whether it should be:
+- **Resolved during planning** - the answer is knowable from repo context, documentation, or user choice
+- **Deferred to implementation** - the answer depends on code changes, runtime behavior, or execution-time discovery
 
-- [ ] Core requirement 1
-- [ ] Core requirement 2
+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).
 
-## Context
+**Do not** run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution.
 
-[Any critical information]
+### Phase 3: Structure the Plan
 
-## MVP
+#### 3.1 Title and File Naming
 
-### test.rb
+- Draft a clear, searchable title using conventional format such as `feat: Add user authentication` or `fix: Prevent checkout double-submit`
+- Determine the plan type: `feat`, `fix`, or `refactor`
+- Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md`
+  - Create `docs/plans/` if it does not exist
+  - Check existing files for today's date to determine the next sequence number (zero-padded to 3 digits, starting at 001)
+  - Keep the descriptive name concise (3-5 words) and kebab-cased
+  - Examples: `2026-01-15-001-feat-user-authentication-flow-plan.md`, `2026-02-03-002-fix-checkout-race-condition-plan.md`
+  - Avoid: missing sequence numbers, vague names like "new-feature", invalid characters (colons, spaces)
 
-```ruby
-class Test
-  def initialize
-    @name = "test"
-  end
-end
-```
+#### 3.2 Stakeholder and Impact Awareness
 
-## Sources
+For **Standard** or **Deep** plans, briefly consider who is affected by this change — end users, developers, operations, other teams — and how that should shape the plan. For cross-cutting work, note affected parties in the System-Wide Impact section.
 
-- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc
-- Related issue: #[issue_number]
-- Documentation: [relevant_docs_url]
-````
+#### 3.3 Break Work into Implementation Units
 
-#### 📋 MORE (Standard Issue)
+Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic commit.
 
-**Best for:** Most features, complex bugs, team collaboration
+Good units are:
+- Focused on one component, behavior, or integration seam
+- Usually touching a small cluster of related files
+- Ordered by dependency
+- Concrete enough for execution without pre-writing code
+- Marked with checkbox syntax for progress tracking
 
-**Includes everything from MINIMAL plus:**
+Avoid:
+- 2-5 minute micro-steps
+- Units that span multiple unrelated concerns
+- Units that are so vague an implementer still has to invent the plan
 
-- Detailed background and motivation
-- Technical considerations
-- Success metrics
-- Dependencies and risks
-- Basic implementation suggestions
+#### 3.4 High-Level Technical Design (Optional)
 
-**Structure:**
+Before detailing implementation units, decide whether an overview would help a reviewer validate the intended approach. This section communicates the *shape* of the solution — how pieces fit together — without dictating implementation.
 
-```markdown
----
-title: [Issue Title]
-type: [feat|fix|refactor]
-status: active
-date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
----
+**When to include it:**
 
-# [Issue Title]
+| Work involves... | Best overview form |
+|---|---|
+| DSL or API surface design | Pseudo-code grammar or contract sketch |
+| Multi-component integration | Mermaid sequence or component diagram |
+| Data pipeline or transformation | Data flow sketch |
+| State-heavy lifecycle | State diagram |
+| Complex branching logic | Flowchart |
+| Single-component with non-obvious shape | Pseudo-code sketch |
 
-## Overview
+**When to skip it:**
+- Well-patterned work where prose and file paths tell the whole story
+- Straightforward CRUD or convention-following changes
+- Lightweight plans where the approach is obvious
 
-[Comprehensive description]
+Choose the medium that fits the work. Do not default to pseudo-code when a diagram communicates better, and vice versa.
 
-## Problem Statement / Motivation
+Frame every sketch with: *"This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce."*
 
-[Why this matters]
+Keep sketches concise — enough to validate direction, not enough to copy-paste into production.
 
-## Proposed Solution
+#### 3.5 Define Each Implementation Unit
 
-[High-level approach]
+For each unit, include:
+- **Goal** - what this unit accomplishes
+- **Requirements** - which requirements or success criteria it advances
+- **Dependencies** - what must exist first
+- **Files** - exact file paths to create, modify, or test
+- **Approach** - key decisions, data flow, component boundaries, or integration notes
+- **Execution note** - optional, only when the unit benefits from a non-default execution posture such as test-first, characterization-first, or external delegation
+- **Technical design** - optional pseudo-code or diagram when the unit's approach is non-obvious and prose alone would leave it ambiguous. Frame explicitly as directional guidance, not implementation specification
+- **Patterns to follow** - existing code or conventions to mirror
+- **Test scenarios** - specific behaviors, edge cases, and failure paths to cover
+- **Verification** - how an implementer should know the unit is complete, expressed as outcomes rather than shell command scripts
 
-## Technical Considerations
+Every feature-bearing unit should include the test file path in `**Files:**`.
 
-- Architecture impacts
-- Performance implications
-- Security considerations
+Use `Execution note` sparingly. Good uses include:
+- `Execution note: Start with a failing integration test for the request/response contract.`
+- `Execution note: Add characterization coverage before modifying this legacy parser.`
+- `Execution note: Implement new domain behavior test-first.`
+- `Execution note: Execution target: external-delegate`
 
-## System-Wide Impact
+Do not expand units into literal `RED/GREEN/REFACTOR` substeps.
 
-- **Interaction graph**: [What callbacks/middleware/observers fire when this runs?]
-- **Error propagation**: [How do errors flow across layers? Do retry strategies align?]
-- **State lifecycle risks**: [Can partial failure leave orphaned/inconsistent state?]
-- **API surface parity**: [What other interfaces expose similar functionality and need the same change?]
-- **Integration test scenarios**: [Cross-layer scenarios that unit tests won't catch]
+#### 3.6 Keep Planning-Time and Implementation-Time Unknowns Separate
 
-## Acceptance Criteria
+If something is important but not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it in the plan.
 
-- [ ] Detailed requirement 1
-- [ ] Detailed requirement 2
-- [ ] Testing requirements
+Examples:
+- Exact method or helper names
+- Final SQL or query details after touching real code
+- Runtime behavior that depends on seeing actual test failures
+- Refactors that may become unnecessary once implementation starts
 
-## Success Metrics
+### Phase 4: Write the Plan
 
-[How we measure success]
+Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution.
 
-## Dependencies & Risks
+#### 4.1 Plan Depth Guidance
 
-[What could block or complicate this]
+**Lightweight**
+- Keep the plan compact
+- Usually 2-4 implementation units
+- Omit optional sections that add little value
 
-## Sources & References
+**Standard**
+- Use the full core template, omitting optional sections (including High-Level Technical Design) that add no value for this particular work
+- Usually 3-6 implementation units
+- Include risks, deferred questions, and system-wide impact when relevant
 
-- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc
-- Similar implementations: [file_path:line_number]
-- Best practices: [documentation_url]
-- Related PRs: #[pr_number]
-```
+**Deep**
+- Use the full core template plus optional analysis sections where warranted
+- Usually 4-8 implementation units
+- Group units into phases when that improves clarity
+- Include alternatives considered, documentation impacts, and deeper risk treatment when warranted
 
-#### 📚 A LOT (Comprehensive Issue)
+#### 4.1b Optional Deep Plan Extensions
 
-**Best for:** Major features, architectural changes, complex integrations
+For sufficiently large, risky, or cross-cutting work, add the sections that genuinely help:
+- **Alternative Approaches Considered**
+- **Success Metrics**
+- **Dependencies / Prerequisites**
+- **Risk Analysis & Mitigation**
+- **Phased Delivery**
+- **Documentation Plan**
+- **Operational / Rollout Notes**
+- **Future Considerations** only when they materially affect current design
 
-**Includes everything from MORE plus:**
+Do not add these as boilerplate. Include them only when they improve execution quality or stakeholder alignment.
 
-- Detailed implementation plan with phases
-- Alternative approaches considered
-- Extensive technical specifications
-- Resource requirements and timeline
-- Future considerations and extensibility
-- Risk mitigation strategies
-- Documentation requirements
+#### 4.2 Core Plan Template
 
-**Structure:**
+Omit clearly inapplicable optional sections, especially for Lightweight plans.
 
 ```markdown
 ---
-title: [Issue Title]
+title: [Plan Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # include when planning from a requirements doc
+deepened: YYYY-MM-DD  # optional, set later by deepen-plan when the plan is substantively strengthened
 ---
 
-# [Issue Title]
+# [Plan Title]
 
 ## Overview
 
-[Executive summary]
-
-## Problem Statement
+[What is changing and why]
 
-[Detailed problem analysis]
+## Problem Frame
 
-## Proposed Solution
+[Summarize the user/business problem and context. Reference the origin doc when present.]
 
-[Comprehensive solution design]
+## Requirements Trace
 
-## Technical Approach
+- R1. [Requirement or success criterion this plan must satisfy]
+- R2. [Requirement or success criterion this plan must satisfy]
 
-### Architecture
+## Scope Boundaries
 
-[Detailed technical design]
+- [Explicit non-goal or exclusion]
 
-### Implementation Phases
+## Context & Research
 
-#### Phase 1: [Foundation]
+### Relevant Code and Patterns
 
-- Tasks and deliverables
-- Success criteria
-- Estimated effort
+- [Existing file, class, component, or pattern to follow]
 
-#### Phase 2: [Core Implementation]
-
-- Tasks and deliverables
-- Success criteria
-- Estimated effort
+### Institutional Learnings
 
-#### Phase 3: [Polish & Optimization]
+- [Relevant `docs/solutions/` insight]
 
-- Tasks and deliverables
-- Success criteria
-- Estimated effort
-
-## Alternative Approaches Considered
-
-[Other solutions evaluated and why rejected]
-
-## System-Wide Impact
+### External References
 
-### Interaction Graph
+- [Relevant external docs or best-practice source, if used]
 
-[Map the chain reaction: what callbacks, middleware, observers, and event handlers fire when this code runs? Trace at least two levels deep. Document: "Action X triggers Y, which calls Z, which persists W."]
+## Key Technical Decisions
 
-### Error & Failure Propagation
+- [Decision]: [Rationale]
 
-[Trace errors from lowest layer up. List specific error classes and where they're handled. Identify retry conflicts, unhandled error types, and silent failure swallowing.]
+## Open Questions
 
-### State Lifecycle Risks
+### Resolved During Planning
 
-[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.]
+- [Question]: [Resolution]
 
-### API Surface Parity
+### Deferred to Implementation
 
-[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.]
+- [Question or unknown]: [Why it is intentionally deferred]
 
-### Integration Test Scenarios
+<!-- Optional: Include this section only when the work involves DSL design, multi-component
+     integration, complex data flow, state-heavy lifecycle, or other cases where prose alone
+     would leave the approach shape ambiguous. Omit it entirely for well-patterned or
+     straightforward work. -->
+## High-Level Technical Design
 
-[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.]
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
 
-## Acceptance Criteria
+[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]
 
-### Functional Requirements
+## Implementation Units
 
-- [ ] Detailed functional criteria
+- [ ] **Unit 1: [Name]**
 
-### Non-Functional Requirements
+**Goal:** [What this unit accomplishes]
 
-- [ ] Performance targets
-- [ ] Security requirements
-- [ ] Accessibility standards
+**Requirements:** [R1, R2]
 
-### Quality Gates
+**Dependencies:** [None / Unit 1 / external prerequisite]
 
-- [ ] Test coverage requirements
-- [ ] Documentation completeness
-- [ ] Code review approval
+**Files:**
+- Create: `path/to/new_file`
+- Modify: `path/to/existing_file`
+- Test: `path/to/test_file`
 
-## Success Metrics
+**Approach:**
+- [Key design or sequencing decision]
 
-[Detailed KPIs and measurement methods]
+**Execution note:** [Optional test-first, characterization-first, external-delegate, or other execution posture signal]
 
-## Dependencies & Prerequisites
+**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*
 
-[Detailed dependency analysis]
+**Patterns to follow:**
+- [Existing file, class, or pattern]
 
-## Risk Analysis & Mitigation
+**Test scenarios:**
+- [Specific scenario with expected behavior]
+- [Edge case or failure path]
 
-[Comprehensive risk assessment]
+**Verification:**
+- [Outcome that should hold when this unit is complete]
 
-## Resource Requirements
+## System-Wide Impact
 
-[Team, time, infrastructure needs]
+- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
+- **Error propagation:** [How failures should travel across layers]
+- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
+- **API surface parity:** [Other interfaces that may require the same change]
+- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
 
-## Future Considerations
+## Risks & Dependencies
 
-[Extensibility and long-term vision]
+- [Meaningful risk, dependency, or sequencing concern]
 
-## Documentation Plan
+## Documentation / Operational Notes
 
-[What docs need updating]
+- [Docs, rollout, monitoring, or support impacts when relevant]
 
 ## Sources & References
 
-### Origin
-
-- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc. Key decisions carried forward: [list 2-3 major decisions from the origin]
-
-### Internal References
-
-- Architecture decisions: [file_path:line_number]
-- Similar features: [file_path:line_number]
-- Configuration: [file_path:line_number]
-
-### External References
-
-- Framework documentation: [url]
-- Best practices guide: [url]
-- Industry standards: [url]
-
-### Related Work
-
-- Previous PRs: #[pr_numbers]
-- Related issues: #[issue_numbers]
-- Design documents: [links]
+- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
+- Related code: [path or symbol]
+- Related PRs/issues: #[number]
+- External docs: [url]
 ```
 
-### 5. Issue Creation & Formatting
-
-<thinking>
-Apply best practices for clarity and actionability, making the issue easy to scan and understand
-</thinking>
+For larger `Deep` plans, extend the core template only when useful with sections such as:
 
-**Content Formatting:**
+```markdown
+## Alternative Approaches Considered
 
-- [ ] Use clear, descriptive headings with proper hierarchy (##, ###)
-- [ ] Include code examples in triple backticks with language syntax highlighting
-- [ ] Add screenshots/mockups if UI-related (drag & drop or use image hosting)
-- [ ] Use task lists (- [ ]) for trackable items that can be checked off
-- [ ] Add collapsible sections for lengthy logs or optional details using `<details>` tags
-- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)
+- [Approach]: [Why rejected or not chosen]
 
-**Cross-Referencing:**
+## Success Metrics
 
-- [ ] Link to related issues/PRs using #number format
-- [ ] Reference specific commits with SHA hashes when relevant
-- [ ] Link to code using GitHub's permalink feature (press 'y' for permanent link)
-- [ ] Mention relevant team members with @username if needed
-- [ ] Add links to external resources with descriptive text
+- [How we will know this solved the intended problem]
 
-**Code & Examples:**
+## Dependencies / Prerequisites
 
-````markdown
-# Good example with syntax highlighting and line references
+- [Technical, organizational, or rollout dependency]
 
+## Risk Analysis & Mitigation
 
-```ruby
-# app/services/user_service.rb:42
-def process_user(user)
+- [Risk]: [Mitigation]
 
-# Implementation here
+## Phased Delivery
 
-end
-```
+### Phase 1
+- [What lands first and why]
 
-# Collapsible error logs
+### Phase 2
+- [What follows and why]
 
-<details>
-<summary>Full error stacktrace</summary>
+## Documentation Plan
 
-`Error details here...`
+- [Docs or runbooks to update]
 
-</details>
-````
+## Operational / Rollout Notes
 
-**AI-Era Considerations:**
+- [Monitoring, migration, feature flag, or rollout considerations]
+```
 
-- [ ] Account for accelerated development with AI pair programming
-- [ ] Include prompts or instructions that worked well during research
-- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
-- [ ] Emphasize comprehensive testing given rapid implementation
-- [ ] Document any AI-generated code that needs human review
+#### 4.3 Planning Rules
 
-### 6. Final Review & Submission
+- Prefer path plus class/component/pattern references over brittle line numbers
+- Keep implementation units checkable with `- [ ]` syntax for progress tracking
+- Do not include implementation code — no imports, exact method signatures, or framework-specific syntax
+- Pseudo-code sketches and DSL grammars are allowed in the High-Level Technical Design section and per-unit technical design fields when they communicate design direction. Frame them explicitly as directional guidance, not implementation specification
+- Mermaid diagrams are encouraged when they clarify relationships or flows that prose alone would make hard to follow — ERDs for data model changes, sequence diagrams for multi-service interactions, state diagrams for lifecycle transitions, flowcharts for complex branching logic
+- Do not include git commands, commit messages, or exact test command recipes
+- Do not expand implementation units into micro-step `RED/GREEN/REFACTOR` instructions
+- Do not pretend an execution-time question is settled just to make the plan look complete
 
-**Origin document cross-check (if plan originated from a requirements doc):**
+### Phase 5: Final Review, Write File, and Handoff
 
-Before finalizing, re-read the origin document and verify:
-- [ ] Every key decision from the origin document is reflected in the plan
-- [ ] The chosen approach matches what was decided in the origin document
-- [ ] Constraints and requirements from the origin document are captured in acceptance criteria
-- [ ] Open questions from the origin document are either resolved or flagged
-- [ ] The `origin:` frontmatter field points to the correct source file
-- [ ] The Sources section includes the origin document with a summary of carried-forward decisions
+#### 5.1 Review Before Writing
 
-**Pre-submission Checklist:**
+Before finalizing, check:
+- The plan does not invent product behavior that should have been defined in `ce:brainstorm`
+- If there was no origin document, the bounded planning bootstrap established enough product clarity to plan responsibly
+- Every major decision is grounded in the origin document or research
+- Each implementation unit is concrete, dependency-ordered, and implementation-ready
+- If test-first or characterization-first posture was explicit or strongly implied, the relevant units carry it forward with a lightweight `Execution note`
+- Test scenarios are specific without becoming test code
+- Deferred items are explicit and not hidden as fake certainty
+- If a High-Level Technical Design section is included, it uses the right medium for the work, carries the non-prescriptive framing, and does not contain implementation code (no imports, exact signatures, or framework-specific syntax)
+- Per-unit technical design fields, if present, are concise and directional rather than copy-paste-ready
 
-- [ ] Title is searchable and descriptive
-- [ ] Labels accurately categorize the issue
-- [ ] All template sections are complete
-- [ ] Links and references are working
-- [ ] Acceptance criteria are measurable
-- [ ] Add names of files in pseudo code examples and todo lists
-- [ ] Add an ERD mermaid diagram if applicable for new model changes
+If the plan originated from a requirements document, re-read that document and verify:
+- The chosen approach still matches the product intent
+- Scope boundaries and success criteria are preserved
+- Blocking questions were either resolved, explicitly assumed, or sent back to `ce:brainstorm`
+- Every section of the origin document is addressed in the plan — scan each section to confirm nothing was silently dropped
 
-## Write Plan File
+#### 5.2 Write Plan File
 
 **REQUIRED: Write the plan file to disk before presenting any options.**
 
-```bash
-mkdir -p docs/plans/
-# Determine daily sequence number
-today=$(date +%Y-%m-%d)
-last_seq=$(ls docs/plans/${today}-*-plan.md 2>/dev/null | grep -oP "${today}-\K\d{3}" | sort -n | tail -1)
-next_seq=$(printf "%03d" $(( ${last_seq:-0} + 1 )))
-```
-
-Use the write tool to save the complete plan to `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md` (where NNN is `$next_seq` from the bash command above). This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
-
-Confirm: "Plan written to docs/plans/[filename]"
+Use the write tool to save the complete plan to:
 
-**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all question calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
-
-## Output Format
+```text
+docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
+```
 
-**Filename:** Use the date, daily sequence number, and kebab-case filename from Step 2 Title & Categorization.
+Confirm:
 
-```
-docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
+```text
+Plan written to docs/plans/[filename]
 ```
 
-Examples:
-- ✅ `docs/plans/2026-01-15-001-feat-user-authentication-flow-plan.md`
-- ✅ `docs/plans/2026-02-03-001-fix-checkout-race-condition-plan.md`
-- ✅ `docs/plans/2026-03-10-002-refactor-api-client-extraction-plan.md`
-- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (missing sequence number, not descriptive)
-- ❌ `docs/plans/2026-01-15-001-feat-new-feature-plan.md` (too vague - what feature?)
-- ❌ `docs/plans/2026-01-15-001-feat: user auth-plan.md` (invalid characters - colon and space)
-- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix and sequence number)
+**Pipeline mode:** If invoked from an automated workflow such as LFG, SLFG, or any `disable-model-invocation` context, skip interactive questions. Make the needed choices automatically and proceed to writing the plan.
 
-## Post-Generation Options
+#### 5.3 Post-Generation Options
 
-After writing the plan file, use the **question tool** to present these options:
+After writing the plan file, present the options 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.
 
 **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-NNN-<type>-<name>-plan.md`. What would you like to do next?"
 
 **Options:**
 1. **Open plan in editor** - Open the plan file for review
-2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
-3. **Review and refine** - Improve the document through structured self-review
-4. **Share to Proof** - Upload to Proof for collaborative review and sharing
-5. **Start `/ce:work`** - Begin implementing this plan locally
-6. **Start `/ce:work` on remote** - Begin implementing in OpenCode on the web (use `&` to run in background)
-7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
+2. **Run `/deepen-plan`** - Stress-test weak sections with targeted research when the plan needs more confidence
+3. **Run `document-review` skill** - Improve the plan through structured document review
+4. **Share to Proof** - Upload the plan for collaborative review and sharing
+5. **Start `/ce:work`** - Begin implementing this plan in the current environment
+6. **Start `/ce:work` in another session** - Begin implementing in a separate agent session when the current platform supports it
+7. **Create Issue** - Create an issue in the configured tracker
 
 Based on selection:
-- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
-- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
-- **Review and refine** → Load `document-review` skill.
-- **Share to Proof** → Upload the plan to Proof:
+- **Open plan in editor** → Open `docs/plans/<plan_filename>.md` using the current platform's file-open or editor mechanism (e.g., `open` on macOS, `xdg-open` on Linux, or the IDE's file-open API)
+- **`/deepen-plan`** → Call `/deepen-plan` with the plan path
+- **`document-review` skill** → Load the `document-review` skill with the plan path
+- **Share to Proof** → Upload the plan:
   ```bash
   CONTENT=$(cat docs/plans/<plan_filename>.md)
   TITLE="Plan: <plan title from frontmatter>"
@@ -599,45 +616,38 @@ Based on selection:
     -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
   PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
   ```
-  Display: `View & collaborate in Proof: <PROOF_URL>` — skip silently if curl fails. Then return to options.
-- **`/ce:work`** → Call the /ce:work command with the plan file path
-- **`/ce:work` on remote** → Run `/ce:work docs/plans/<plan_filename>.md &` to start work in background for OpenCode web
-- **Create Issue** → See "Issue Creation" section below
-- **Other** (automatically provided) → Accept free text for rework or specific changes
-
-**Note:** If running `/ce:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
+  Display `View & collaborate in Proof: <PROOF_URL>` if successful, then return to the options
+- **`/ce:work`** → Call `/ce:work` with the plan path
+- **`/ce:work` in another session** → If the current platform supports launching a separate agent session, start `/ce:work` with the plan path there. Otherwise, explain the limitation briefly and offer to run `/ce:work` in the current session instead.
+- **Create Issue** → Follow the Issue Creation section below
+- **Other** → Accept free text for revisions and loop back to options
 
-Loop back to options after Simplify or Other changes until user selects `/ce:work` or another action.
+If running with ultrathink enabled, or the platform's reasoning/effort level is set to max or extra-high, automatically run `/deepen-plan` only when the plan is `Standard` or `Deep`, high-risk, or still shows meaningful confidence gaps in decisions, sequencing, system-wide impact, risks, or verification.
 
 ## Issue Creation
 
-When user selects "Create Issue", detect their project tracker from AGENTS.md:
-
-1. **Check for tracker preference** in user's AGENTS.md (global or project):
-   - Look for `project_tracker: github` or `project_tracker: linear`
-   - Or look for mentions of "GitHub Issues" or "Linear" in their workflow section
-
-2. **If GitHub:**
+When the user selects "Create Issue", detect their project tracker from `AGENTS.md` or, if needed for compatibility, `AGENTS.md`:
 
-   Use the title and type from Step 2 (already in context - no need to re-read the file):
+1. Look for `project_tracker: github` or `project_tracker: linear`
+2. If GitHub:
 
    ```bash
    gh issue create --title "<type>: <title>" --body-file <plan_path>
    ```
 
-3. **If Linear:**
+3. If Linear:
 
    ```bash
    linear issue create --title "<title>" --description "$(cat <plan_path>)"
    ```
 
-4. **If no tracker configured:**
-   Ask user: "Which project tracker do you use? (GitHub/Linear/Other)"
-   - Suggest adding `project_tracker: github` or `project_tracker: linear` to their AGENTS.md
+4. If no tracker is configured:
+   - Ask which tracker they use using the platform's blocking question tool when available (see Interaction Method)
+   - Suggest adding the tracker to `AGENTS.md` for future runs
 
-5. **After creation:**
-   - Display the issue URL
-   - Ask if they want to proceed to `/ce:work`
+After issue creation:
+- Display the issue URL
+- Ask whether to proceed to `/ce:work`
 
-NEVER CODE! Just research and write the plan.
+NEVER CODE! Research, decide, and write the plan.