Generating arc42

Generating arc42 Documentation

Overview

Generate an arc42 architecture-documentation base for a repository, derived from its source code, using Mermaid-only diagrams. Vendor-neutral: built on the open arc42 template, usable on any project including open-source.

Core principle: document only what the source supports. Generate as much as the code, config, and history evidence; leave a TODO: everywhere the answer can only come from a human. A flagged gap is better than a confident fabrication.

When to use

• "Generate / write / scaffold the arc42 docs for this repo."
• "Create the doc/architecture chapters for this service or library."
• Bootstrapping architecture documentation for an undocumented codebase.
• Refreshing/extending an existing arc42 base from current source.

Not for: editing one existing chapter's prose, or non-arc42 documentation.

Workflow

1. Read the conventions first. Read arc42-conventions.md (in this skill directory) IN FULL and follow it exactly — folder structure, chapter set, style, Mermaid colour code, and per-chapter guidance. It is the source of truth for how to write the docs.
2. Study the real repository. README, build/config files, manifests, CI, and the actual source folders. Derive components, external systems, actors, protocols, and runtime scenarios from what you can point to in the code.
3. Scale depth to the evidence. Rich codebase → full chapters; small library → the core chapters as short stubs (use the stub skeleton defined in arc42-conventions.md). Don't pad.
4. Write into doc/architecture/, wrapping each generated chapter body in <!-- arc42:generated --> / <!-- /arc42:generated --> markers. On a refresh, replace only what's inside those markers; treat any prose outside them — or any chapter that lacks them — as human-authored. Never overwrite it; report the conflict instead. Stamp the generation provenance into README.md (see the conventions).
5. Verify, then report. Run the Quick checklist in arc42-conventions.md and fix every failure. Then end with a summary: what you generated, and every TODO: a human must complete, grouped by chapter.

Quick reference

Chapters (note the intentional gaps): 01_introduction_and_goals, 03_context_and_scope, 04_solution_strategy, 05_building_block_view, 06_runtime_view, 07_deployment_view, 08_crosscutting_concepts/ (index + the concepts the system actually has, e.g. 001_security, 002_domain_model), 09_architecture_decision_records/ (index + template + ADRs), 12_glossary. Plus README.md (index) and pdf.yaml. Core chapters to always produce: 1, 3, 5, 12. Add 6/7/8 when the system warrants them. Expect chapter 1's quality goals and stakeholders to be largely TODO: when only the source is available — those aren't derivable from code, and a flagged gap there is the correct outcome, not a failure.

Mermaid block colours via classDef: blue = developed here, green = separately-released component with its own docs (link, don't zoom in), white = 3rd-party / external dependency you don't own.

Common mistakes

• Inventing facts. Never fabricate requirement IDs, people's names/emails, or owners/identifiers — leave TODO:.
• Speculative ADRs. ADRs record history and rationale, which isn't in the code. Author one only when its rationale is evidenced (commits, comments, design docs, config that proves a choice); otherwise list it as a TODO: candidate topic in the ADR index. A made-up ADR reads as settled history.
• Wrong diagram tool. Mermaid only. No PlantUML, no draw.io, no diagrams/ subfolder — diagrams are inline fenced ```mermaid blocks.
• Over-producing. Don't write chapters the source can't support; stub them.
• Skipping the reference. The per-chapter detail in arc42-conventions.md is required reading, not optional background.