150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
---
|
|
name: finalize-architecture
|
|
description: "Final completeness check and format validation for the architecture document. The Architect pipeline's final step before handoff to Planner."
|
|
---
|
|
|
|
This skill performs a final completeness check and format validation on the architecture document after challenge and revision.
|
|
|
|
**Announce at start:** "I'm using the finalize-architecture skill to perform the final completeness check on the architecture document."
|
|
|
|
## Primary Input
|
|
|
|
- `docs/architecture/{feature}.md`
|
|
|
|
## Primary Output (STRICT PATH)
|
|
|
|
- Final `docs/architecture/{feature}.md`
|
|
|
|
This is the **only** file artifact in the Architect pipeline. Finalization results are applied directly to this file.
|
|
|
|
## Process
|
|
|
|
You MUST complete these steps in order:
|
|
|
|
### Step 1: Section Completeness Check
|
|
|
|
Verify all 18 required sections are present and substantive (or explicitly marked N/A with reason):
|
|
|
|
1. Overview
|
|
2. System Architecture
|
|
3. Service Boundaries
|
|
4. Data Flow
|
|
5. Database Schema
|
|
6. API Contract
|
|
7. Async / Queue Design
|
|
8. Consistency Model
|
|
9. Error Model
|
|
10. Security Boundaries
|
|
11. Integration Boundaries
|
|
12. Observability
|
|
13. Scaling Strategy
|
|
14. Non-Functional Requirements
|
|
15. Mermaid Diagrams
|
|
16. ADR
|
|
17. Risks
|
|
18. Open Questions
|
|
|
|
For each missing or empty section, add a placeholder with `N/A — [reason]` or flag it as a gap that must be filled.
|
|
|
|
### Step 2: Mermaid Diagram Verification
|
|
|
|
Verify the document contains at minimum:
|
|
- **1 System Architecture Diagram** — showing all services, databases, queues, and external integrations
|
|
- **1 Sequence Diagram** — showing the primary happy-path interaction flow
|
|
- **1 Data Flow Diagram** — showing how data moves through the system
|
|
|
|
For each diagram, verify:
|
|
- Mermaid syntax is valid
|
|
- All components referenced in the architecture are present in the diagram
|
|
- No orphan components exist in diagrams that are not described elsewhere
|
|
|
|
### Step 3: Database Schema Verification
|
|
|
|
Verify the Database Schema section contains:
|
|
- All tables with field names, types, constraints, and defaults
|
|
- Indexes with justification based on query patterns
|
|
- Partition keys where applicable
|
|
- Relationships (foreign keys, references)
|
|
- Denormalization strategy where applicable
|
|
- Migration strategy notes
|
|
|
|
### Step 4: API Contract Verification
|
|
|
|
Verify the API Contract section contains:
|
|
- All endpoints with method, path, request schema, response schema
|
|
- Error codes and error response schemas
|
|
- Idempotency requirements per endpoint (where applicable)
|
|
- Pagination and filtering (where applicable)
|
|
- Authentication requirements
|
|
|
|
### Step 5: ADR Verification
|
|
|
|
Verify the ADR section contains at minimum 1 ADR with:
|
|
- ADR number and title
|
|
- Context
|
|
- Decision
|
|
- Consequences
|
|
- Alternatives considered
|
|
|
|
### Step 6: Traceability Verification
|
|
|
|
Verify:
|
|
- Every API endpoint traces to a PRD functional requirement
|
|
- Every DB table traces to a data requirement
|
|
- Every service boundary traces to a domain responsibility
|
|
- Every async flow traces to a PRD requirement
|
|
- Every security boundary traces to a requirement
|
|
- Every integration boundary traces to an external system requirement
|
|
|
|
### Step 7: Format Verification
|
|
|
|
Verify:
|
|
- The document follows the exact section ordering from the template
|
|
- Section headings use proper markdown hierarchy
|
|
- Mermaid code blocks use ```mermaid syntax
|
|
- Tables use proper markdown table syntax
|
|
- No external files are referenced (all content is within the single document)
|
|
|
|
### Step 8: Architecture Review Gate
|
|
|
|
Verify the Architecture Review section from `challenge-architecture`:
|
|
- Gate decision is either PASS or CONDITIONAL PASS
|
|
- All identified issues have been addressed
|
|
- No unresolved blockers remain
|
|
|
|
## Finalization Checklist
|
|
|
|
- [ ] All 18 required sections present and substantive (or N/A with reason)
|
|
- [ ] At least 3 Mermaid diagrams present (system, sequence, data flow)
|
|
- [ ] Database Schema has complete table definitions
|
|
- [ ] API Contract has complete endpoint specifications
|
|
- [ ] At least 1 ADR present with full format
|
|
- [ ] All elements trace to PRD requirements
|
|
- [ ] Architecture Review gate is PASS or CONDITIONAL PASS
|
|
- [ ] Document format follows template ordering
|
|
- [ ] No external file references (all content is inline)
|
|
- [ ] Risks section is populated
|
|
- [ ] Open Questions section is populated (or explicitly states "None")
|
|
|
|
## Guardrails
|
|
|
|
This is a pure validation and formatting skill.
|
|
|
|
Do:
|
|
- Verify completeness of all 18 sections
|
|
- Validate Mermaid diagram syntax and coverage
|
|
- Validate API contract completeness
|
|
- Validate database schema completeness
|
|
- Validate ADR format
|
|
- Validate traceability
|
|
- Fix formatting issues directly in `docs/architecture/{feature}.md`
|
|
|
|
Do not:
|
|
- Design new architecture
|
|
- Change architectural decisions
|
|
- Add significant new content that wasn't validated in challenge-architecture
|
|
- Produce any file artifact other than `docs/architecture/{feature}.md`
|
|
|
|
## Transition
|
|
|
|
After finalization is complete and all checks pass, the architecture document is ready for handoff to the Planner. The Planner reads only `docs/architecture/{feature}.md`. |