satellite-provider/.cursor/skills/plan/SKILL.md

name, description, category, tags, disable-model-invocation

name	description	category	tags	disable-model-invocation
plan	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"	build	planning architecture components testing work-items epics	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                                    │
└────────────────────────────────────────────────────────────────┘