Add detailed file index and enhance skill documentation for autopilot, decompose, deploy, plan, and research skills. Introduce tests-only mode in decompose skill, clarify required files for deploy and plan skills, and improve prerequisite checks across skills for better user guidance and workflow efficiency.

2026-04-22 22:56:31 +00:00 · 2026-03-22 16:15:49 +02:00
parent 60ebe686ff
commit 3165a88f0b
60 changed files with 6324 additions and 1550 deletions
@@ -0,0 +1,27 @@
+## Prerequisite Checks (BLOCKING)
+
+Run sequentially before any planning step:
+
+### Prereq 1: Data Gate
+
+1. `_docs/00_problem/acceptance_criteria.md` exists and is non-empty — **STOP if missing**
+2. `_docs/00_problem/restrictions.md` exists and is non-empty — **STOP if missing**
+3. `_docs/00_problem/input_data/` exists and contains at least one data file — **STOP if missing**
+4. `_docs/00_problem/problem.md` exists and is non-empty — **STOP if missing**
+
+All four are mandatory. If any is missing or empty, STOP and ask the user to provide them. If the user cannot provide the required data, planning cannot proceed — just stop.
+
+### Prereq 2: Finalize Solution Draft
+
+Only runs after the Data Gate passes:
+
+1. Scan `_docs/01_solution/` for files matching `solution_draft*.md`
+2. Identify the highest-numbered draft (e.g. `solution_draft06.md`)
+3. **Rename** it to `_docs/01_solution/solution.md`
+4. If `solution.md` already exists, ask the user whether to overwrite or keep existing
+5. Verify `solution.md` is non-empty — **STOP if missing or empty**
+
+### Prereq 3: Workspace Setup
+
+1. Create DOCUMENT_DIR if it does not exist
+2. If DOCUMENT_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**
@@ -0,0 +1,81 @@
+## Artifact Management
+
+### Directory Structure
+
+All artifacts are written directly under DOCUMENT_DIR:
+
+```
+DOCUMENT_DIR/
+├── integration_tests/
+│   ├── environment.md
+│   ├── test_data.md
+│   ├── functional_tests.md
+│   ├── non_functional_tests.md
+│   └── traceability_matrix.md
+├── architecture.md
+├── system-flows.md
+├── data_model.md
+├── deployment/
+│   ├── containerization.md
+│   ├── ci_cd_pipeline.md
+│   ├── environment_strategy.md
+│   ├── observability.md
+│   └── deployment_procedures.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]/
+│   └── ...
+├── diagrams/
+│   ├── components.drawio
+│   └── flows/
+│       ├── flow_[name].md          (Mermaid)
+│       └── ...
+└── FINAL_report.md
+```
+
+### Save Timing
+
+| Step | Save immediately after | Filename |
+|------|------------------------|----------|
+| Step 1 | Integration test environment spec | `integration_tests/environment.md` |
+| Step 1 | Integration test data spec | `integration_tests/test_data.md` |
+| Step 1 | Integration functional tests | `integration_tests/functional_tests.md` |
+| Step 1 | Integration non-functional tests | `integration_tests/non_functional_tests.md` |
+| Step 1 | Integration traceability matrix | `integration_tests/traceability_matrix.md` |
+| Step 2 | Architecture analysis complete | `architecture.md` |
+| Step 2 | System flows documented | `system-flows.md` |
+| Step 2 | Data model documented | `data_model.md` |
+| Step 2 | Deployment plan complete | `deployment/` (5 files) |
+| Step 3 | Each component analyzed | `components/[##]_[name]/description.md` |
+| Step 3 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
+| Step 3 | Diagrams generated | `diagrams/` |
+| Step 4 | Risk assessment complete | `risk_mitigations.md` |
+| Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
+| Step 6 | 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 DOCUMENT_DIR 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
@@ -0,0 +1,74 @@
+## Step 2: Solution Analysis
+
+**Role**: Professional software architect
+**Goal**: Produce `architecture.md`, `system-flows.md`, `data_model.md`, and `deployment/` from the solution draft
+**Constraints**: No code, no component-level detail yet; focus on system-level view
+
+### Phase 2a: Architecture & Flows
+
+1. Read all input files thoroughly
+2. Incorporate findings, questions, and insights discovered during Step 1 (integration tests)
+3. Research unknown or questionable topics via internet; ask user about ambiguities
+4. Document architecture using `templates/architecture.md` as structure
+5. 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
+- [ ] Integration test findings are reflected in architecture decisions
+
+**Save action**: Write `architecture.md` and `system-flows.md`
+
+**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.
+
+### Phase 2b: Data Model
+
+**Role**: Professional software architect
+**Goal**: Produce a detailed data model document covering entities, relationships, and migration strategy
+
+1. Extract core entities from architecture.md and solution.md
+2. Define entity attributes, types, and constraints
+3. Define relationships between entities (Mermaid ERD)
+4. Define migration strategy: versioning tool (EF Core migrations / Alembic / sql-migrate), reversibility requirement, naming convention
+5. Define seed data requirements per environment (dev, staging)
+6. Define backward compatibility approach for schema changes (additive-only by default)
+
+**Self-verification**:
+- [ ] Every entity mentioned in architecture.md is defined
+- [ ] Relationships are explicit with cardinality
+- [ ] Migration strategy specifies reversibility requirement
+- [ ] Seed data requirements defined
+- [ ] Backward compatibility approach documented
+
+**Save action**: Write `data_model.md`
+
+### Phase 2c: Deployment Planning
+
+**Role**: DevOps / Platform engineer
+**Goal**: Produce deployment plan covering containerization, CI/CD, environment strategy, observability, and deployment procedures
+
+Use the `/deploy` skill's templates as structure for each artifact:
+
+1. Read architecture.md and restrictions.md for infrastructure constraints
+2. Research Docker best practices for the project's tech stack
+3. Define containerization plan: Dockerfile per component, docker-compose for dev and tests
+4. Define CI/CD pipeline: stages, quality gates, caching, parallelization
+5. Define environment strategy: dev, staging, production with secrets management
+6. Define observability: structured logging, metrics, tracing, alerting
+7. Define deployment procedures: strategy, health checks, rollback, checklist
+
+**Self-verification**:
+- [ ] Every component has a Docker specification
+- [ ] CI/CD pipeline covers lint, test, security, build, deploy
+- [ ] Environment strategy covers dev, staging, production
+- [ ] Observability covers logging, metrics, tracing, alerting
+- [ ] Deployment procedures include rollback and health checks
+
+**Save action**: Write all 5 files under `deployment/`:
+- `containerization.md`
+- `ci_cd_pipeline.md`
+- `environment_strategy.md`
+- `observability.md`
+- `deployment_procedures.md`
@@ -0,0 +1,29 @@
+## Step 3: Component Decomposition
+
+**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. Use integration test scenarios from Step 1 to validate component boundaries
+3. If additional components are needed (data preparation, shared helpers), create them
+4. For each component, write a spec using `templates/component-spec.md` as structure
+5. 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
+6. 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
+- [ ] Every integration test scenario can be traced through component interactions
+
+**Save action**: Write:
+ - each component `components/[##]_[name]/description.md`
+ - common helper `common-helpers/[##]_helper_[name].md`
+ - diagrams `diagrams/`
+
+**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms.
@@ -0,0 +1,38 @@
+## Step 4: Architecture Review & Risk Assessment
+
+**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
+
+### 4a. 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.
+
+### 4b. 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 4 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms.
@@ -0,0 +1,20 @@
+## Step 5: Test Specifications
+
+**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`
@@ -0,0 +1,48 @@
+## Step 6: Jira Epics
+
+**Role**: Professional product manager
+
+**Goal**: Create Jira epics from components, ordered by dependency
+
+**Constraints**: Epic descriptions must be **comprehensive and self-contained** — a developer reading only the Jira epic should understand the full context without needing to open separate files.
+
+1. **Create "Bootstrap & Initial Structure" epic first** — this epic will parent the `01_initial_structure` task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
+2. Generate Jira Epics for each component using Jira MCP, structured per `templates/epic-spec.md`
+3. Order epics by dependency (Bootstrap epic is always first, then components based on their dependency graph)
+4. Include effort estimation per epic (T-shirt size or story points range)
+5. Ensure each epic has clear acceptance criteria cross-referenced with component specs
+6. Generate Mermaid diagrams showing component-to-epic mapping and component relationships
+
+**CRITICAL — Epic description richness requirements**:
+
+Each epic description in Jira MUST include ALL of the following sections with substantial content:
+- **System context**: where this component fits in the overall architecture (include Mermaid diagram showing this component's position and connections)
+- **Problem / Context**: what problem this component solves, why it exists, current pain points
+- **Scope**: detailed in-scope and out-of-scope lists
+- **Architecture notes**: relevant ADRs, technology choices, patterns used, key design decisions
+- **Interface specification**: full method signatures, input/output types, error types (from component description.md)
+- **Data flow**: how data enters and exits this component (include Mermaid sequence or flowchart diagram)
+- **Dependencies**: epic dependencies (with Jira IDs) and external dependencies (libraries, hardware, services)
+- **Acceptance criteria**: measurable criteria with specific thresholds (from component tests.md)
+- **Non-functional requirements**: latency, memory, throughput targets with failure thresholds
+- **Risks & mitigations**: relevant risks from risk_mitigations.md with concrete mitigation strategies
+- **Effort estimation**: T-shirt size and story points range
+- **Child issues**: planned task breakdown with complexity points
+- **Key constraints**: from restrictions.md that affect this component
+- **Testing strategy**: summary of test types and coverage from tests.md
+
+Do NOT create minimal epics with just a summary and short description. The Jira epic is the primary reference document for the implementation team.
+
+**Self-verification**:
+- [ ] "Bootstrap & Initial Structure" epic exists and is first in order
+- [ ] "Integration Tests" epic exists
+- [ ] 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
+- [ ] Every epic description includes architecture diagram, interface spec, data flow, risks, and NFRs
+- [ ] Epic descriptions are self-contained — readable without opening other files
+
+7. **Create "Integration Tests" epic** — this epic will parent the integration test tasks created by the `/decompose` skill. It covers implementing the test scenarios defined in `integration_tests/`.
+
+**Save action**: Epics created in Jira via MCP. Also saved locally in `epics.md` with Jira IDs.
@@ -0,0 +1,57 @@
+## Quality Checklist (before FINAL_report.md)
+
+Before writing the final report, verify ALL of the following:
+
+### Integration Tests
+- [ ] Every acceptance criterion is covered in traceability_matrix.md
+- [ ] Every restriction is verified by at least one test
+- [ ] Positive and negative scenarios are balanced
+- [ ] Docker environment is self-contained
+- [ ] Consumer app treats main system as black box
+- [ ] CI/CD integration and reporting defined
+
+### Architecture
+- [ ] Covers all capabilities from solution.md
+- [ ] Technology choices are justified
+- [ ] Deployment model is defined
+- [ ] Integration test findings are reflected in architecture decisions
+
+### Data Model
+- [ ] Every entity from architecture.md is defined
+- [ ] Relationships have explicit cardinality
+- [ ] Migration strategy with reversibility requirement
+- [ ] Seed data requirements defined
+- [ ] Backward compatibility approach documented
+
+### Deployment
+- [ ] Containerization plan covers all components
+- [ ] CI/CD pipeline includes lint, test, security, build, deploy stages
+- [ ] Environment strategy covers dev, staging, production
+- [ ] Observability covers logging, metrics, tracing, alerting
+- [ ] Deployment procedures include rollback and health checks
+
+### Components
+- [ ] Every component follows SRP
+- [ ] No circular dependencies
+- [ ] All inter-component interfaces are defined and consistent
+- [ ] No orphan components (unused by any flow)
+- [ ] Every integration test scenario can be traced through component interactions
+
+### 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
+
+### Epics
+- [ ] "Bootstrap & Initial Structure" epic exists
+- [ ] "Integration Tests" epic exists
+- [ ] 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