diff --git a/plugins/compound-engineering/skills/ce-plan/SKILL.md b/plugins/compound-engineering/skills/ce-plan/SKILL.md index ea41e95..2ee88b8 100644 --- a/plugins/compound-engineering/skills/ce-plan/SKILL.md +++ b/plugins/compound-engineering/skills/ce-plan/SKILL.md @@ -1,16 +1,22 @@ --- 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", "how should we build", "write a tech plan", "plan the implementation", or when a brainstorm/requirements document is ready for implementation planning. Also triggers on "what's the approach for", "break this down", or references to an existing requirements doc that needs a technical plan. +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. + +This workflow produces a durable implementation plan. It does **not** implement code, run tests, or learn from execution-time results. If the answer depends on changing code and seeing what happens, that belongs in `ce:work`, not here. + +## Interaction Method + +Use the platform's interactive question mechanism when available. Otherwise, present numbered options in chat and wait for the user's reply before proceeding. + +Ask one question at a time. Prefer a concise single-select choice when natural options exist. ## Feature Description @@ -18,579 +24,506 @@ Transform feature descriptions, bug reports, or improvement ideas into well-stru **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." -Do not proceed until you have a clear feature description from the user. +Do not proceed until you have a clear planning input. -### 0. Idea Refinement +## Core Principles -**Check for requirements document first:** +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. +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. -Before asking questions, look for recent requirements documents in `docs/brainstorms/` that match this feature: +## Plan Quality Bar -```bash -ls -la docs/brainstorms/*-requirements.md 2>/dev/null | head -10 -``` +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 + +A plan is ready when an implementer can start confidently without needing the plan to write the code for them. + +## Workflow + +### Phase 0: Resume, Source, and Scope + +#### 0.1 Resume Existing Plan Work When Appropriate + +If the user references an existing plan file or there is an obvious recent matching plan in `docs/plans/`: +- Read it +- Confirm whether to update it in place or create a new plan +- If updating, preserve completed checkboxes and revise only the still-relevant sections + +#### 0.2 Find Upstream Requirements Document + +Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`. **Relevance criteria:** A requirements document is relevant if: -- The topic (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 +- 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 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: )` 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. +If multiple source documents match, ask which one to use before proceeding. -**If multiple source documents could match:** -Use **AskUserQuestion tool** to ask which source document to use, or whether to proceed without one. +#### 0.3 Use the Source Document as Primary Input -**If no requirements document is found (or not relevant), run idea refinement:** +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: )` +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. -Refine the idea through collaborative dialogue using the **AskUserQuestion tool**: +If no relevant requirements document exists, planning may proceed from the user's request directly. -- 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" +#### 0.4 No-Requirements-Doc Fallback -**Gather signals for research decision.** During refinement, note: +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 -- **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? +The planning bootstrap should establish: +- Problem frame +- Intended behavior +- Scope boundaries and obvious non-goals +- Success criteria +- Blocking questions or assumptions -**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?" +Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm. -## Main Tasks +If the bootstrap uncovers major unresolved product questions: +- Recommend `ce:brainstorm` again +- If the user still wants to continue, require explicit assumptions before proceeding -### 1. Local Research (Always Runs - Parallel) +#### 0.5 Classify Outstanding Questions Before Planning - -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. - +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 -Run these agents **in parallel** to gather local context: +If true product blockers remain: +- Surface them clearly +- Ask the user 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 -- Task compound-engineering:research:repo-research-analyst(feature_description) -- Task compound-engineering:research:learnings-researcher(feature_description) +#### 0.6 Assess Plan Depth -**What to look for:** -- **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency -- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned) +Classify the work into one of these plan depths: -These findings inform the next step. +- **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 -### 1.5. Research Decision +If depth is unclear, ask one targeted question and then continue. -Based on signals from Step 0 and findings from Step 1, decide on external research. +### Phase 1: Gather Context -**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. +#### 1.1 Local Research (Always Runs) -**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value. - -**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable. - -**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed. - -Examples: -- "Your codebase has solid patterns for this. Proceeding without external research." -- "This involves payment processing, so I'll research current best practices first." - -### 1.5b. External Research (Conditional) - -**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 compound-engineering:research:best-practices-researcher(feature_description) -- Task compound-engineering:research:framework-docs-researcher(feature_description) +- Task compound-engineering:research:repo-research-analyst(planning context summary) +- Task compound-engineering:research:learnings-researcher(planning context summary) -### 1.6. Consolidate Research +Collect: +- Existing patterns and conventions to follow +- Relevant files, modules, and tests +- CLAUDE.md or AGENTS.md guidance that materially affects the plan +- Institutional learnings from `docs/solutions/` -After all research steps complete, consolidate findings: +#### 1.2 Decide on External Research -- 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 CLAUDE.md conventions +Based on the origin document, user signals, and local findings, decide whether external research adds value. -**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning. +**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? -### 2. Issue Planning & Structure +**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 - -Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives - +**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 -**Title & Categorization:** +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." -- [ ] 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 +#### 1.3 External Research (Conditional) -**Stakeholder Analysis:** +If Step 1.2 indicates external research is useful, run these agents in parallel: -- [ ] Identify who will be affected by this issue (end users, developers, operations) -- [ ] Consider implementation complexity and required expertise +- Task compound-engineering:research:best-practices-researcher(planning context summary) +- Task compound-engineering:research:framework-docs-researcher(planning context summary) -**Content Planning:** +#### 1.4 Consolidate Research -- [ ] 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 +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 -### 3. SpecFlow Analysis +#### 1.5 Flow and Edge-Case Analysis (Conditional) -After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification: +For **Standard** or **Deep** plans, or when user flow completeness is still unclear, run: -- Task compound-engineering:workflow:spec-flow-analyzer(feature_description, research_findings) +- Task compound-engineering:workflow:spec-flow-analyzer(planning context summary, research findings) -**SpecFlow Analyzer Output:** +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 -- [ ] Review SpecFlow analysis results -- [ ] Incorporate any identified gaps or edge cases into the issue -- [ ] Update acceptance criteria based on SpecFlow findings +### Phase 2: Resolve Planning Questions -### 4. Choose Implementation Detail Level +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 -Select how comprehensive you want the issue to be, simpler is mostly better. +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 -#### 📄 MINIMAL (Quick Issue) +Ask the user only when the answer materially affects architecture, scope, sequencing, or risk and cannot be responsibly inferred. -**Best for:** Simple bugs, small improvements, clear features +**Do not** run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution. -**Includes:** +### Phase 3: Structure the Plan -- Problem statement or feature description -- Basic acceptance criteria -- Essential context only +#### 3.1 Title and File Naming -**Structure:** +- 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---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) -````markdown ---- -title: [Issue Title] -type: [feat|fix|refactor] -status: active -date: YYYY-MM-DD -origin: docs/brainstorms/YYYY-MM-DD--requirements.md # if originated from a requirements doc, otherwise omit ---- +#### 3.2 Stakeholder and Impact Awareness -# [Issue Title] +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. -[Brief problem/feature description] +#### 3.3 Break Work into Implementation Units -## Acceptance Criteria +Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic commit. -- [ ] Core requirement 1 -- [ ] Core requirement 2 +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 -## Context +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 -[Any critical information] +#### 3.4 Define Each Implementation Unit -## MVP +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 +- **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 -### test.rb +Every feature-bearing unit should include the test file path in `**Files:**`. -```ruby -class Test - def initialize - @name = "test" - end -end -``` +#### 3.5 Keep Planning-Time and Implementation-Time Unknowns Separate -## Sources +If something is important but not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it in the plan. -- **Origin document:** [docs/brainstorms/YYYY-MM-DD--requirements.md](path) — include if plan originated from an upstream requirements doc -- Related issue: #[issue_number] -- Documentation: [relevant_docs_url] -```` +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 -#### 📋 MORE (Standard Issue) +### Phase 4: Write the Plan -**Best for:** Most features, complex bugs, team collaboration +Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution. -**Includes everything from MINIMAL plus:** +#### 4.1 Plan Depth Guidance -- Detailed background and motivation -- Technical considerations -- Success metrics -- Dependencies and risks -- Basic implementation suggestions +**Lightweight** +- Keep the plan compact +- Usually 2-4 implementation units +- Omit optional sections that add little value -**Structure:** +**Standard** +- Use the full core template +- Usually 3-6 implementation units +- Include risks, deferred questions, and system-wide impact when relevant + +**Deep** +- Use the full core template plus optional analysis sections +- Usually 4-8 implementation units +- Group units into phases when that improves clarity +- Include alternatives considered, documentation impacts, and deeper risk treatment when warranted + +#### 4.1b Optional Deep Plan Extensions + +For sufficiently large, risky, or cross-cutting work, add the sections that genuinely help: +- **Alternative Approaches Considered** +- **Success Metrics** +- **Dependencies / Prerequisites** +- **Risk Analysis & Mitigation** +- **Phased Delivery** +- **Documentation Plan** +- **Operational / Rollout Notes** +- **Future Considerations** only when they materially affect current design + +Do not add these as boilerplate. Include them only when they improve execution quality or stakeholder alignment. + +#### 4.2 Core Plan Template + +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--requirements.md # if originated from a requirements doc, otherwise omit +origin: docs/brainstorms/YYYY-MM-DD--requirements.md # include when planning from a requirements doc --- -# [Issue Title] +# [Plan Title] ## Overview -[Comprehensive description] +[What is changing and why] -## Problem Statement / Motivation +## Problem Frame -[Why this matters] +[Summarize the user/business problem and context. Reference the origin doc when present.] -## Proposed Solution +## Requirements Trace -[High-level approach] +- R1. [Requirement or success criterion this plan must satisfy] +- R2. [Requirement or success criterion this plan must satisfy] -## Technical Considerations +## Scope Boundaries -- Architecture impacts -- Performance implications -- Security considerations +- [Explicit non-goal or exclusion] -## System-Wide Impact +## Context & Research -- **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] +### Relevant Code and Patterns -## Acceptance Criteria +- [Existing file, class, component, or pattern to follow] -- [ ] Detailed requirement 1 -- [ ] Detailed requirement 2 -- [ ] Testing requirements +### Institutional Learnings -## Success Metrics - -[How we measure success] - -## Dependencies & Risks - -[What could block or complicate this] - -## Sources & References - -- **Origin document:** [docs/brainstorms/YYYY-MM-DD--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] -``` - -#### 📚 A LOT (Comprehensive Issue) - -**Best for:** Major features, architectural changes, complex integrations - -**Includes everything from MORE plus:** - -- Detailed implementation plan with phases -- Alternative approaches considered -- Extensive technical specifications -- Resource requirements and timeline -- Future considerations and extensibility -- Risk mitigation strategies -- Documentation requirements - -**Structure:** - -```markdown ---- -title: [Issue Title] -type: [feat|fix|refactor] -status: active -date: YYYY-MM-DD -origin: docs/brainstorms/YYYY-MM-DD--requirements.md # if originated from a requirements doc, otherwise omit ---- - -# [Issue Title] - -## Overview - -[Executive summary] - -## Problem Statement - -[Detailed problem analysis] - -## Proposed Solution - -[Comprehensive solution design] - -## Technical Approach - -### Architecture - -[Detailed technical design] - -### Implementation Phases - -#### Phase 1: [Foundation] - -- Tasks and deliverables -- Success criteria -- Estimated effort - -#### Phase 2: [Core Implementation] - -- Tasks and deliverables -- Success criteria -- Estimated effort - -#### Phase 3: [Polish & Optimization] - -- Tasks and deliverables -- Success criteria -- Estimated effort - -## Alternative Approaches Considered - -[Other solutions evaluated and why rejected] - -## System-Wide Impact - -### Interaction Graph - -[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."] - -### Error & Failure Propagation - -[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.] - -### State Lifecycle Risks - -[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.] - -### API Surface Parity - -[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.] - -### Integration Test Scenarios - -[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.] - -## Acceptance Criteria - -### Functional Requirements - -- [ ] Detailed functional criteria - -### Non-Functional Requirements - -- [ ] Performance targets -- [ ] Security requirements -- [ ] Accessibility standards - -### Quality Gates - -- [ ] Test coverage requirements -- [ ] Documentation completeness -- [ ] Code review approval - -## Success Metrics - -[Detailed KPIs and measurement methods] - -## Dependencies & Prerequisites - -[Detailed dependency analysis] - -## Risk Analysis & Mitigation - -[Comprehensive risk assessment] - -## Resource Requirements - -[Team, time, infrastructure needs] - -## Future Considerations - -[Extensibility and long-term vision] - -## Documentation Plan - -[What docs need updating] - -## Sources & References - -### Origin - -- **Origin document:** [docs/brainstorms/YYYY-MM-DD--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] +- [Relevant `docs/solutions/` insight] ### External References -- Framework documentation: [url] -- Best practices guide: [url] -- Industry standards: [url] +- [Relevant external docs or best-practice source, if used] -### Related Work +## Key Technical Decisions -- Previous PRs: #[pr_numbers] -- Related issues: #[issue_numbers] -- Design documents: [links] +- [Decision]: [Rationale] + +## Open Questions + +### Resolved During Planning + +- [Question]: [Resolution] + +### Deferred to Implementation + +- [Question or unknown]: [Why it is intentionally deferred] + +## Implementation Units + +- [ ] **Unit 1: [Name]** + +**Goal:** [What this unit accomplishes] + +**Requirements:** [R1, R2] + +**Dependencies:** [None / Unit 1 / external prerequisite] + +**Files:** +- Create: `path/to/new_file` +- Modify: `path/to/existing_file` +- Test: `path/to/test_file` + +**Approach:** +- [Key design or sequencing decision] + +**Patterns to follow:** +- [Existing file, class, or pattern] + +**Test scenarios:** +- [Specific scenario with expected behavior] +- [Edge case or failure path] + +**Verification:** +- [Outcome that should hold when this unit is complete] + +## System-Wide Impact + +- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected] +- **Error propagation:** [How failures should travel across layers] +- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns] +- **API surface parity:** [Other interfaces that may require the same change] +- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove] + +## Risks & Dependencies + +- [Meaningful risk, dependency, or sequencing concern] + +## Documentation / Operational Notes + +- [Docs, rollout, monitoring, or support impacts when relevant] + +## Sources & References + +- **Origin document:** [docs/brainstorms/YYYY-MM-DD--requirements.md](path) +- Related code: [path or symbol] +- Related PRs/issues: #[number] +- External docs: [url] ``` -### 5. Issue Creation & Formatting +For larger `Deep` plans, extend the core template only when useful with sections such as: - -Apply best practices for clarity and actionability, making the issue easy to scan and understand - +```markdown +## Alternative Approaches Considered -**Content Formatting:** +- [Approach]: [Why rejected or not chosen] -- [ ] 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 `
` tags -- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor) +## Success Metrics -**Cross-Referencing:** +- [How we will know this solved the intended problem] -- [ ] 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 +## Dependencies / Prerequisites -**Code & Examples:** +- [Technical, organizational, or rollout dependency] -````markdown -# Good example with syntax highlighting and line references +## Risk Analysis & Mitigation +- [Risk]: [Mitigation] -```ruby -# app/services/user_service.rb:42 -def process_user(user) +## Phased Delivery -# Implementation here +### Phase 1 +- [What lands first and why] -end +### Phase 2 +- [What follows and why] + +## Documentation Plan + +- [Docs or runbooks to update] + +## Operational / Rollout Notes + +- [Monitoring, migration, feature flag, or rollout considerations] ``` -# Collapsible error logs +#### 4.3 Planning Rules -
-Full error stacktrace +- Prefer path plus class/component/pattern references over brittle line numbers +- Keep implementation units checkable with `- [ ]` syntax for progress tracking +- Do not include fenced implementation code blocks unless the plan itself is about code shape as a design artifact +- Do not include git commands, commit messages, or exact test command recipes +- Do not pretend an execution-time question is settled just to make the plan look complete +- Include mermaid diagrams 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 -`Error details here...` +### Phase 5: Final Review, Write File, and Handoff -
-```` +#### 5.1 Review Before Writing -**AI-Era Considerations:** +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 +- Test scenarios are specific without becoming test code +- Deferred items are explicit and not hidden as fake certainty -- [ ] 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 +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 -### 6. Final Review & Submission - -**Origin document cross-check (if plan originated from a requirements doc):** - -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 - -**Pre-submission Checklist:** - -- [ ] 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 - -## 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: -Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-NNN---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]" - -**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts. - -## Output Format - -**Filename:** Use the date, daily sequence number, and kebab-case filename from Step 2 Title & Categorization. - -``` +```text docs/plans/YYYY-MM-DD-NNN---plan.md ``` -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) +Confirm: -## Post-Generation Options +```text +Plan written to docs/plans/[filename] +``` -After writing the plan file, use the **AskUserQuestion tool** to present these options: +**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. + +#### 5.3 Post-Generation Options + +After writing the plan file, present the options using the platform's interactive question mechanism when available. Otherwise present numbered options in chat. **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-NNN---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 +2. **Run `/deepen-plan`** - Enhance sections with parallel research agents +3. **Review and refine** - 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 locally -6. **Start `/ce:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background) -7. **Create Issue** - Create issue in project tracker (GitHub/Linear) +6. **Start `/ce:work` on remote** - Begin implementing in Claude Code on the web +7. **Create Issue** - Create an issue in the configured tracker Based on selection: -- **Open plan in editor** → Run `open docs/plans/.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** → Run `open docs/plans/.md` +- **`/deepen-plan`** → Call `/deepen-plan` with the plan path +- **Review and refine** → Load the `document-review` skill +- **Share to Proof** → Upload the plan: ```bash CONTENT=$(cat docs/plans/.md) TITLE="Plan: " @@ -599,44 +532,37 @@ 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: ` — 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/.md &` to start work in background for Claude Code web -- **Create Issue** → See "Issue Creation" section below -- **Other** (automatically provided) → Accept free text for rework or specific changes + Display `View & collaborate in Proof: ` if successful, then return to the options +- **`/ce:work`** → Call `/ce:work` with the plan path +- **`/ce:work` on remote** → Run `/ce:work docs/plans/.md &` +- **Create Issue** → Follow the Issue Creation section below +- **Other** → Accept free text for revisions and loop back to options -**Note:** If running `/ce:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding. - -Loop back to options after Simplify or Other changes until user selects `/ce:work` or another action. +If running with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum grounding. ## Issue Creation -When user selects "Create Issue", detect their project tracker from CLAUDE.md: +When the user selects "Create Issue", detect their project tracker from CLAUDE.md: -1. **Check for tracker preference** in user's CLAUDE.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:** - - 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 ": " --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 CLAUDE.md +4. If no tracker is configured: + - Ask which tracker they use + - Suggest adding the tracker to CLAUDE.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.