--- name: plan description: | Decompose a solution into architecture, data model, deployment plan, system flows, components, tests, and work item epics. Systematic planning workflow with BLOCKING gates, self-verification, and structured artifact management. Uses _docs/ + _docs/02_document/ structure. Trigger phrases: - "plan", "decompose solution", "architecture planning" - "break down the solution", "create planning documents" - "component decomposition", "solution analysis" category: build tags: [planning, architecture, components, testing, work-items, epics] disable-model-invocation: true --- # Solution Planning Decompose a problem and solution into architecture, data model, deployment plan, system flows, components, tests, and work item epics through a systematic 6-step workflow. ## Core Principles - **Single Responsibility**: each component does one thing well; do not spread related logic across components - **Dumb code, smart data**: keep logic simple, push complexity into data structures and configuration - **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work - **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding - **Plan, don't code**: this workflow produces documents and specs, never implementation code ## Context Resolution Fixed paths — no mode detection needed: - PROBLEM_FILE: `_docs/00_problem/problem.md` - SOLUTION_FILE: `_docs/01_solution/solution.md` - DOCUMENT_DIR: `_docs/02_document/` Announce the resolved paths to the user before proceeding. ## Required Files | File | Purpose | |------|---------| | `_docs/00_problem/problem.md` | Problem description and context | | `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria | | `_docs/00_problem/restrictions.md` | Constraints and limitations | | `_docs/00_problem/input_data/` | Reference data examples | | `_docs/01_solution/solution.md` | Finalized solution to decompose | ## Prerequisites Read and follow `steps/00_prerequisites.md`. All three prerequisite checks are **BLOCKING** — do not start the workflow until they pass. ## Artifact Management Read `steps/01_artifact-management.md` for directory structure, save timing, save principles, and resumability rules. Refer to it throughout the workflow. ## Progress Tracking At the start of execution, create a TodoWrite with all steps (1 through 6 plus Final). Update status as each step completes. ## Workflow ### Step 1: Blackbox Tests Read and execute `.cursor/skills/test-spec/SKILL.md`. This is a planning context — no source code exists yet, so test-spec Phase 4 (script generation) is skipped. Script creation is handled later by the decompose skill as a task. Capture any new questions, findings, or insights that arise during test specification — these feed forward into Steps 2 and 3. --- ### Step 2: Solution Analysis Read and follow `steps/02_solution-analysis.md`. --- ### Step 3: Component Decomposition Read and follow `steps/03_component-decomposition.md`. --- ### Step 4: Architecture Review & Risk Assessment Read and follow `steps/04_review-risk.md`. --- ### Step 5: Test Specifications Read and follow `steps/05_test-specifications.md`. --- ### Step 6: Work Item Epics Read and follow `steps/06_work-item-epics.md`. --- ### Final: Quality Checklist Read and follow `steps/07_quality-checklist.md`. ## Common Mistakes - **Proceeding without input data**: all three data gate items (acceptance_criteria, restrictions, input_data) must be present before any planning begins - **Coding during planning**: this workflow produces documents, never code - **Multi-responsibility components**: if a component does two things, split it - **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation - **Diagrams without data**: generate diagrams only after the underlying structure is documented - **Copy-pasting problem.md**: the architecture doc should analyze and transform, not repeat the input - **Vague interfaces**: "component A talks to component B" is not enough; define the method, input, output - **Ignoring restrictions.md**: every constraint must be traceable in the architecture or risk register - **Ignoring blackbox test findings**: insights from Step 1 must feed into architecture (Step 2) and component decomposition (Step 3) ## Escalation Rules | Situation | Action | |-----------|--------| | Missing acceptance_criteria.md, restrictions.md, or input_data/ | **STOP** — planning cannot proceed | | Ambiguous requirements | ASK user | | Input data coverage below 70% | Search internet for supplementary data, ASK user to validate | | Technology choice with multiple valid options | ASK user | | Component naming | PROCEED, confirm at next BLOCKING gate | | File structure within templates | PROCEED | | Contradictions between input files | ASK user | | Risk mitigation requires architecture change | ASK user | ## Methodology Quick Reference ``` ┌────────────────────────────────────────────────────────────────┐ │ Solution Planning (6-Step + Final) │ ├────────────────────────────────────────────────────────────────┤ │ PREREQ: Data Gate (BLOCKING) │ │ → verify AC, restrictions, input_data, solution exist │ │ │ │ 1. Blackbox Tests → test-spec/SKILL.md │ │ [BLOCKING: user confirms test coverage] │ │ 2. Solution Analysis → architecture, data model, deployment │ │ [BLOCKING: user confirms architecture] │ │ 3. Component Decomp → component specs + interfaces │ │ [BLOCKING: user confirms components] │ │ 4. Review & Risk → risk register, iterations │ │ [BLOCKING: user confirms mitigations] │ │ 5. Test Specifications → per-component test specs │ │ 6. Work Item Epics → epic per component + bootstrap │ │ ───────────────────────────────────────────────── │ │ Final: Quality Checklist → FINAL_report.md │ ├────────────────────────────────────────────────────────────────┤ │ Principles: Single Responsibility · Dumb code, smart data │ │ Save immediately · Ask don't assume │ │ Plan don't code │ └────────────────────────────────────────────────────────────────┘ ```