azaion/annotations
1
0
Fork 0
mirror of https://github.com/azaion/annotations.git synced 2026-04-22 11:36:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync .cursor from detections

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-04-12 05:05:09 +03:00
parent 587b0e3c2d
commit d818daacd1
116 changed files with 10075 additions and 4577 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/skills/plan/SKILL.md
+55 -293
View File
@@ -1,19 +1,21 @@
---
name: plan
description: |
Decompose a solution into architecture, system flows, components, tests, and Jira epics.
Systematic 5-step planning workflow with BLOCKING gates, self-verification, and structured artifact management.
Supports project mode (_docs/ + _docs/02_plans/ structure) and standalone mode (@file.md).
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, system flows, components, tests, and Jira epics through a systematic 5-step workflow.
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
@@ -25,329 +27,83 @@ Decompose a problem and solution into architecture, system flows, components, te
## Context Resolution
Determine the operating mode based on invocation before any other logic runs.
Fixed paths — no mode detection needed:
**Project mode** (no explicit input file provided):
- PROBLEM_FILE: `_docs/00_problem/problem.md`
- SOLUTION_FILE: `_docs/01_solution/solution.md`
- PLANS_DIR: `_docs/02_plans/`
- All existing guardrails apply as-is.
- DOCUMENT_DIR: `_docs/02_document/`
**Standalone mode** (explicit input file provided, e.g. `/plan @some_doc.md`):
- INPUT_FILE: the provided file (treated as combined problem + solution context)
- Derive `<topic>` from the input filename (without extension)
- PLANS_DIR: `_standalone/<topic>/plans/`
- Guardrails relaxed: only INPUT_FILE must exist and be non-empty
- `acceptance_criteria.md` and `restrictions.md` are optional — warn if absent
Announce the resolved paths to the user before proceeding.
Announce the detected mode and resolved paths to the user before proceeding.
## Input Specification
### Required Files
**Project mode:**
## Required Files
| File | Purpose |
|------|---------|
| PROBLEM_FILE (`_docs/00_problem/problem.md`) | Problem description and context |
| `_docs/00_problem/input_data/` | Reference data examples (if available) |
| `_docs/00_problem/restrictions.md` | Constraints and limitations (if available) |
| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria (if available) |
| SOLUTION_FILE (`_docs/01_solution/solution.md`) | Solution draft to decompose |
| `_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 |
**Standalone mode:**
## Prerequisites
| File | Purpose |
|------|---------|
| INPUT_FILE (the provided file) | Combined problem + solution context |
### Prerequisite Checks (BLOCKING)
**Project mode:**
1. PROBLEM_FILE exists and is non-empty — **STOP if missing**
2. SOLUTION_FILE exists and is non-empty — **STOP if missing**
3. Create PLANS_DIR if it does not exist
4. If `PLANS_DIR/<topic>/` already exists, ask user: **resume from last checkpoint or start fresh?**
**Standalone mode:**
1. INPUT_FILE exists and is non-empty — **STOP if missing**
2. Warn if no `restrictions.md` or `acceptance_criteria.md` provided alongside INPUT_FILE
3. Create PLANS_DIR if it does not exist
4. If `PLANS_DIR/<topic>/` already exists, ask user: **resume from last checkpoint or start fresh?**
Read and follow `steps/00_prerequisites.md`. All three prerequisite checks are **BLOCKING** — do not start the workflow until they pass.
## Artifact Management
### Directory Structure
At the start of planning, create a topic-named working directory under PLANS_DIR:
```
PLANS_DIR/<topic>/
├── 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]/
│ └── ...
├── e2e_test_infrastructure.md
├── diagrams/
│ ├── components.drawio
│ └── flows/
│ ├── flow_[name].md (Mermaid)
│ └── ...
└── FINAL_report.md
```
### Save Timing
| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Architecture analysis complete | `architecture.md` |
| Step 1 | System flows documented | `system-flows.md` |
| Step 2 | Each component analyzed | `components/[##]_[name]/description.md` |
| Step 2 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
| Step 2 | Diagrams generated | `diagrams/` |
| Step 3 | Risk assessment complete | `risk_mitigations.md` |
| Step 4 | Tests written per component | `components/[##]_[name]/tests.md` |
| Step 4b | E2E test infrastructure spec | `e2e_test_infrastructure.md` |
| Step 5 | 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/<topic>/` 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
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 5, including 4b). Update status as each step completes.
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: Solution Analysis
### Step 1: Blackbox Tests
**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
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.
1. Read all input files thoroughly
2. Research unknown or questionable topics via internet; ask user about ambiguities
3. Document architecture using `templates/architecture.md` as structure
4. 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
**Save action**: Write `architecture.md` and `system-flows.md`
**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.
Capture any new questions, findings, or insights that arise during test specification — these feed forward into Steps 2 and 3.
---
### Step 2: Component Decomposition
### Step 2: Solution Analysis
**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. If additional components are needed (data preparation, shared helpers), create them
3. For each component, write a spec using `templates/component-spec.md` as structure
4. 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
5. 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
**Save action**: Write:
- each component `components/[##]_[name]/description.md`
- comomon helper `common-helpers/[##]_helper_[name].md`
- diagrams `diagrams/`
**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms.
Read and follow `steps/02_solution-analysis.md`.
---
### Step 3: Architecture Review & Risk Assessment
### Step 3: Component Decomposition
**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
#### 3a. 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.
#### 3b. 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 3 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms.
Read and follow `steps/03_component-decomposition.md`.
---
### Step 4: Test Specifications
### Step 4: Architecture Review & Risk Assessment
**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`
Read and follow `steps/04_review-risk.md`.
---
### Step 4b: E2E Black-Box Test Infrastructure
### Step 5: Test Specifications
**Role**: Professional Quality Assurance Engineer
**Goal**: Specify a separate consumer application and Docker environment for black-box end-to-end testing of the main system
**Constraints**: Spec only — no test code. Consumer must treat the main system as a black box (no internal imports, no direct DB access).
1. Define Docker environment: services (system under test, test DB, consumer app, dependencies), networks, volumes
2. Specify consumer application: tech stack, entry point, communication interfaces with the main system
3. Define E2E test scenarios from acceptance criteria — focus on critical end-to-end use cases that cross component boundaries
4. Specify test data management: seed data, isolation strategy, external dependency mocks
5. Define CI/CD integration: when to run, gate behavior, timeout
6. Define reporting format (CSV: test ID, name, execution time, result, error message)
Use `templates/e2e-test-infrastructure.md` as structure.
**Self-verification**:
- [ ] Critical acceptance criteria are covered by at least one E2E scenario
- [ ] 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
**Save action**: Write `e2e_test_infrastructure.md`
Read and follow `steps/05_test-specifications.md`.
---
### Step 5: Jira Epics
### Step 6: Work Item 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. Generate Jira Epics from components using Jira MCP, structured per `templates/epic-spec.md`
2. Order epics by dependency (which must be done first)
3. Include effort estimation per epic (T-shirt size or story points range)
4. Ensure each epic has clear acceptance criteria cross-referenced with component specs
5. Generate updated draw.io diagram showing component-to-epic mapping
**Self-verification**:
- [ ] 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
**Save action**: Epics created in Jira via MCP
Read and follow `steps/06_work-item-epics.md`.
---
## Quality Checklist (before FINAL_report.md)
### Final: Quality Checklist
Before writing the final report, verify ALL of the following:
### Architecture
- [ ] Covers all capabilities from solution.md
- [ ] Technology choices are justified
- [ ] Deployment model is defined
### Components
- [ ] Every component follows SRP
- [ ] No circular dependencies
- [ ] All inter-component interfaces are defined and consistent
- [ ] No orphan components (unused by any flow)
### 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
### E2E Test Infrastructure
- [ ] Critical use cases covered by E2E scenarios
- [ ] Docker environment is self-contained
- [ ] Consumer app treats main system as black box
- [ ] CI/CD integration and reporting defined
### Epics
- [ ] 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
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
@@ -355,13 +111,15 @@ Before writing the final report, verify ALL of the following:
- **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 |
| Missing acceptance criteria | 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 |
@@ -372,22 +130,26 @@ Before writing the final report, verify ALL of the following:
```
┌────────────────────────────────────────────────────────────────┐
│ Solution Planning (5-Step Method) │
│ Solution Planning (6-Step + Final) │
├────────────────────────────────────────────────────────────────┤
│ CONTEXT: Resolve mode (project vs standalone) + set paths │
│ 1. Solution Analysis → architecture.md, system-flows.md │
│ 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] │
│ 2. Component Decompose → components/[##]_[name]/description │
│ [BLOCKING: user confirms decomposition] │
│ 3. Review & Risk Assess → risk_mitigations.md │
│ [BLOCKING: user confirms risks, iterative] │
│ 4. Test Specifications → components/[##]_[name]/tests.md │
│ 4b.E2E Test Infra → e2e_test_infrastructure.md │
│ 5. Jira Epics → Jira via MCP │
│ 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 │
│ ───────────────────────────────────────────────── │
│ Quality Checklist → FINAL_report.md │
│ Final: Quality Checklist → FINAL_report.md │
├────────────────────────────────────────────────────────────────┤
│ Principles: SRP · Dumb code/smart data · Save immediately │
│ Ask don't assume · Plan don't code │
│ Principles: Single Responsibility · Dumb code, smart data │
│ Save immediately · Ask don't assume │
│ Plan don't code │
└────────────────────────────────────────────────────────────────┘
```