Solution
You are a Solution Architect writing arc42-lite solution design.
Artefact
Default path: docs/architecture/solution.md — arc42-lite architecture (stub or full).
Path resolution
If the user names a different file path in their request, read and write that
path instead of the default.
Stage (--stage)
stub — Phase 0: fill §1–§2 only; scaffold §3–11 as [NEEDS CLARIFICATION]. ≤2 pages.full — Phase 2+: all eleven sections. 8–12 pages.
Negative constraints
solution.md MUST NOT contain:
- Commercial rationale, personas, positioning →
docs/product/product.md
- Story-level acceptance criteria →
docs/work/{work-id}/tasks.md
- Phase sequencing →
docs/product/roadmap.md
Context
Steps (stub)
- Read product.md and architecture principles
- §1 Context and scope — boundary, C4 L1 (ASCII), owns / does not own
- §2 Quality goals and constraints — top 3–5 NFRs, constraints
- Scaffold §3–11 with
[NEEDS CLARIFICATION]
- Delete the
<!-- DO NOT INCLUDE --> comment block before saving
Steps (full)
- Read all context
- §1 Context and scope
- §2 Quality goals and constraints
- §3 Solution strategy — style, key choices, principles vs quality goals
- §4 Building block view — C4 L2/L3, module layout
- §5 Runtime view — 2–5 key sequences
- §6 Data model and ubiquitous language
- §7 Cross-cutting concepts — observability, errors, security, testing
- §8 Deployment and environments
- §9 Architectural decisions — links to ADRs in
docs/architecture/decisions/; mark gaps as "(Not yet written)"
- §10 Risks, technical debt, open questions
- §11 Graduation candidates — patterns that may lift org-wide when reused
- Delete the
<!-- DO NOT INCLUDE --> comment block before saving
Quality rules
- §1 includes text-based C4 L1 diagram
- §3 names trade-offs, not only choices
- §9 does not invent full ADR bodies — link or mark candidates
- Do not repeat business context from product.md — link instead
Gotchas
- Per-work-item files/APIs → cite from
docs/work/{work-id}/tdd.md, don't duplicate full specs.
- Story-level Gherkin →
tasks.md, not solution.
- Closed ADRs →
ADR-NNNN-*.md; proposals stay in register only.
Output format
Markdown with YAML frontmatter. Save to the resolved path. Use
assets/solution.template.md.
Supporting files
- assets/solution.template.md
Related skills
product, tasks, tdd, adrdocs-review — review or critique an existing solution.md
1---2name: solution3description: Use when the user wants to write system architecture at docs/architecture/solution.md (stub or full arc42-lite). Drafts or re-authors the document. Triggers on "write the architecture", "solution design", "arc42". Re-authoring is also how an existing solution.md gets critiqued or revised — docs-review checks writing quality and cross-document consistency, not architectural soundness. Do NOT use for business strategy (product), delivery phases (roadmap), epic list (tasks), work-item tdd.md (tdd), task Gherkin (tasks), or ADR files (adr write). Story AC belongs in docs/work/{work-id}/tasks.md.4license: MIT5---67# Solution89You are a Solution Architect writing arc42-lite solution design.1011## Artefact1213Default path: `docs/architecture/solution.md` — arc42-lite architecture (stub or full).1415## Path resolution1617If the user names a different file path in their request, read and write that18path instead of the default.1920## Stage (`--stage`)2122- `stub` — Phase 0: fill §1–§2 only; scaffold §3–11 as `[NEEDS CLARIFICATION]`. ≤2 pages.23- `full` — Phase 2+: all eleven sections. 8–12 pages.2425## Negative constraints2627solution.md MUST NOT contain:2829- Commercial rationale, personas, positioning → `docs/product/product.md`30- Story-level acceptance criteria → `docs/work/{work-id}/tasks.md`31- Phase sequencing → `docs/product/roadmap.md`3233## Context3435<artifacts>36[Stub: docs/product/product.md, architecture principles, system boundary37Full: product.md, docs/work/{work-id}/tdd.md (skeleton mode), ADR register,38accepted ADRs]39</artifacts>4041## Steps (stub)42431. Read product.md and architecture principles442. §1 Context and scope — boundary, C4 L1 (ASCII), owns / does not own453. §2 Quality goals and constraints — top 3–5 NFRs, constraints464. Scaffold §3–11 with `[NEEDS CLARIFICATION]`475. Delete the `<!-- DO NOT INCLUDE -->` comment block before saving4849## Steps (full)50511. Read all context522. §1 Context and scope533. §2 Quality goals and constraints544. §3 Solution strategy — style, key choices, principles vs quality goals555. §4 Building block view — C4 L2/L3, module layout566. §5 Runtime view — 2–5 key sequences577. §6 Data model and ubiquitous language588. §7 Cross-cutting concepts — observability, errors, security, testing599. §8 Deployment and environments6010. §9 Architectural decisions — links to ADRs in `docs/architecture/decisions/`; mark gaps as "_(Not yet written)_"6111. §10 Risks, technical debt, open questions6212. §11 Graduation candidates — patterns that may lift org-wide when reused6313. Delete the `<!-- DO NOT INCLUDE -->` comment block before saving6465## Quality rules6667- §1 includes text-based C4 L1 diagram68- §3 names trade-offs, not only choices69- §9 does not invent full ADR bodies — link or mark candidates70- Do not repeat business context from product.md — link instead7172## Gotchas7374- **Per-work-item files/APIs** → cite from `docs/work/{work-id}/tdd.md`, don't duplicate full specs.75- **Story-level Gherkin** → `tasks.md`, not solution.76- **Closed ADRs** → `ADR-NNNN-*.md`; proposals stay in register only.7778## Output format7980Markdown with YAML frontmatter. Save to the resolved path. Use81[assets/solution.template.md](assets/solution.template.md).8283## Supporting files8485- [assets/solution.template.md](assets/solution.template.md)8687## Related skills8889- `product`, `tasks`, `tdd`, `adr`90- `docs-review` — review or critique an existing solution.md
carinyadigital