gps-denied-onboard/.cursor/skills/plan/SKILL.md

---
name: plan
description: |
  Decompose a solution into architecture, 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_plans/ 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, jira, epics]
disable-model-invocation: true
---

# Solution Planning

Decompose a problem and solution into architecture, 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`
- PLANS_DIR: `_docs/02_plans/`

Announce the resolved paths to the user before proceeding.

## Input Specification

### 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 |

### Prerequisite Checks (BLOCKING)

Run sequentially before any planning step:

**Prereq 1: Data Gate**

1. `_docs/00_problem/acceptance_criteria.md` exists and is non-empty — **STOP if missing**
2. `_docs/00_problem/restrictions.md` exists and is non-empty — **STOP if missing**
3. `_docs/00_problem/input_data/` exists and contains at least one data file — **STOP if missing**
4. `_docs/00_problem/problem.md` exists and is non-empty — **STOP if missing**

All four are mandatory. If any is missing or empty, STOP and ask the user to provide them. If the user cannot provide the required data, planning cannot proceed — just stop.

**Prereq 2: Finalize Solution Draft**

Only runs after the Data Gate passes:

1. Scan `_docs/01_solution/` for files matching `solution_draft*.md`
2. Identify the highest-numbered draft (e.g. `solution_draft06.md`)
3. **Rename** it to `_docs/01_solution/solution.md`
4. If `solution.md` already exists, ask the user whether to overwrite or keep existing
5. Verify `solution.md` is non-empty — **STOP if missing or empty**

**Prereq 3: Workspace Setup**

1. Create PLANS_DIR if it does not exist
2. If PLANS_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**

## Artifact Management

### Directory Structure

All artifacts are written directly under PLANS_DIR:

```
PLANS_DIR/
├── integration_tests/
│   ├── environment.md
│   ├── test_data.md
│   ├── functional_tests.md
│   ├── non_functional_tests.md
│   └── traceability_matrix.md
├── architecture.md
├── system-flows.md
├── risk_mitigations.md
├── risk_mitigations_02.md          (iterative, ## as sequence)
├── components/
│   ├── 01_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   ├── 02_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   └── ...
├── common-helpers/
│   ├── 01_helper_[name]/
│   ├── 02_helper_[name]/
│   └── ...
├── diagrams/
│   ├── components.drawio
│   └── flows/
│       ├── flow_[name].md          (Mermaid)
│       └── ...
└── FINAL_report.md
```

### Save Timing

| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Integration test environment spec | `integration_tests/environment.md` |
| Step 1 | Integration test data spec | `integration_tests/test_data.md` |
| Step 1 | Integration functional tests | `integration_tests/functional_tests.md` |
| Step 1 | Integration non-functional tests | `integration_tests/non_functional_tests.md` |
| Step 1 | Integration traceability matrix | `integration_tests/traceability_matrix.md` |
| Step 2 | Architecture analysis complete | `architecture.md` |
| Step 2 | System flows documented | `system-flows.md` |
| Step 3 | Each component analyzed | `components/[##]_[name]/description.md` |
| Step 3 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
| Step 3 | Diagrams generated | `diagrams/` |
| Step 4 | Risk assessment complete | `risk_mitigations.md` |
| Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
| Step 6 | Epics created in Jira | Jira via MCP |
| Final | All steps complete | `FINAL_report.md` |

### Save Principles

1. **Save immediately**: write to disk as soon as a step completes; do not wait until the end
2. **Incremental updates**: same file can be updated multiple times; append or replace
3. **Preserve process**: keep all intermediate files even after integration into final report
4. **Enable recovery**: if interrupted, resume from the last saved artifact (see Resumability)

### Resumability

If PLANS_DIR already contains artifacts:

1. List existing files and match them to the save timing table above
2. Identify the last completed step based on which artifacts exist
3. Resume from the next incomplete step
4. Inform the user which steps are being skipped

## Progress Tracking

At the start of execution, create a TodoWrite with all steps (1 through 6). Update status as each step completes.

## Workflow

### Step 1: Integration Tests

**Role**: Professional Quality Assurance Engineer
**Goal**: Analyze input data completeness and produce detailed black-box integration test specifications
**Constraints**: Spec only — no test code. Tests describe what the system should do given specific inputs, not how the system is built.

#### Phase 1a: Input Data Completeness Analysis

1. Read `_docs/01_solution/solution.md` (finalized in Prereq 2)
2. Read `acceptance_criteria.md`, `restrictions.md`
3. Read testing strategy from solution.md
4. Analyze `input_data/` contents against:
   - Coverage of acceptance criteria scenarios
   - Coverage of restriction edge cases
   - Coverage of testing strategy requirements
5. Threshold: at least 70% coverage of the scenarios
6. If coverage is low, search the internet for supplementary data, assess quality with user, and if user agrees, add to `input_data/`
7. Present coverage assessment to user

**BLOCKING**: Do NOT proceed until user confirms the input data coverage is sufficient.

#### Phase 1b: Black-Box Test Scenario Specification

Based on all acquired data, acceptance_criteria, and restrictions, form detailed test scenarios:

1. Define test environment using `templates/integration-environment.md` as structure
2. Define test data management using `templates/integration-test-data.md` as structure
3. Write functional test scenarios (positive + negative) using `templates/integration-functional-tests.md` as structure
4. Write non-functional test scenarios (performance, resilience, security, edge cases) using `templates/integration-non-functional-tests.md` as structure
5. Build traceability matrix using `templates/integration-traceability-matrix.md` as structure

**Self-verification**:
- [ ] Every acceptance criterion is covered by at least one test scenario
- [ ] Every restriction is verified by at least one test scenario
- [ ] Positive and negative scenarios are balanced
- [ ] Consumer app has no direct access to system internals
- [ ] Docker environment is self-contained (`docker compose up` sufficient)
- [ ] External dependencies have mock/stub services defined
- [ ] Traceability matrix has no uncovered AC or restrictions

**Save action**: Write all files under `integration_tests/`:
- `environment.md`
- `test_data.md`
- `functional_tests.md`
- `non_functional_tests.md`
- `traceability_matrix.md`

**BLOCKING**: Present test coverage summary (from traceability_matrix.md) to user. Do NOT proceed until confirmed.

Capture any new questions, findings, or insights that arise during test specification — these feed forward into Steps 2 and 3.

---

### Step 2: Solution Analysis

**Role**: Professional software architect
**Goal**: Produce `architecture.md` and `system-flows.md` from the solution draft
**Constraints**: No code, no component-level detail yet; focus on system-level view

1. Read all input files thoroughly
2. Incorporate findings, questions, and insights discovered during Step 1 (integration tests)
3. Research unknown or questionable topics via internet; ask user about ambiguities
4. Document architecture using `templates/architecture.md` as structure
5. Document system flows using `templates/system-flows.md` as structure

**Self-verification**:
- [ ] Architecture covers all capabilities mentioned in solution.md
- [ ] System flows cover all main user/system interactions
- [ ] No contradictions with problem.md or restrictions.md
- [ ] Technology choices are justified
- [ ] Integration test findings are reflected in architecture decisions

**Save action**: Write `architecture.md` and `system-flows.md`

**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.

---

### Step 3: Component Decomposition

**Role**: Professional software architect
**Goal**: Decompose the architecture into components with detailed specs
**Constraints**: No code; only names, interfaces, inputs/outputs. Follow SRP strictly.

1. Identify components from the architecture; think about separation, reusability, and communication patterns
2. Use integration test scenarios from Step 1 to validate component boundaries
3. If additional components are needed (data preparation, shared helpers), create them
4. For each component, write a spec using `templates/component-spec.md` as structure
5. Generate diagrams:
   - draw.io component diagram showing relations (minimize line intersections, group semantically coherent components, place external users near their components)
   - Mermaid flowchart per main control flow
6. Components can share and reuse common logic, same for multiple components. Hence for such occurences common-helpers folder is specified.

**Self-verification**:
- [ ] Each component has a single, clear responsibility
- [ ] No functionality is spread across multiple components
- [ ] All inter-component interfaces are defined (who calls whom, with what)
- [ ] Component dependency graph has no circular dependencies
- [ ] All components from architecture.md are accounted for
- [ ] Every integration test scenario can be traced through component interactions

**Save action**: Write:
 - each component `components/[##]_[name]/description.md`
 - common helper `common-helpers/[##]_helper_[name].md`
 - diagrams `diagrams/`

**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms.

---

### Step 4: Architecture Review & Risk Assessment

**Role**: Professional software architect and analyst
**Goal**: Validate all artifacts for consistency, then identify and mitigate risks
**Constraints**: This is a review step — fix problems found, do not add new features

#### 4a. Evaluator Pass (re-read ALL artifacts)

Review checklist:
- [ ] All components follow Single Responsibility Principle
- [ ] All components follow dumb code / smart data principle
- [ ] Inter-component interfaces are consistent (caller's output matches callee's input)
- [ ] No circular dependencies in the dependency graph
- [ ] No missing interactions between components
- [ ] No over-engineering — is there a simpler decomposition?
- [ ] Security considerations addressed in component design
- [ ] Performance bottlenecks identified
- [ ] API contracts are consistent across components

Fix any issues found before proceeding to risk identification.

#### 4b. Risk Identification

1. Identify technical and project risks
2. Assess probability and impact using `templates/risk-register.md`
3. Define mitigation strategies
4. Apply mitigations to architecture, flows, and component documents where applicable

**Self-verification**:
- [ ] Every High/Critical risk has a concrete mitigation strategy
- [ ] Mitigations are reflected in the relevant component or architecture docs
- [ ] No new risks introduced by the mitigations themselves

**Save action**: Write `risk_mitigations.md`

**BLOCKING**: Present risk summary to user. Ask whether assessment is sufficient.

**Iterative**: If user requests another round, repeat Step 4 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms.

---

### Step 5: Test Specifications

**Role**: Professional Quality Assurance Engineer

**Goal**: Write test specs for each component achieving minimum 75% acceptance criteria coverage

**Constraints**: Test specs only — no test code. Each test must trace to an acceptance criterion.

1. For each component, write tests using `templates/test-spec.md` as structure
2. Cover all 4 types: integration, performance, security, acceptance
3. Include test data management (setup, teardown, isolation)
4. Verify traceability: every acceptance criterion from `acceptance_criteria.md` must be covered by at least one test

**Self-verification**:
- [ ] Every acceptance criterion has at least one test covering it
- [ ] Test inputs are realistic and well-defined
- [ ] Expected results are specific and measurable
- [ ] No component is left without tests

**Save action**: Write each `components/[##]_[name]/tests.md`

---

### Step 6: Jira Epics

**Role**: Professional product manager

**Goal**: Create Jira epics from components, ordered by dependency

**Constraints**: Be concise — fewer words with the same meaning is better

1. **Create "Bootstrap & Initial Structure" epic first** — this epic will parent the `01_initial_structure` task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
2. Generate Jira Epics for each component using Jira MCP, structured per `templates/epic-spec.md`
3. Order epics by dependency (Bootstrap epic is always first, then components based on their dependency graph)
4. Include effort estimation per epic (T-shirt size or story points range)
5. Ensure each epic has clear acceptance criteria cross-referenced with component specs
6. Generate updated draw.io diagram showing component-to-epic mapping

**Self-verification**:
- [ ] "Bootstrap & Initial Structure" epic exists and is first in order
- [ ] "Integration Tests" epic exists
- [ ] Every component maps to exactly one epic
- [ ] Dependency order is respected (no epic depends on a later one)
- [ ] Acceptance criteria are measurable
- [ ] Effort estimates are realistic

7. **Create "Integration Tests" epic** — this epic will parent the integration test tasks created by the `/decompose` skill. It covers implementing the test scenarios defined in `integration_tests/`.

**Save action**: Epics created in Jira via MCP

---

## Quality Checklist (before FINAL_report.md)

Before writing the final report, verify ALL of the following:

### Integration Tests
- [ ] Every acceptance criterion is covered in traceability_matrix.md
- [ ] Every restriction is verified by at least one test
- [ ] Positive and negative scenarios are balanced
- [ ] Docker environment is self-contained
- [ ] Consumer app treats main system as black box
- [ ] CI/CD integration and reporting defined

### Architecture
- [ ] Covers all capabilities from solution.md
- [ ] Technology choices are justified
- [ ] Deployment model is defined
- [ ] Integration test findings are reflected in architecture decisions

### Components
- [ ] Every component follows SRP
- [ ] No circular dependencies
- [ ] All inter-component interfaces are defined and consistent
- [ ] No orphan components (unused by any flow)
- [ ] Every integration test scenario can be traced through component interactions

### Risks
- [ ] All High/Critical risks have mitigations
- [ ] Mitigations are reflected in component/architecture docs
- [ ] User has confirmed risk assessment is sufficient

### Tests
- [ ] Every acceptance criterion is covered by at least one test
- [ ] All 4 test types are represented per component (where applicable)
- [ ] Test data management is defined

### Epics
- [ ] "Bootstrap & Initial Structure" epic exists
- [ ] "Integration Tests" epic exists
- [ ] Every component maps to an epic
- [ ] Dependency order is correct
- [ ] Acceptance criteria are measurable

**Save action**: Write `FINAL_report.md` using `templates/final-report.md` as structure

## 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 integration 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 Method)                │
├────────────────────────────────────────────────────────────────┤
│ PREREQ 1: Data Gate (BLOCKING)                                 │
│   → verify AC, restrictions, input_data exist — STOP if not    │
│ PREREQ 2: Finalize solution draft                              │
│   → rename highest solution_draft##.md to solution.md          │
│ PREREQ 3: Workspace setup                                      │
│   → create PLANS_DIR/ if needed                                │
│                                                                │
│ 1. Integration Tests  → integration_tests/ (5 files)           │
│    [BLOCKING: user confirms test coverage]                     │
│ 2. Solution Analysis  → architecture.md, system-flows.md       │
│    [BLOCKING: user confirms architecture]                      │
│ 3. Component Decompose → components/[##]_[name]/description    │
│    [BLOCKING: user confirms decomposition]                     │
│ 4. Review & Risk      → risk_mitigations.md                    │
│    [BLOCKING: user confirms risks, iterative]                  │
│ 5. Test Specifications → components/[##]_[name]/tests.md       │
│ 6. Jira Epics         → Jira via MCP                           │
│    ─────────────────────────────────────────────────           │
│    Quality Checklist → FINAL_report.md                         │
├────────────────────────────────────────────────────────────────┤
│ Principles: SRP · Dumb code/smart data · Save immediately      │
│             Ask don't assume · Plan don't code                 │
└────────────────────────────────────────────────────────────────┘
```