Skip to content

Commit ec0d14b

Browse files
author
jensgrote
committed
refactor(contract): split architecture-documentation into vocabulary + arc42-authoring skill
Extract procedural content from the over-grown architecture-documentation contract (2922 chars) into a new arc42-authoring skill. Absorb crosscutting-concepts contract into the skill as chapter-8-baseline.md. Shrink architecture-documentation contract to vocabulary only (~385 chars). Closes #529
1 parent 1397409 commit ec0d14b

8 files changed

Lines changed: 298 additions & 27 deletions

File tree

‎skill/arc42-authoring/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: arc42-authoring
3+
description: Produce and maintain arc42 architecture documentation with cross-section traceability, structured quality scenarios, and decision–risk wiring. Use when scaffolding a new arc42 document, extending an existing one, or verifying traceability between chapters.
4+
metadata:
5+
author: LLM-Coding
6+
version: "0.1"
7+
source: https://github.com/LLM-Coding/Semantic-Anchors
8+
license: MIT
9+
---
10+
11+
# arc42 Authoring
12+
13+
Procedural guidance for producing arc42 architecture documentation that goes beyond the template's built-in help text.
14+
15+
## On invocation
16+
17+
When this skill is invoked:
18+
19+
1. **Check whether an arc42 document already exists.** Look for `src/docs/` or `docs/arc42/` in the project. If found, work incrementally — do not re-scaffold.
20+
21+
2. **If no arc42 exists, scaffold first.** Use docToolchain `downloadTemplate` to create the "with-help" template into `src/docs/`. Each chapter's help text is its structural spec — fill and then replace it.
22+
23+
3. **Apply the traceability rules** from [references/traceability-rules.md](references/traceability-rules.md) as you produce or review each chapter. These rules are the project's value-add over plain arc42.
24+
25+
4. **For Chapter 10 quality scenarios**, use the six-part Quality Attribute Scenario format from [references/chapter-10-quality-scenarios.md](references/chapter-10-quality-scenarios.md).
26+
27+
5. **For Chapter 11 Risks and Technical Debt**, follow [references/chapter-11-structure.md](references/chapter-11-structure.md).
28+
29+
6. **For Chapter 8 Crosscutting Concepts**, follow [references/chapter-8-baseline.md](references/chapter-8-baseline.md).
30+
31+
7. **For ADR–Risk wiring**, apply the rules in [references/adr-risk-wiring.md](references/adr-risk-wiring.md).
32+
33+
## When to use this skill
34+
35+
- Scaffolding a new arc42 document for a greenfield project
36+
- Extending an arc42 document after architecture decisions change
37+
- Reviewing arc42 documentation for completeness and cross-section traceability
38+
- Producing Chapter 10 quality scenarios in the six-part form
39+
- Structuring Chapter 11 with the Risks/Technical-Debt split
40+
41+
## When NOT to use this skill
42+
43+
- For reverse-engineering existing code into documentation — use `socratic-code-theory-recovery` instead (Phase 2 of that skill produces arc42 from an answered Question Tree)
44+
- For the vocabulary of what arc42, ADRs, C4, and QAS *are* — that is the `architecture-documentation` contract (always-on)

‎skill/arc42-authoring/references/adr-risk-wiring.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# ADR–Risk Wiring
2+
3+
## Rule
4+
5+
Each ADR's **Consequences** section names the risks the decision creates:
6+
7+
- If the risk is already tracked in Chapter 11: reference its ID (e.g., "introduces R-003").
8+
- If the risk is new: either add it to Chapter 11 with a new R-NNN ID, or record the consequence as "explicitly accepted without a tracked risk" (for trivial consequences).
9+
10+
## Inverse direction
11+
12+
Conversely, Chapter 11 risks that are *caused by* a decision reference the ADR that introduced them.
13+
14+
## Unconfirmed decisions
15+
16+
When the rationale behind a decision is inferred (not confirmed by the team):
17+
18+
- ADR Status: **"Accepted (inferred)"**
19+
- Pugh Matrix cells needing team judgment: marked `?` rather than guessed
20+
21+
This preserves honesty — the documentation records what is known vs. what is assumed.
22+
23+
## Scaffolding
24+
25+
When creating a new ADR, use this template:
26+
27+
```
28+
# ADR-NNN: <Title>
29+
30+
## Status
31+
Accepted | Accepted (inferred) | Proposed | Superseded by ADR-NNN
32+
33+
## Context
34+
<Why this decision is needed>
35+
36+
## Decision
37+
<What was decided>
38+
39+
## Pugh Matrix
40+
| Criterion | Option A | Option B (Baseline) | Option C |
41+
|-----------|----------|---------------------|----------|
42+
| ... | +1 | 0 | -1 |
43+
44+
## Consequences
45+
- <Positive consequence>
46+
- <Negative consequence → R-NNN>
47+
```

‎skill/arc42-authoring/references/chapter-10-quality-scenarios.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Chapter 10 — Quality Scenarios
2+
3+
## Format: Six-Part Quality Attribute Scenario (Bass/Clements/Kazman)
4+
5+
Every Chapter 10 quality scenario is written in this form:
6+
7+
| Part | Description | Example |
8+
|------|-------------|---------|
9+
| **Source** | Who or what triggers the stimulus | End user, CI pipeline, attacker |
10+
| **Stimulus** | The event or condition | 1000 concurrent requests, node failure, SQL injection attempt |
11+
| **Artifact** | What is affected | Order Service, API Gateway, Database |
12+
| **Environment** | Under what conditions | Normal operation, peak load, degraded mode |
13+
| **Response** | What the system does | Queues excess requests, fails over, rejects input |
14+
| **Response Measure** | Literal, testable figure | p99 < 200ms, failover < 30s, zero data exposure |
15+
16+
The **Response Measure** carries a literal figure, so the requirement is testable rather than an adjective ("fast", "secure", "available").
17+
18+
## Chapter 1.2 vs. Chapter 10
19+
20+
- **Chapter 1.2** lists only the top 3–5 quality goals — the ones that drive architecture decisions.
21+
- **Chapter 10** may elaborate further quality characteristics beyond those top goals.
22+
- Each Chapter 10 scenario is marked as either:
23+
- **Concretising** a Chapter 1.2 top goal (cross-link which one), or
24+
- **Derived** — a quality requirement that does not trace to a top goal but matters for the system.
25+
26+
## Deriving scenarios from code
27+
28+
When evidence exists in code (timeouts, budgets, SLOs, test thresholds), derive scenarios as `[ANSWERED]` with `file:line` evidence. Never invent target numbers — only the quality-goal *ranking* is a team decision.

‎skill/arc42-authoring/references/chapter-11-structure.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Chapter 11 — Risks and Technical Debt
2+
3+
## Structure
4+
5+
Chapter 11 separates into two subsections:
6+
7+
### 11.1 Risks
8+
9+
Each risk carries:
10+
11+
| Column | Description |
12+
|--------|-------------|
13+
| **ID** | R-NNN (stable identifier for cross-referencing from ADRs) |
14+
| **Risk** | What could go wrong |
15+
| **Probability** | Low / Medium / High |
16+
| **Impact** | Low / Medium / High |
17+
| **Priority** | Derived from probability × impact |
18+
| **Mitigation** | Cross-reference to Chapter 8 concept or quality scenario that mitigates it |
19+
20+
Risks are ordered by priority (highest first).
21+
22+
### 11.2 Technical Debt
23+
24+
Each debt item:
25+
26+
| Column | Description |
27+
|--------|-------------|
28+
| **ID** | TD-NNN |
29+
| **Debt** | What the shortcut is |
30+
| **Building Block** | Cross-reference to specific Chapter 5 building block it burdens |
31+
| **Impact** | What happens if not addressed |
32+
| **Effort** | Estimated effort to resolve |
33+
34+
## ADR ↔ Risk wiring
35+
36+
See [adr-risk-wiring.md](adr-risk-wiring.md) for how ADR Consequences connect to Risk IDs.

‎skill/arc42-authoring/references/chapter-8-baseline.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Chapter 8 — Crosscutting Concepts Baseline
2+
3+
## Required baseline concepts
4+
5+
arc42 leaves Chapter 8 open. This skill requires five baseline crosscutting concepts, in this order:
6+
7+
| Section | Concept | Key rule |
8+
|---------|---------|----------|
9+
| 8.1 | **Threat Model** | STRIDE; threats get IDs (T-001…) |
10+
| 8.2 | **Security** | Every mitigation references the T-IDs it closes |
11+
| 8.3 | **Test** | Testing pyramid; tests trace to Use Cases and Business Rules |
12+
| 8.4 | **Observability** | Logs, metrics, traces, audit trails |
13+
| 8.5 | **Error Handling** | Retry, circuit breaker, fallback, recovery |
14+
15+
## Extension rule
16+
17+
Add further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) **only when the system actually has that concern**. Do not add empty sections.
18+
19+
## Back-referencing
20+
21+
Chapter 8 concepts back-reference the Chapter 9 ADR that decided them. If no ADR exists for a concept, either create one or note the concept as "established practice, no decision required."

‎skill/arc42-authoring/references/scaffolding.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Scaffolding
2+
3+
## Initial setup with docToolchain
4+
5+
Scaffold the arc42 "with-help" template into the project's `src/docs/` directory:
6+
7+
```bash
8+
docToolchain downloadTemplate
9+
```
10+
11+
Each chapter's help text is its structural spec — fill and then replace the help text as the documentation matures.
12+
13+
## Diagram conventions
14+
15+
- **Format**: PlantUML, not Mermaid
16+
- **Building blocks**: C4 via PlantUML's bundled C4-PlantUML standard library
17+
- **Include form**: `!include <C4/...>` (angle brackets = stdlib), never the remote `https://` URL, never vendored file copies
18+
- **Style**: C4 containers and components, not generic boxes
19+
- **Coverage**: Every context, building-block, and runtime chapter carries at least one diagram

‎skill/arc42-authoring/references/traceability-rules.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Cross-Section Traceability Rules
2+
3+
arc42 templates do not enforce these connections between chapters. This skill does.
4+
5+
## The five rules
6+
7+
1. **Quality Goal → Strategy**: Every Chapter 1.2 quality goal maps to a named approach in Chapter 4 (Solution Strategy).
8+
9+
2. **Context ↔ Building Blocks**: The external systems in Chapter 3 (System Scope and Context) and the Chapter 5 Level-1 building-block view are the same set — one system boundary in both.
10+
11+
3. **Building Block → Runtime**: Every Chapter 5 building block appears in at least one Chapter 6 runtime scenario. Chapter 6 includes at least one error/recovery scenario, not only the happy path.
12+
13+
4. **ADR Index**: Chapter 9 carries an in-document ADR index (ADR | Title | Status), even when the ADRs live in a separate register.
14+
15+
5. **Building Block Completeness**: Each Chapter 5 building block states responsibility, interface, and source location.
16+
17+
## Verification checklist
18+
19+
After producing or updating chapters, verify:
20+
21+
- [ ] Every Chapter 1.2 goal appears by name in Chapter 4
22+
- [ ] Chapter 3 external systems = Chapter 5 Level-1 boundary elements
23+
- [ ] No Chapter 5 building block is absent from Chapter 6
24+
- [ ] Chapter 6 contains ≥1 error/recovery scenario
25+
- [ ] Chapter 9 index is up to date
26+
- [ ] Every Chapter 5 block has: responsibility, interface, source location

0 commit comments

Comments
 (0)