mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 07:11:13 +00:00
Oleksandr Bezdieniezhnykh
6044a33197
Bundled hygiene commit before cycle-3 /implement (AZ-776, AZ-777). Mixes two concerns by user choice (autodev option B): - Cycle-3 autodev artifacts not yet committed by Step 9 (new-task): task specs for AZ-776 / AZ-777 under _docs/02_tasks/todo/ and the updated _docs/02_tasks/_dependencies_table.md. - Accumulated skill / rule tooling maintenance under .cursor/ (skills: autodev, code-review, decompose, deploy, implement, new-task, plan, refactor, retrospective, test-spec; rules: coderule, cursor-meta, meta-rule, testing; new release skill scaffolding). - Autodev bootstrap state: _docs/_autodev_state.md (step 10 in_progress) and _docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md (replay timestamp refreshed; gtsam 4.2 still numpy<2-only). Co-authored-by: Cursor <cursoragent@cursor.com>
171 lines
9.0 KiB
Markdown
171 lines
9.0 KiB
Markdown
---
|
||
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 │
|
||
└────────────────────────────────────────────────────────────────┘
|
||
```
|