Skip to content

Commit 37122f6

Browse files
raifdmuellerraifdmueller
authored
Merge pull request #1 from LLM-Coding/SCTR-Tutorial-2nd-Run
docs: reverse-engineer Vibe spec, arc42 architecture and ADRs
2 parents f71bfd3 + 09677b9 commit 37122f6

30 files changed

Lines changed: 4926 additions & 0 deletions

‎.github/workflows/publish-docs.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Publish documentation site
2+
3+
# Builds the docToolchain microsite (./dtcw generateSite) and deploys it
4+
# to GitHub Pages. Requires repository Settings -> Pages -> Source set to
5+
# "GitHub Actions".
6+
7+
on:
8+
push:
9+
branches: [main]
10+
paths:
11+
- 'src/docs/**'
12+
- 'src/site/**'
13+
- 'docToolchainConfig.groovy'
14+
- 'dtcw'
15+
- '.github/workflows/publish-docs.yml'
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
# Allow only one concurrent deployment; let an in-progress run finish.
24+
concurrency:
25+
group: github-pages
26+
cancel-in-progress: false
27+
28+
jobs:
29+
build:
30+
runs-on: ubuntu-latest
31+
env:
32+
# Used by the microsite for "edit on GitHub" links.
33+
DTC_PROJECT_BRANCH: ${{ github.ref_name }}
34+
steps:
35+
- name: Check out repository
36+
uses: actions/checkout@v4
37+
with:
38+
# docToolchain reads git history for page metadata.
39+
fetch-depth: 0
40+
41+
- name: Generate microsite with docToolchain
42+
# dtcw auto-detects Docker on the runner and uses the
43+
# doctoolchain/doctoolchain image — no local JDK needed.
44+
run: |
45+
chmod +x ./dtcw
46+
./dtcw generateSite
47+
48+
- name: Configure GitHub Pages
49+
uses: actions/configure-pages@v5
50+
51+
- name: Upload site artifact
52+
uses: actions/upload-pages-artifact@v3
53+
with:
54+
path: build/microsite/output
55+
56+
deploy:
57+
needs: build
58+
runs-on: ubuntu-latest
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
steps:
63+
- name: Deploy to GitHub Pages
64+
id: deployment
65+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,3 +206,5 @@ tests/playground/*
206206

207207
# Snapshot test report (generated by pytest-textual-snapshot)
208208
snapshot_report.html
209+
210+
.gradle/

‎CLAUDE.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
2+
## Specification
3+
4+
When we talk about a "specification" or "spec", we mean:
5+
- Persona Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level, with Business Rules (BR-IDs)
6+
- System Use Cases for each technical interface (API endpoint, CLI command, event, file format): input/validation, processing, output/status codes, error responses
7+
- Activity Diagrams for all flows (not just the happy path)
8+
- Acceptance criteria in Gherkin format (Given/When/Then)
9+
- Individual requirements in EARS syntax where applicable (When/While/If/Shall)
10+
- Supplementary Specifications as needed: Entity Model, State Machines, Interface Contracts, Validation Rules
11+
12+
## Requirements Discovery
13+
14+
Clarify requirements using the Socratic Method:
15+
- Ask at most 3 questions at a time, challenge assumptions
16+
- Use MECE to ensure questions cover all areas without overlap
17+
- Keep asking until you fully understand the requirements
18+
19+
Frame the scope before writing it down:
20+
- Impact Mapping connects deliverables to business goals and actors — so you build what moves a goal, not just what was asked.
21+
- User Story Mapping lays stories along the user's journey and exposes a coherent first slice.
22+
23+
Document the result as a PRD (problem, goals, personas, success criteria, scope).
24+
25+
## Architecture Documentation
26+
27+
Architecture documentation follows arc42. Scaffold the arc42 "with-help" template into the project's `src/docs/` via docToolchain `downloadTemplate` rather than restating chapter structure here — each chapter's help text is its structural spec, which the process fills and then replaces.
28+
29+
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 vendored file copies. Not generic boxes.
30+
31+
Decisions are ADRs (Nygard) with a 3-point Pugh Matrix (-1/0/+1). When the rationale is unconfirmed, ADR Status is "Accepted (inferred)" and Pugh cells needing team judgment are marked `?` rather than guessed. 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, Chapter 8 concepts back-reference the ADR that decided them.
32+
33+
Cross-section traceability — arc42 templates do not enforce these, so the contract does:
34+
- Every Chapter 1.2 quality goal maps to a named approach in Chapter 4.
35+
- The external systems in Chapter 3 (context) and the Chapter 5 Level-1 building-block view are the same set — one system boundary in both.
36+
- 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.
37+
- Chapter 9 carries an in-document ADR index (ADR | Title | Status), even when the ADRs live in a separate register.
38+
- Each Chapter 5 building block states responsibility, interface, and source location.
39+
40+
Chapter 1.2 lists only the top 3-5 quality goals — the ones that drive architecture decisions. Chapter 10 may elaborate further quality characteristics beyond those top goals; that is correct arc42, not a defect. The Chapter 10 quality tree marks each characteristic as either concretising a Chapter 1.2 top goal or as a derived quality requirement, and each Chapter 10 quality scenario cross-links back to the Chapter 1.2 goal it concretises (or is marked "derived"). Each Chapter 10 scenario is written in the six-part quality attribute scenario form (Source, Stimulus, Artifact, Environment, Response, Response Measure); the Response Measure carries a literal figure, so the requirement is testable rather than an adjective.
41+
42+
Chapter 11 separates Risks from Technical Debt into two subsections. Each Risk carries probability, impact, a derived priority, and a mitigation/action cross-referencing an existing mitigation in Chapter 8 or a quality scenario where one exists; risks are ordered by priority. Each Technical Debt item references the specific Chapter 5 building block it burdens.
43+
44+
## Crosscutting Concepts
45+
46+
arc42 leaves Chapter 8 open. We require five baseline crosscutting concepts, in this order:
47+
48+
- 8.1 Threat Model — STRIDE; threats get IDs (T-001…).
49+
- 8.2 Security — every mitigation references the T-IDs it closes.
50+
- 8.3 Test — testing pyramid; tests trace to Use Cases and Business Rules.
51+
- 8.4 Observability — logs, metrics, traces, audit trails.
52+
- 8.5 Error Handling — retry, circuit breaker, fallback, recovery.
53+
54+
Add further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) only when the system actually has that concern.
55+
56+
## Layer Boundaries
57+
58+
At every layer boundary:
59+
- Expose only well-defined DTOs and contracts — never domain entities
60+
- Use explicit mapping at every seam
61+
- Apply Anti-Corruption Layers when integrating external systems
62+
- Dependency direction points inward (DIP)
63+
64+
## Backlog Management
65+
66+
Create EPICs and User Stories as GitHub issues from the specification.
67+
- User Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
68+
- Prioritize with MoSCoW (Must/Should/Could/Won't)
69+
- Mark dependencies between issues
70+
- Groom the backlog regularly as the project evolves
71+
72+
## Vertical Slicing
73+
74+
Build the first increment as a walking skeleton: a deployable end-to-end slice that wires every architectural layer together and does almost nothing else.
75+
76+
Grow the system as thin vertical slices — each slice cuts through all layers and delivers one small piece of user value. Slices are tracer bullets: kept and refined, never thrown away.
77+
78+
When a technical unknown blocks a slice, run a spike solution first — a timeboxed, throwaway experiment that removes the risk. Spike code is discarded; only its lesson carries into the slice.
79+
80+
## Implement Next
81+
82+
For each issue:
83+
- Create a feature branch for the EPIC
84+
- Select next issue from backlog (respect dependencies)
85+
- Analyze and document analysis as a comment on the issue
86+
- Implement using TDD (London or Chicago School as appropriate)
87+
- Each test references its Use Case ID for traceability
88+
- Commit with Conventional Commits, reference issue number
89+
- Check if spec or architecture docs need updating
90+
- When EPIC is complete, create a Pull Request
91+
92+
## Refactoring
93+
94+
Refactoring targets are named code smells, not a vague urge to "clean up".
95+
96+
For any refactoring that does not complete in one step, use the Mikado Method: attempt the change, note what breaks, revert, and do the prerequisites first — never leave the build broken while you dig.
97+
98+
Refactoring commits change structure only. Behaviour changes go in separate commits, and the test suite stays green at every commit.
99+
100+
## Code Quality
101+
102+
Our code follows:
103+
- SOLID principles
104+
- DRY, KISS
105+
- Ubiquitous Language from Domain-Driven Design (same terms in code as in the specification)
106+
107+
## Quality Review
108+
109+
Quality assurance follows three layers:
110+
- Code review using Fagan Inspection (structured, systematic, with defined phases)
111+
- Security review based on OWASP Top 10
112+
- Architecture review using ATAM (scenario-based tradeoff analysis against quality goals)
113+
- Use a different AI model or fresh session for reviews to avoid blind spots
114+
115+
## Docs-as-Code
116+
117+
Documentation follows Docs-as-Code according to Ralf D. Müller:
118+
- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain
119+
- Version-controlled, peer-reviewed, and built automatically
120+
- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)
121+
- Projects following this contract include the `dtcw` wrapper and `docToolchainConfig.groovy` so PlantUML / AsciiDoc actually render.
122+
123+
## Socratic Code Theory Recovery
124+
125+
Recover a program's "theory" (Naur 1985) from source code through recursive question refinement.
126+
127+
- Start with 5 root questions: Q1 Problem/Users, Q2 Specification, Q3 Architecture, Q4 Quality Goals, Q5 Risks.
128+
129+
- The second level of the tree is FIXED, not free. Every run emits exactly these nodes, in this order, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]:
130+
- Q1.1-Q1.6: product identity, primary users, channels, why-built, success metrics, segment priority
131+
- Q2.1-Q2.6: actors, use-case catalog, per-interface system specs, data/entity model, acceptance criteria, cross-cutting business rules
132+
- Q3.1-Q3.12: the twelve arc42 chapters, in arc42 order
133+
- Q4.1-Q4.8: the eight ISO/IEC 25010 characteristics; plus Q4.9: which characteristic has priority
134+
- Q5.1-Q5.5: technical debt, security risks, operational risks, dependency/supply-chain risks, scaling/performance risks
135+
136+
- Below the fixed second level, decompose adaptively and code-driven; a node is a leaf only when it can be answered from one specific file:line evidence (a directory is too coarse — decompose further) or definitively marked [OPEN]. Depth tracks code density: a small bounded context yields a shallow tree, a large one a deep tree, capped at four levels below a fixed node. Depth varies between runs — expected.
137+
138+
- Q-IDs are stable: Q3.7 is always Deployment View, in every run, so trees from different runs can be diffed node-by-node.
139+
140+
- Each leaf is [ANSWERED] (with file:line evidence) or [OPEN] (with Category, Ask role, and why it is unanswerable from code).
141+
142+
- Quality is not wholly team knowledge. Derive quality scenarios for the Q4 branch and arc42 Chapter 10 from measurable code behaviour — literal thresholds, timeouts, budgets, the threat catalogue and test concept from Q3.8 — as [ANSWERED] with file:line; never invent target numbers. Only the quality-goal ranking (Q4.9) is [OPEN]. arc42 Chapter 10 carries the derivable scenarios, never just an [OPEN] pointer. Chapter 1.2 names only the top 3-5 quality goals; Chapter 10 covers all eight characteristics — mark each Chapter 10 entry as concretising a Chapter 1.2 top goal or as derived.
143+
144+
- Open Questions are the handoff document: always emit one section per role (Product Owner, Architect, Developer, Domain Expert, Operations), even when a section is empty ("No open questions for this role").
145+
146+
- Two-phase workflow: Phase 1 builds the tree; the team answers the Open Questions; Phase 2 synthesizes documentation from the answered tree.
147+
148+
## Concise Response (TLDR)
149+
150+
Responses lead with the conclusion first (BLUF). Keep to essential points. No filler, no preamble. Use short sentences, active voice, and no unnecessary words (Strunk & White).
151+
152+
## Simple Explanation (ELI5)
153+
154+
Explain complex concepts using simple language and everyday analogies. When the explanation feels hard to write, that reveals gaps in understanding — study those areas first (Feynman Technique).
155+
156+
## Writing Style
157+
158+
Writing follows Gutes Deutsch nach Wolf Schneider (or Plain English according to Strunk & White).
159+
160+
Additionally:
161+
- Technical terms stay in English (LLM, Prompt, Token, Spec, etc.)
162+
- Address the reader directly, use first person sparingly but deliberately
163+
- Use analogies to human thinking to explain technical concepts
164+
- One thought per paragraph (5-8 sentences is fine)
165+
- Section headings are statements, not topic announcements
166+
- First sentence says what the paragraph is about
167+
- Show code and prompts, don't just claim things work
168+
- Conclusions make a clear statement — never end with 'it remains exciting'
169+
170+
---
171+
Generated from https://llm-coding.github.io/Semantic-Anchors/#/contracts
172+
173+
## Docs-as-Code
174+
- docToolchain reads its sources from src/docs/. Write all
175+
documentation there.
176+
- Fill the arc42 template at src/docs/arc42/; do not create a
177+
standalone arc42 file. Write each chapter into its section
178+
file, set the document title to the system name, and remove
179+
the generic "About arc42" help chapter.
180+
- PRD and specification go directly under src/docs/.
181+
- Cross-references must resolve inside src/docs/; do not point
182+
at the Question Tree or the repo-root docs/ folder.

0 commit comments

Comments
 (0)