---
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 75% | 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                                    │
└────────────────────────────────────────────────────────────────┘
```
