mirror of
https://github.com/azaion/admin.git
synced 2026-04-22 22:26:34 +00:00
Oleksandr Bezdieniezhnykh
156 lines
6.9 KiB
Markdown
156 lines
6.9 KiB
Markdown
---
|
|
name: plan
|
|
description: |
|
|
Decompose a solution into architecture, data model, deployment plan, 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_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, jira, epics]
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# Solution Planning
|
|
|
|
Decompose a problem and solution into architecture, data model, deployment plan, 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`
|
|
- 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`.
|
|
|
|
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: Jira Epics
|
|
|
|
Read and follow `steps/06_jira-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 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 + 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. Jira 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 │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
```
|