---
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, ADRs, tests, and work item epics through a systematic workflow with seven step files (1, 2, 3, 4, 4.5, 5, 6) plus a Final quality checklist.

## 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, 2, 3, 4, 4.5, 5, 6 plus Final). Update status as each step completes. The fractional Step 4.5 (ADR Capture) sits between Architecture Review (Step 4) and Test Specifications (Step 5).

## 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`. The step opens with **Phase 2a.0: Glossary & Architecture Vision** (BLOCKING) — drafts `_docs/02_document/glossary.md` and a one-paragraph architecture vision, presents the condensed view to the user, iterates until confirmed, then proceeds into the architecture, data-model, and deployment phases. The confirmed vision becomes the first `## Architecture Vision` H2 of `architecture.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 4.5: Architecture Decision Records (ADRs)

Read and follow `steps/04-5_adr-capture.md`.

This step captures the architecture and tech-stack decisions that were made (or revised) in Steps 2–4 as durable, dated, immutable records under `_docs/02_document/adr/`. ADRs are the single thing in `_docs/` that explain the **why** of each major decision after the conversation history is gone. They are consumed by `decompose` (when bootstrapping module layout), `new-task` (when assessing a new feature against existing decisions), `refactor` (when proposing replacements), and any future code-review cycle that needs to confirm a structural choice was deliberate.

This step is **BLOCKING**: the ADR set must be reviewed and confirmed by the user before Step 5 begins.

---

### 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
- **Skipping the glossary/vision gate (Phase 2a.0)**: drafting `architecture.md` from raw `solution.md` without confirming terminology and vision means the AI's mental model is not aligned with the user's; every downstream artifact will inherit that drift
- **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 the canonical threshold (`cursor-meta.mdc` Quality Thresholds) | 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   → glossary + vision, architecture,       │
│                          data model, deployment                 │
│    [BLOCKING 2a.0: user confirms glossary + vision]            │
│    [BLOCKING 2a:   user confirms architecture]                  │
│ 3. Component Decomp    → component specs + interfaces           │
│    [BLOCKING: user confirms components]                        │
│ 4. Review & Risk       → risk register, iterations              │
│    [BLOCKING: user confirms mitigations]                       │
│ 4.5 ADR Capture        → _docs/02_document/adr/NNN_*.md         │
│    [BLOCKING: user confirms ADR set]                           │
│ 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                                    │
└────────────────────────────────────────────────────────────────┘
```
