arc42-documentation

arc42 Documentation Authoring

Produce an arc42 architecture document that holds together across sections — not twelve chapters written in isolation.

When to use this skill

Use it when you are creating a new arc42 document, filling empty chapters, or auditing an existing one against the project's rules. The architecture-documentation contract names what the project means by architecture documentation (arc42; C4 via PlantUML; Nygard ADRs with a 3-point Pugh matrix; six-part Quality Attribute Scenarios). This skill is the how — the procedure and the cross-section rules arc42's own templates do not enforce. Load it on demand; it is not always-on.

If you are recovering documentation from existing code rather than authoring it forward, use the socratic-code-theory-recovery skill instead — its Phase 2 synthesizes an arc42 document and applies the same rules defined here.

Step 1 — Scaffold, do not restate

Scaffold the arc42 "with-help" template into the project's src/docs/ via docToolchain downloadTemplate. Each chapter's help text is its own structural spec; the process fills the help text and then replaces it. Do not paste a chapter skeleton from memory — let the template carry the structure so it stays current with arc42.

Step 2 — Diagrams

Every context, building-block, and runtime chapter carries at least one diagram. Diagrams are PlantUML, not Mermaid. Building blocks use C4 via PlantUML's bundled C4-PlantUML standard library — the !include <C4/...> stdlib form (angle brackets), never the remote https:// URL and never a vendored file copy. Diagrams are concrete components, not generic boxes.

Step 3 — Decisions (ADRs)

Decisions are ADRs in Nygard format with a 3-point Pugh matrix (-1 / 0 / +1).

• When the rationale is unconfirmed, set ADR Status to "Accepted (inferred)" and mark Pugh cells that need team judgement with ? rather than guessing a number.
• Each ADR's Consequences name the risks the decision creates, referencing the Chapter 11 risk IDs (R-NNN). A decision that creates a risk not yet in Chapter 11 either adds it there or records the consequence as explicitly accepted without a tracked risk.
• Conversely, every Chapter 8 crosscutting concept back-references the ADR that decided it.