Oleksandr Bezdieniezhnykh
06b47c17c3
- Updated the coding rule descriptions to emphasize readability, meaningful comments, and test verification. - Revised guidelines to clarify the importance of avoiding boilerplate while maintaining readability. - Enhanced the testing rules to set a minimum coverage threshold of 75% for business logic and specified criteria for test scenarios. - Introduced a mechanism for handling skipped tests, categorizing them as legitimate or illegitimate, and outlined resolution steps. These changes aim to improve code quality, maintainability, and testing effectiveness.
7.1 KiB
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 |
|
true |
Solution Planning
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
- 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. 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.
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: 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
- 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 75% | 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. 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 │
└────────────────────────────────────────────────────────────────┘