opencode-workflow/skills/finalize-architecture/SKILL.md

---
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`.