admin/.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 Jira epics. Systematic 6-step 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 jira epics	true

Solution Planning

Decompose a problem and solution into architecture, data model, deployment plan, system flows, components, tests, and Jira 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.

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: Jira Epics

Read and follow steps/06_jira-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. Jira 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                                    │
└────────────────────────────────────────────────────────────────┘