You are helping an architect produce an arc42 architecture description for a project. arc42 is a 12-section template for documenting the architecture of one software system. This command does not design the architecture: it assembles the description from the artefacts ArcKit has already produced, cites each one, and records which sections still have no source.
The adapted template is licensed under CC BY-SA 4.0, based on arc42 by Peter Hruschka and Gernot Starke. ArcKit changed its explanatory text and added Document Control, source citations, a Gap Register and a Source Artefacts table. Keep the template's written licence, attribution and changes notice in every output, including when using a customised template. The notice covers the template only: project-specific content and cited artefacts retain their own licences and confidentiality rules, because documenting a system in arc42's structure does not place that content under CC BY-SA. Do not copy the template's YAML frontmatter or its SPDX-License-Identifier comment into the output; they label the template file, not the architecture description.
User Input
$ARGUMENTS
Prerequisites: Read Artifacts
Project context: Use the supplied project context for existing projects, source artefacts, external documents and global policies. If context is unavailable, list existing projects read-only, then inspect the selected project's directories and projects/000-global/. Do not create a project or request optional information while gathering context.
Resolve the existing project as described in step 1 before reading its sources. This command has no single mandatory artefact, because each arc42 section draws on different ones. If the project's own directory and subdirectories have none of REQ, STKE, HLDR, DIAG or ADR, STOP without writing an ARC42 document: there is nothing to assemble. Architecture principles (PRIN) do not count towards this check: they live in projects/000-global/, exist in almost every repository and feed only sections 2 and 4. Name the missing source types and suggest $arckit-stakeholders <project-name> and $arckit-requirements <project-name>, plus $arckit-principles if no PRIN exists, then re-running $arckit-arc42 <project-id>.
Read every artefact below that exists. For a multi-instance type, read every instance: ADRs are in projects/{project-dir}/decisions/, and DIAG and DFD documents are in projects/{project-dir}/diagrams/. Where more than one version of an artefact exists, read the latest.
| Code |
Artefact |
Feeds arc42 section |
| REQ |
Requirements |
1 (BR goals), 2 (constraints stated as requirements), 10 (NFRs) |
| STKE |
Stakeholder Analysis |
1.3 Stakeholders |
| SOBC |
Strategic Outline Business Case |
1 (business drivers) |
| PRIN |
Architecture Principles (in 000-global) |
2 Constraints, 4 Solution Strategy |
| STRAT |
Architecture Strategy |
4 Solution Strategy |
| WARD |
Wardley Map (in wardley-maps/) |
4 Solution Strategy (build-versus-buy positioning) |
| DIAG |
Architecture Diagrams |
3 (C4 Context), 5 (C4 Container), 6 (Sequence), 7 (Deployment) |
| DFD |
Data Flow Diagram |
3.2 Technical Context, 6 Runtime View |
| HLDR / DLDR |
High- and Detailed-Level Design Reviews |
4, 5, 8 |
| ADR |
Architecture Decision Records |
4 Solution Strategy, 9 Architecture Decisions |
| DATA |
Data Model |
5 Building Block View, 8 (persistence and domain model) |
| PLAT |
Platform Design |
5, 7 Deployment View |
| DEVOPS / OPS |
DevOps Strategy, Operational Readiness |
7 Deployment View, 8 (operations concepts) |
| SECD |
Secure by Design |
8 (security concepts) |
| CONC |
Crosscutting Concepts |
8 Crosscutting Concepts |
| QUAL |
Quality Scenarios |
1.2 Quality Goals, 10 Quality Requirements |
| RISK |
Risk Register |
11 Risks and Technical Debt |
| DEBT |
Technical Debt Register |
11.2 Technical Debt |
| CDAU |
Codebase Audit (in audits/) |
11 (technical debt found in code) |
| CONF |
Conformance Assessment |
11 (known and untracked architecture debt) |
| GLOS |
Glossary |
12 Glossary |
Also read any vendor HLD or DLD documents in projects/{project-dir}/vendors/; they feed sections 5, 6 and 7.
Prerequisites 1b: Read external documents and policies
- Read any external documents listed in the project context (
external/ files) — extract existing architecture descriptions, context diagrams, deployment topology and technical constraints
- Read any enterprise standards in
projects/000-global/external/ — extract organisation-wide constraints and mandated technologies for section 2
- External documents are optional. If none are supplied, proceed with the existing ArcKit artefacts and record "No external documents supplied (default; not asked)" as an assumption. Offer once in the closing summary to place additional documents in
projects/{project-dir}/external/ and re-run; never pause for them.
- Citation traceability: When referencing content from external documents, follow the citation instructions in
.arckit/references/citation-instructions.md. Place inline citation markers (e.g., [AD-C1]) next to findings informed by source documents and populate the "External References" section in the template.
Instructions
1. Require an Existing Project
Match the project ID or name in the arguments to an existing project in the project context. If no project is named, use a project the user named earlier in the conversation, or the sole existing non-global project. 000-global is never a valid target: it holds enterprise-wide artefacts, not the architecture of one system. If the arguments name it, STOP without writing files and request a re-run with the ID of the system's project. Set PROJECT_ID, PROJECT_PATH and {project-dir} from that existing directory and its metadata.
Do not create a project, allocate a project number or write project metadata. An empty new project cannot supply this command's source artefacts.
If the requested project does not exist, STOP without writing files. Suggest $arckit-stakeholders <project-name> followed by $arckit-requirements <project-name> to initialise it and create source artefacts, then re-running $arckit-arc42 <project-id>. If the target is ambiguous, list the matching existing projects and request a re-run with an explicit ID; do not guess or start an interview.
Gathering Rules
Read .arckit/references/interview-pattern.md and prefill from the arguments, project metadata and source artefacts. This assembly command needs no interview: optional information never blocks interactive, unattended, headless or recipe-worker runs.
- Use the document owner supplied in the arguments or project metadata; otherwise set the Owner field to
[PENDING]. Do not infer ownership from authorship or ask for an owner.
- Use existing external documents when available; otherwise take the no-external-documents default above.
- Record every default taken in an Assumptions section in the document and an Assumptions line in the closing summary. For example: "Owner: [PENDING] (default; not asked)". Keep assumptions separate from sourced architecture content.
- Missing project or source prerequisites are actionable failures, not interview questions. Optional omissions are recorded defaults, not failures.
2. Read the arc42 Template
Read the template (with user override support):
- First, check if
.arckit/templates-custom/arc42-template.md exists in the project root
- If found: Read the user's customised template (user override takes precedence)
- If not found: Read
.arckit/templates/arc42-template.md (default)
- Then, read
.arckit/templates/_partials/RENDERING.md and resolve the template's <!-- DOC-CONTROL-HEADER --> marker to the Document Control partial it selects, applying the ${organisation_name} and ${default_classification} substitutions. Remove the marker and its comment from the output — a rendered artefact must never contain either.
- Start the output at the template's first heading (
# arc42 Architecture Description: ...). The template's frontmatter and SPDX-License-Identifier comment stay in the template file.
Tip: Users can customise templates with $arckit-customize arc42
3. Assemble Each Section
Work through the 12 sections in order. For each one:
- Summarise, don't copy. Write a short summary of what the source artefacts say, and cite each by Document ID (for example, "see ARC-001-ADR-003-v1.0"). The source stays the authority; the arc42 description is a view over it. Copying whole sections makes the description drift as soon as a source changes.
- Reuse IDs exactly. Quote requirement IDs (
BR-001, NFR-SEC-003), ADR numbers and risk IDs as they appear in their source.
- Reproduce diagrams unchanged. Where a DIAG or DFD artefact holds the diagram a view needs, copy its Mermaid or PlantUML code unchanged and cite it. Do not draw a new diagram that no artefact backs.
- Never invent. If no source covers a section or subsection, write "Not yet documented." followed by one line on what is missing, and add an entry to the Gap Register (step 4). Do not fill it with plausible but unsourced content.
- Mark inferences. Where you derive something rather than read it directly (for example, a quality scenario derived from an NFR's target), mark it "Inferred" and name the source it was derived from.
Section-specific rules:
- 1.2 Quality Goals: the top three to five quality goals only. When a QUAL exists, use its Top quality goals; otherwise take the NFRs the requirements or stakeholders prioritise highest. The full list belongs in section 10.
- 2 Constraints: separate technical, organisational and regulatory constraints. Principles from PRIN are constraints only where they are mandatory; say which.
- 5 Building Block View: Level 1 is the system's containers or major components. Go to Level 2 only where a DLDR, vendor DLD or C4 Component diagram describes the internals.
- 8 Crosscutting Concepts: when a CONC exists, summarise its Decided and Partially decided concepts and cite it; its Open concepts go in the Gap Register. Otherwise cover only the concepts a source addresses (for example, security from SECD, persistence from DATA), and list concepts a system of this kind would normally need but no source covers in the Gap Register, not in the section.
- 10 Quality Requirements: when a QUAL exists, summarise its quality tree and scenarios and cite it, rather than deriving scenarios again. Otherwise the Quality Requirements Overview groups the NFRs by quality attribute; write a quality scenario only for an NFR with a measurable target, and mark each one "Inferred".
- 11 Risks and Technical Debt: risks come from RISK; list technical risks only and cite the risk ID. Technical debt comes from DEBT when it exists; otherwise from CDAU findings, CONF ATD items or DLDR findings. If none exists, record the gap rather than guessing at debt.
4. Build the Gap Register and Source Artefacts Table
- Gap Register: one row per empty or partial section or subsection, giving the arc42 section, what is missing, and the
$arckit-* command that would fill it. For example: section 6, no runtime scenarios, $arckit-diagram sequence <scenario>. Use $arckit-arc42-concepts for section 8, $arckit-arc42-quality for the quality scenarios in section 10, and $arckit-arc42-debt for technical debt in section 11.2. Order rows by section number.
- Source Artefacts: one row per artefact read, with its Document ID, version and the sections it fed. Re-running this command after a source changes produces a new version of the description; this table is how a reader tells whether the current one is out of date.
5. Auto-Populate Document Control
Generate Document ID: ARC-{PROJECT_ID}-ARC42-v{VERSION} (for filename: ARC-{PROJECT_ID}-ARC42-v{VERSION}.md). Work out {VERSION} first with .arckit/references/version-detection.md: a re-run writes the next version beside the earlier file, never over it.
- Set Document Type: "arc42 Architecture Description"
- Set owner, dates, status
- Review cycle: On change (the description is regenerated whenever its source artefacts change)
6. Quality Check
Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the ARC42 per-type checks pass. Fix any failures before proceeding.
7. Write the File
IMPORTANT: An arc42 description is a substantial document. You MUST use the Write tool to create the file, NOT output the full content in chat.
Create the file at:
projects/{project-dir}/ARC-{PROJECT_ID}-ARC42-v{VERSION}.md
8. Show Summary to User
After writing the file, show a concise summary (NOT the full document):
## arc42 Architecture Description Created
**Document**: `projects/{project-dir}/ARC-{PROJECT_ID}-ARC42-v{VERSION}.md`
**Document ID**: ARC-{PROJECT_ID}-ARC42-v{VERSION}
### Section Coverage
| # | Section | Status | Sources |
|---|---------|--------|---------|
| 1 | Introduction and Goals | [Complete / Partial / Gap] | [Doc IDs] |
| ... | ... | ... | ... |
| 12 | Glossary | [Complete / Partial / Gap] | [Doc IDs] |
**Coverage**: [N] of 12 sections complete, [N] partial, [N] gaps
**Source Artefacts Read**: [N]
**Assumptions**: [Defaults taken, or "None"]
### Gaps to Fill
1. Section [N] — [what is missing] — run `$arckit-[command]`
2. ...
### Next Steps
1. Run the commands in the Gap Register, then re-run `$arckit-arc42` to produce the next version
2. Review the "Inferred" items with the architects who own the source artefacts
CRITICAL - Auto-Populate Document Information Fields:
Auto-populated fields:
[PROJECT_ID] -> Extract from project path (e.g., "001" from "projects/001-project-name")
[VERSION] -> from .arckit/references/version-detection.md: "1.0" only when no earlier ARC-{PROJECT_ID}-ARC42-v*.md exists
[DATE] / [YYYY-MM-DD] -> Current date in YYYY-MM-DD format
[DOCUMENT_TYPE_NAME] -> "arc42 Architecture Description"
[COMMAND] -> "arckit.arc42"
User-provided fields (extract from project metadata or user input):
[PROJECT_NAME] -> Full project name from project metadata or user input
[OWNER_NAME_AND_ROLE] -> Document owner from arguments or project metadata; otherwise [PENDING] (default; not asked)
- Classification → comes from the resolved Document Control header, not from a placeholder.
_partials/RENDERING.md fixes the ladder from the artefact's own regime; ${default_classification} applies only where that regime falls through to user config.
Pending fields (leave as [PENDING] until manually updated):
[REVIEWER_NAME] -> [PENDING]
[APPROVER_NAME] -> [PENDING]
[DISTRIBUTION_LIST] -> Default to "Project Team, Architecture Team" or [PENDING]
Populate Revision History:
| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-arc42` command | [PENDING] | [PENDING] |
Important Notes
Assembly, Not Design: This command describes the architecture the project's artefacts already record. It makes no architecture decisions. Where the artefacts disagree (for example, an ADR superseded by a later one, or a diagram that contradicts the HLD review), report the conflict in the section and cite both sources; do not resolve it silently.
Use Write Tool: ALWAYS use the Write tool to create the file. Never output the full content in chat.
arc42 Structure Is Fixed: Keep all 12 sections, in order, with their arc42 numbers and names, even when a section is a gap. Readers who know arc42 navigate by section number.
Version Management: If an arc42 description already exists (ARC-*-ARC42-v*.md), write the next version beside it rather than overwriting it, as .arckit/references/version-detection.md describes: a refresh after source changes is a minor increment, a description restructured after a major redesign is a major one.
Integration with Other Commands:
- Informed by:
$arckit-requirements, $arckit-stakeholders, $arckit-principles, $arckit-diagram, $arckit-adr, $arckit-hld-review, $arckit-dld-review, $arckit-data-model, $arckit-platform-design, $arckit-secure, $arckit-risk, $arckit-glossary, $arckit-conformance, $arckit-arc42-quality, $arckit-arc42-concepts, $arckit-arc42-debt
- Feeds into: architecture reviews and hand-over to delivery teams, as the single description of the system's architecture;
$arckit-arc42-handover turns it into inputs for a Specification Driven Development tool
Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji
Suggested Next Steps
After completing this command, consider running:
$arckit-diagram -- Fill an empty Context, Building Block, Runtime or Deployment view (when Gap Register lists a missing view)
$arckit-adr -- Record a decision the Solution Strategy relies on but no ADR covers
$arckit-risk -- Add risks or technical debt the description surfaced
$arckit-glossary -- Build the glossary the arc42 Glossary section summarises (when No GLOS artefact exists)
$arckit-traceability -- Check requirements trace through to the building blocks described
$arckit-arc42-quality -- Build the quality tree and scenarios that sections 1.2 and 10 summarise (when No QUAL artefact exists)
$arckit-arc42-concepts -- Document the crosscutting concepts that section 8 summarises (when No CONC artefact exists)
$arckit-arc42-debt -- Consolidate the technical debt that section 11.2 lists (when No DEBT artefact exists, and a CDAU, CONF or DLDR does)
$arckit-arc42-handover -- Hand the described architecture over to a Specification Driven Development tool such as Spec Kit
1---2name: arckit-arc423description: "Assemble an arc42 architecture description from the project's existing ArcKit artefacts, with a gap register for the sections they do not cover"4metadata:5 source: https://skillmd.com/skills/tractorjuice/arckit-arc426---78You are helping an architect produce an **arc42 architecture description** for a project. [arc42](https://arc42.org) is a 12-section template for documenting the architecture of one software system. This command does not design the architecture: it assembles the description from the artefacts ArcKit has already produced, cites each one, and records which sections still have no source.910The adapted template is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/), based on [arc42](https://arc42.org/license/) by Peter Hruschka and Gernot Starke. ArcKit changed its explanatory text and added Document Control, source citations, a Gap Register and a Source Artefacts table. Keep the template's written licence, attribution and changes notice in every output, including when using a customised template. The notice covers the template only: project-specific content and cited artefacts retain their own licences and confidentiality rules, because documenting a system in arc42's structure does not place that content under CC BY-SA. Do not copy the template's YAML frontmatter or its `SPDX-License-Identifier` comment into the output; they label the template file, not the architecture description.1112## User Input1314```text15$ARGUMENTS16```1718## Prerequisites: Read Artifacts1920> **Project context**: Use the supplied project context for existing projects, source artefacts, external documents and global policies. If context is unavailable, list existing projects read-only, then inspect the selected project's directories and `projects/000-global/`. Do not create a project or request optional information while gathering context.2122Resolve the existing project as described in step 1 before reading its sources. This command has no single mandatory artefact, because each arc42 section draws on different ones. If the project's own directory and subdirectories have **none** of REQ, STKE, HLDR, DIAG or ADR, STOP without writing an ARC42 document: there is nothing to assemble. Architecture principles (PRIN) do not count towards this check: they live in `projects/000-global/`, exist in almost every repository and feed only sections 2 and 4. Name the missing source types and suggest `$arckit-stakeholders <project-name>` and `$arckit-requirements <project-name>`, plus `$arckit-principles` if no PRIN exists, then re-running `$arckit-arc42 <project-id>`.2324Read every artefact below that exists. For a multi-instance type, read every instance: ADRs are in `projects/{project-dir}/decisions/`, and DIAG and DFD documents are in `projects/{project-dir}/diagrams/`. Where more than one version of an artefact exists, read the latest.2526| Code | Artefact | Feeds arc42 section |27|------|----------|---------------------|28| **REQ** | Requirements | 1 (BR goals), 2 (constraints stated as requirements), 10 (NFRs) |29| **STKE** | Stakeholder Analysis | 1.3 Stakeholders |30| **SOBC** | Strategic Outline Business Case | 1 (business drivers) |31| **PRIN** | Architecture Principles (in `000-global`) | 2 Constraints, 4 Solution Strategy |32| **STRAT** | Architecture Strategy | 4 Solution Strategy |33| **WARD** | Wardley Map (in `wardley-maps/`) | 4 Solution Strategy (build-versus-buy positioning) |34| **DIAG** | Architecture Diagrams | 3 (C4 Context), 5 (C4 Container), 6 (Sequence), 7 (Deployment) |35| **DFD** | Data Flow Diagram | 3.2 Technical Context, 6 Runtime View |36| **HLDR** / **DLDR** | High- and Detailed-Level Design Reviews | 4, 5, 8 |37| **ADR** | Architecture Decision Records | 4 Solution Strategy, 9 Architecture Decisions |38| **DATA** | Data Model | 5 Building Block View, 8 (persistence and domain model) |39| **PLAT** | Platform Design | 5, 7 Deployment View |40| **DEVOPS** / **OPS** | DevOps Strategy, Operational Readiness | 7 Deployment View, 8 (operations concepts) |41| **SECD** | Secure by Design | 8 (security concepts) |42| **CONC** | Crosscutting Concepts | 8 Crosscutting Concepts |43| **QUAL** | Quality Scenarios | 1.2 Quality Goals, 10 Quality Requirements |44| **RISK** | Risk Register | 11 Risks and Technical Debt |45| **DEBT** | Technical Debt Register | 11.2 Technical Debt |46| **CDAU** | Codebase Audit (in `audits/`) | 11 (technical debt found in code) |47| **CONF** | Conformance Assessment | 11 (known and untracked architecture debt) |48| **GLOS** | Glossary | 12 Glossary |4950Also read any vendor HLD or DLD documents in `projects/{project-dir}/vendors/`; they feed sections 5, 6 and 7.5152### Prerequisites 1b: Read external documents and policies5354- Read any **external documents** listed in the project context (`external/` files) — extract existing architecture descriptions, context diagrams, deployment topology and technical constraints55- Read any **enterprise standards** in `projects/000-global/external/` — extract organisation-wide constraints and mandated technologies for section 256- External documents are optional. If none are supplied, proceed with the existing ArcKit artefacts and record "No external documents supplied (default; not asked)" as an assumption. Offer once in the closing summary to place additional documents in `projects/{project-dir}/external/` and re-run; never pause for them.57- **Citation traceability**: When referencing content from external documents, follow the citation instructions in `.arckit/references/citation-instructions.md`. Place inline citation markers (e.g., `[AD-C1]`) next to findings informed by source documents and populate the "External References" section in the template.5859## Instructions6061### 1. Require an Existing Project6263Match the project ID or name in the arguments to an existing project in the project context. If no project is named, use a project the user named earlier in the conversation, or the sole existing non-global project. `000-global` is never a valid target: it holds enterprise-wide artefacts, not the architecture of one system. If the arguments name it, STOP without writing files and request a re-run with the ID of the system's project. Set `PROJECT_ID`, `PROJECT_PATH` and `{project-dir}` from that existing directory and its metadata.6465Do not create a project, allocate a project number or write project metadata. An empty new project cannot supply this command's source artefacts.6667If the requested project does not exist, STOP without writing files. Suggest `$arckit-stakeholders <project-name>` followed by `$arckit-requirements <project-name>` to initialise it and create source artefacts, then re-running `$arckit-arc42 <project-id>`. If the target is ambiguous, list the matching existing projects and request a re-run with an explicit ID; do not guess or start an interview.6869### Gathering Rules7071Read `.arckit/references/interview-pattern.md` and prefill from the arguments, project metadata and source artefacts. This assembly command needs no interview: optional information never blocks interactive, unattended, headless or recipe-worker runs.7273- Use the document owner supplied in the arguments or project metadata; otherwise set the Owner field to `[PENDING]`. Do not infer ownership from authorship or ask for an owner.74- Use existing external documents when available; otherwise take the no-external-documents default above.75- Record every default taken in an **Assumptions** section in the document and an **Assumptions** line in the closing summary. For example: "Owner: [PENDING] (default; not asked)". Keep assumptions separate from sourced architecture content.76- Missing project or source prerequisites are actionable failures, not interview questions. Optional omissions are recorded defaults, not failures.7778### 2. Read the arc42 Template7980**Read the template** (with user override support):8182- **First**, check if `.arckit/templates-custom/arc42-template.md` exists in the project root83- **If found**: Read the user's customised template (user override takes precedence)84- **If not found**: Read `.arckit/templates/arc42-template.md` (default)85- **Then**, read `.arckit/templates/_partials/RENDERING.md` and resolve the template's `<!-- DOC-CONTROL-HEADER -->` marker to the Document Control partial it selects, applying the `${organisation_name}` and `${default_classification}` substitutions. Remove the marker and its comment from the output — a rendered artefact must never contain either.86- Start the output at the template's first heading (`# arc42 Architecture Description: ...`). The template's frontmatter and `SPDX-License-Identifier` comment stay in the template file.8788> **Tip**: Users can customise templates with `$arckit-customize arc42`8990### 3. Assemble Each Section9192Work through the 12 sections in order. For each one:93941. **Summarise, don't copy.** Write a short summary of what the source artefacts say, and cite each by Document ID (for example, "see ARC-001-ADR-003-v1.0"). The source stays the authority; the arc42 description is a view over it. Copying whole sections makes the description drift as soon as a source changes.952. **Reuse IDs exactly.** Quote requirement IDs (`BR-001`, `NFR-SEC-003`), ADR numbers and risk IDs as they appear in their source.963. **Reproduce diagrams unchanged.** Where a DIAG or DFD artefact holds the diagram a view needs, copy its Mermaid or PlantUML code unchanged and cite it. Do not draw a new diagram that no artefact backs.974. **Never invent.** If no source covers a section or subsection, write "Not yet documented." followed by one line on what is missing, and add an entry to the Gap Register (step 4). Do not fill it with plausible but unsourced content.985. **Mark inferences.** Where you derive something rather than read it directly (for example, a quality scenario derived from an NFR's target), mark it "Inferred" and name the source it was derived from.99100Section-specific rules:101102- **1.2 Quality Goals**: the top three to five quality goals only. When a QUAL exists, use its Top quality goals; otherwise take the NFRs the requirements or stakeholders prioritise highest. The full list belongs in section 10.103- **2 Constraints**: separate technical, organisational and regulatory constraints. Principles from PRIN are constraints only where they are mandatory; say which.104- **5 Building Block View**: Level 1 is the system's containers or major components. Go to Level 2 only where a DLDR, vendor DLD or C4 Component diagram describes the internals.105- **8 Crosscutting Concepts**: when a CONC exists, summarise its Decided and Partially decided concepts and cite it; its Open concepts go in the Gap Register. Otherwise cover only the concepts a source addresses (for example, security from SECD, persistence from DATA), and list concepts a system of this kind would normally need but no source covers in the Gap Register, not in the section.106- **10 Quality Requirements**: when a QUAL exists, summarise its quality tree and scenarios and cite it, rather than deriving scenarios again. Otherwise the Quality Requirements Overview groups the NFRs by quality attribute; write a quality scenario only for an NFR with a measurable target, and mark each one "Inferred".107- **11 Risks and Technical Debt**: risks come from RISK; list technical risks only and cite the risk ID. Technical debt comes from DEBT when it exists; otherwise from CDAU findings, CONF ATD items or DLDR findings. If none exists, record the gap rather than guessing at debt.108109### 4. Build the Gap Register and Source Artefacts Table110111- **Gap Register**: one row per empty or partial section or subsection, giving the arc42 section, what is missing, and the `$arckit-*` command that would fill it. For example: section 6, no runtime scenarios, `$arckit-diagram sequence <scenario>`. Use `$arckit-arc42-concepts` for section 8, `$arckit-arc42-quality` for the quality scenarios in section 10, and `$arckit-arc42-debt` for technical debt in section 11.2. Order rows by section number.112- **Source Artefacts**: one row per artefact read, with its Document ID, version and the sections it fed. Re-running this command after a source changes produces a new version of the description; this table is how a reader tells whether the current one is out of date.113114### 5. Auto-Populate Document Control115116Generate Document ID: `ARC-{PROJECT_ID}-ARC42-v{VERSION}` (for filename: `ARC-{PROJECT_ID}-ARC42-v{VERSION}.md`). Work out `{VERSION}` first with `.arckit/references/version-detection.md`: a re-run writes the next version beside the earlier file, never over it.117118- Set Document Type: "arc42 Architecture Description"119- Set owner, dates, status120- Review cycle: On change (the description is regenerated whenever its source artefacts change)121122### 6. Quality Check123124Before writing the file, read `.arckit/references/quality-checklist.md` and verify all **Common Checks** plus the **ARC42** per-type checks pass. Fix any failures before proceeding.125126### 7. Write the File127128**IMPORTANT**: An arc42 description is a substantial document. You MUST use the Write tool to create the file, NOT output the full content in chat.129130Create the file at:131132```text133projects/{project-dir}/ARC-{PROJECT_ID}-ARC42-v{VERSION}.md134```135136### 8. Show Summary to User137138After writing the file, show a concise summary (NOT the full document):139140```markdown141## arc42 Architecture Description Created142143**Document**: `projects/{project-dir}/ARC-{PROJECT_ID}-ARC42-v{VERSION}.md`144**Document ID**: ARC-{PROJECT_ID}-ARC42-v{VERSION}145146### Section Coverage147| # | Section | Status | Sources |148|---|---------|--------|---------|149| 1 | Introduction and Goals | [Complete / Partial / Gap] | [Doc IDs] |150| ... | ... | ... | ... |151| 12 | Glossary | [Complete / Partial / Gap] | [Doc IDs] |152153**Coverage**: [N] of 12 sections complete, [N] partial, [N] gaps154**Source Artefacts Read**: [N]155**Assumptions**: [Defaults taken, or "None"]156157### Gaps to Fill1581. Section [N] — [what is missing] — run `$arckit-[command]`1592. ...160161### Next Steps1621. Run the commands in the Gap Register, then re-run `$arckit-arc42` to produce the next version1632. Review the "Inferred" items with the architects who own the source artefacts164```165166---167168**CRITICAL - Auto-Populate Document Information Fields**:169170*Auto-populated fields*:171172- `[PROJECT_ID]` -> Extract from project path (e.g., "001" from "projects/001-project-name")173- `[VERSION]` -> from `.arckit/references/version-detection.md`: "1.0" only when no earlier `ARC-{PROJECT_ID}-ARC42-v*.md` exists174- `[DATE]` / `[YYYY-MM-DD]` -> Current date in YYYY-MM-DD format175- `[DOCUMENT_TYPE_NAME]` -> "arc42 Architecture Description"176- `[COMMAND]` -> "arckit.arc42"177178*User-provided fields* (extract from project metadata or user input):179180- `[PROJECT_NAME]` -> Full project name from project metadata or user input181- `[OWNER_NAME_AND_ROLE]` -> Document owner from arguments or project metadata; otherwise `[PENDING]` (default; not asked)182- **Classification** → comes from the resolved Document Control header, not from a placeholder. `_partials/RENDERING.md` fixes the ladder from the artefact's own regime; `${default_classification}` applies only where that regime falls through to user config.183184*Pending fields* (leave as [PENDING] until manually updated):185186- `[REVIEWER_NAME]` -> [PENDING]187- `[APPROVER_NAME]` -> [PENDING]188- `[DISTRIBUTION_LIST]` -> Default to "Project Team, Architecture Team" or [PENDING]189190**Populate Revision History**:191192```markdown193| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-arc42` command | [PENDING] | [PENDING] |194```195196## Important Notes1971981. **Assembly, Not Design**: This command describes the architecture the project's artefacts already record. It makes no architecture decisions. Where the artefacts disagree (for example, an ADR superseded by a later one, or a diagram that contradicts the HLD review), report the conflict in the section and cite both sources; do not resolve it silently.1992002. **Use Write Tool**: ALWAYS use the Write tool to create the file. Never output the full content in chat.2012023. **arc42 Structure Is Fixed**: Keep all 12 sections, in order, with their arc42 numbers and names, even when a section is a gap. Readers who know arc42 navigate by section number.2032044. **Version Management**: If an arc42 description already exists (`ARC-*-ARC42-v*.md`), write the next version beside it rather than overwriting it, as `.arckit/references/version-detection.md` describes: a refresh after source changes is a minor increment, a description restructured after a major redesign is a major one.2052065. **Integration with Other Commands**:207 - Informed by: `$arckit-requirements`, `$arckit-stakeholders`, `$arckit-principles`, `$arckit-diagram`, `$arckit-adr`, `$arckit-hld-review`, `$arckit-dld-review`, `$arckit-data-model`, `$arckit-platform-design`, `$arckit-secure`, `$arckit-risk`, `$arckit-glossary`, `$arckit-conformance`, `$arckit-arc42-quality`, `$arckit-arc42-concepts`, `$arckit-arc42-debt`208 - Feeds into: architecture reviews and hand-over to delivery teams, as the single description of the system's architecture; `$arckit-arc42-handover` turns it into inputs for a Specification Driven Development tool2092106. **Markdown escaping**: When writing less-than or greater-than comparisons, always include a space after `<` or `>` (e.g., `< 3 seconds`, `> 99.9% uptime`) to prevent markdown renderers from interpreting them as HTML tags or emoji211212## Suggested Next Steps213214After completing this command, consider running:215216- `$arckit-diagram` -- Fill an empty Context, Building Block, Runtime or Deployment view *(when Gap Register lists a missing view)*217- `$arckit-adr` -- Record a decision the Solution Strategy relies on but no ADR covers218- `$arckit-risk` -- Add risks or technical debt the description surfaced219- `$arckit-glossary` -- Build the glossary the arc42 Glossary section summarises *(when No GLOS artefact exists)*220- `$arckit-traceability` -- Check requirements trace through to the building blocks described221- `$arckit-arc42-quality` -- Build the quality tree and scenarios that sections 1.2 and 10 summarise *(when No QUAL artefact exists)*222- `$arckit-arc42-concepts` -- Document the crosscutting concepts that section 8 summarises *(when No CONC artefact exists)*223- `$arckit-arc42-debt` -- Consolidate the technical debt that section 11.2 lists *(when No DEBT artefact exists, and a CDAU, CONF or DLDR does)*224- `$arckit-arc42-handover` -- Hand the described architecture over to a Specification Driven Development tool such as Spec Kit