mirror of
https://github.com/azaion/ai-training.git
synced 2026-04-22 09:16:36 +00:00
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.
156 lines
7.1 KiB
Markdown
156 lines
7.1 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, 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 │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
```
|