Skip to content

CLAUDE.md, docToolchain v4 und die vollständige Theory Recovery (Phase 1 + 2) - #1

Merged
raifdmueller merged 8 commits into
masterfrom
claude/jolly-ptolemy-2gxvqg
Sep 14, 2026
Merged

CLAUDE.md, docToolchain v4 und die vollständige Theory Recovery (Phase 1 + 2)#1
raifdmueller merged 8 commits into
masterfrom
claude/jolly-ptolemy-2gxvqg

Conversation

@raifdmueller

@raifdmueller raifdmueller commented Sep 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Was drin ist

Sechs Commits, vier Themen. Am Groovy-Build-Code ändert dieser PR nichts — er dokumentiert ihn.

1. CLAUDE.md: Arbeitsweise festgeschrieben

Neue Abschnitte für Specification, Requirements Discovery, Architecture Documentation, Crosscutting Concepts, Layer Boundaries, Backlog Management, Vertical Slicing, Implement Next, Refactoring, Code Quality, Quality Review, Docs-as-Code, Socratic Code Theory Recovery, Documentation Verification, Antwortstil, Teaching, TDD Hamburg Style, Strategic Architecture Analysis und Presentation Planning.

2. docToolchain v4

dtcw4 plus docToolchainConfig.groovy; die Laufzeit liegt außerhalb des Repos unter ~/.doctoolchain/. Alle AsciiDoc-Dokumente unter docs/ rendern nach build/docs/html5 — inklusive acht PlantUML-Diagrammen (C4 via !include <C4/...>, Sequenz, Aktivität, Entity, State), ohne Graphviz.

$ ./dtcw4 local generateHTML
AsciidoctorJ 2.5.13 ready (with diagram support)
...
HTML generation completed successfully.

3. Theory Recovery Phase 1 — der Fragenbaum

  • docs/QUESTION_TREE-arc42-generator.adoc — feste zweite Ebene vollständig, feste dritte Ebene unter Architecture Constraints, darunter code-getrieben bis Tiefe 4. Jedes Blatt [ANSWERED] mit file:line oder [OPEN] mit Kategorie und Rolle.
  • docs/OPEN_QUESTIONS-arc42-generator.adoc — neun offene Blätter, eine Sektion je Rolle, alle neun vom Team beantwortet.

4. Theory Recovery Phase 2 — die Dokumentation

  • docs/specs/prd-arc42-generator.adoc — Problem, Ziele, Personas, Erfolgskriterien, Scope, Constraints, offene Fragen.
  • docs/specs/use-cases-arc42-generator.adoc — vier Persona Use Cases (Cockburn Fully Dressed), sechs System Use Cases, zehn Business Rules, Gherkin-Kriterien, zwölf EARS-Anforderungen, Entity-Modell, State Machine, Interface Contracts, acht Validierungsregeln.
  • docs/arc42/arc42-arc42-generator.adoc — alle zwölf arc42-Kapitel. Kapitel 8 mit den fünf Baseline-Konzepten (Threat Model mit T-001…T-005, Security, Test, Observability, Error Handling) plus Encoding. Kapitel 10 mit acht sechsteiligen Quality-Attribute-Szenarien, jedes mit literalem Response Measure.
  • docs/specs/adrs/ — sieben Nygard-ADRs mit 3-Punkte-Pugh-Matrix, eingebunden in Kapitel 9.
  • docs/specs/backlog-arc42-generator.adoc — vier EPICs, sechzehn User Stories nach INVEST, MoSCoW-priorisiert, mit Abhängigkeiten.

Die synthetisierten Dokumente sind selbsttragend: keine Q-IDs, Evidenz als file:line, Team-Fakten als (team answer) markiert.

Was die Recovery gefunden hat

Befund Evidenz ID
Fehlgeschlagene Konvertierungen ändern den Exit-Code nicht build.groovy:211-215 R-2
Ein fehlgeschlagenes Kapitel der MP-Formate warnt nur und verschwindet lib/Converter.groovy:345 R-1
failed wird nie hochgezählt, Summary meldet immer Failed: 0 lib/Packager.groovy:116,177 R-2
Der Build löscht das Submodul-Verzeichnis samt uncommitteter Arbeit build-arc42.sh:57-60 R-3
example ist ein nie genutztes Feature — null Treffer im Golden Master gegen 995 für arc42help buildconfig.groovy:7,13-14 TD-1
HTML-Charset-Fixup ist unerreichbar lib/Converter.groovy:231-238 vs. :60-61 TD-2
Ein vertippter Phasenname meldet Erfolg, ohne etwas zu tun build.groovy:46 TD-3
switchToreq42.sh schreibt Gradle-Dateien um, die es nicht mehr gibt switchToreq42.sh:1-12 TD-4

Zwei Einschränkungen, ehrlich benannt

./dtcw4 local downloadTemplate scheitert hier mit HTTP 403 auf github.com/arc42/arc42-template/raw/... — die Egress-Policy dieser Session blockiert den Host, nicht docToolchain. Das identische Archiv kam per git clone derselben Quelle, und zwar in der with-help-Variante; downloadTemplate hätte im Headless-Modus nur EN, plain gezogen.

GitHub-Issues sind in diesem Repository deaktiviert (410 Issues has been disabled). Der Backlog liegt deshalb als Dokument vor. Jeder Abschnitt ist so geschrieben, dass er nach dem Aktivieren unter Settings → General → Features → Issues unverändert ein Issue wird.

Test

./dtcw4 local generateHTML rendert alle sechs Dokumente ohne Warnung, alle Querverweise lösen auf.

🤖 Generated with Claude Code

https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G

rdmueller and others added 7 commits September 14, 2026 19:57
@rdmueller @claude
docs: add engineering practice instructions to CLAUDE.md
6672693 
Document the shared vocabulary and procedures for specification,
requirements discovery, architecture documentation, crosscutting
concepts, backlog management, vertical slicing, refactoring, quality
review, docs-as-code, code theory recovery, documentation verification,
response style, teaching, TDD Hamburg Style, strategic architecture
analysis and presentation planning.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
build: add docToolchain v4 wrapper and config
6a50a59 
Install docToolchain v4 per the Docs-as-Code contract: the dtcw4 wrapper
script plus a minimal docToolchainConfig.groovy so the AsciiDoc sources
under docs/ render to build/docs/html5.

Verified with ./dtcw4 local generateHTML (AsciidoctorJ 2.5.13).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
docs: recover the arc42-generator theory as a question tree (phase 1)
9fd9a8d 
Socratic Code Theory Recovery, phase 1: build the question tree from the
code, do not yet write documentation.

- QUESTION_TREE-arc42-generator.adoc: Q1-Q5 with the fixed second level
  (Q1.1-Q1.6, Q2.1-Q2.6, Q3.1-Q3.12, Q4.1-Q4.9, Q5.1-Q5.5) and the fixed
  third level under Q3.2; every leaf either [ANSWERED] with file:line
  evidence or [OPEN] with category and ask role.
- OPEN_QUESTIONS-arc42-generator.adoc: the nine open leaves, one section
  per role, each answerable in one to three sentences.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
docs: answer all nine open questions of the theory recovery
d2d67bd 
The team answered the handoff document; phase 1 is now complete.

Notable: `example` is a never-used feature. A shallow clone of the Golden
Master shows zero occurrences of `arc42example` against 995 of `arc42help`
in 168 .adoc files, so the regex in lib/Templates.groovy:80 runs on every
file and never matches.

Further decisions recorded: Gradle was replaced because it generated its
own build scripts in a first pass; release effort is the success metric;
EN/DE are the reference languages; CLAUDE.md governs branching and commits
from now on; security risk is accepted deliberately, so SafeMode.UNSAFE
stays; reliability outranks performance; a full build may take up to
20 minutes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
docs: add arc42 architecture documentation (phase 2)
57e0a3f 
Synthesize the twelve arc42 chapters from the answered question tree.
Scaffold is the with-help template of the Golden Master; dtcw4
downloadTemplate is blocked by the session egress policy (HTTP 403 on
github.com/.../raw/...), so the identical archive came from a git clone
of the same repository.

- Chapter 1.2 names four quality goals, chapter 10 carries one scenario
  per goal plus four derived ones, covering all eight ISO 25010
  characteristics with literal response measures.
- Chapter 8 follows the five-concept baseline: threat model (T-001 to
  T-005, accepted), security, test, observability, error handling, plus
  encoding as a sixth concept the system actually has.
- Chapter 9 records seven ADRs in Nygard form, each with a three-point
  Pugh matrix.
- Chapter 11 separates risks (R-1 to R-7) from technical debt (TD-1 to
  TD-11); ADRs reference the risk IDs they create or accept.
- Eight C4 and sequence diagrams as inline PlantUML, rendered by
  AsciidoctorJ Diagram without Graphviz.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
docs: synthesize PRD, specification and ADRs from the answered tree
1ffd290 
Phase 2 of the theory recovery, in the prescribed layout:

- docs/specs/prd-arc42-generator.adoc: problem, goals, personas,
  success criteria, scope, constraints, open questions.
- docs/specs/use-cases-arc42-generator.adoc: four persona use cases in
  Cockburn fully dressed form, six system use cases (CLI, container
  entry point, config file, input contract, output contract, Pandoc
  process), ten business rules, Gherkin criteria, twelve EARS
  requirements, entity model, state machine, interface contracts and
  eight validation rules.
- docs/specs/adrs/: the seven ADRs as individual Nygard records with
  Pugh matrices; chapter 9 of the architecture includes them.
- docs/arc42/arc42-arc42-generator.adoc: renamed from architecture.adoc.

The synthesized documents are self-contained: no question IDs, code
evidence as file:line, and facts only the team could supply marked
(team answer). Nothing is deferred - all nine questions were answered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@rdmueller @claude
docs: add the backlog derived from the specification
c3df503 
Four EPICs with sixteen user stories, prioritized with MoSCoW, each in
INVEST form with Gherkin acceptance criteria, code evidence and marked
dependencies.

The GitHub issue tracker of this repository is disabled (the API answers
410), so the backlog lives as a document. Each section is written to
become one issue verbatim once Issues is enabled under Settings ->
General -> Features.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@raifdmueller raifdmueller changed the title Engineering practices in CLAUDE.md, docToolchain v4, theory recovery phase 1 CLAUDE.md, docToolchain v4 und die vollständige Theory Recovery (Phase 1 + 2) Sep 14, 2026
@rdmueller @claude
ci: publish the documentation microsite to GitHub Pages
aa5e0e0 
Add .github/workflows/documentation.yml: it installs docToolchain (cached
by the wrapper's hash, so the one-time Gradle build runs only when the
pinned version changes), runs generateSite, checks that a landing page
was produced, and deploys to Pages. Pull requests build the site and
upload it as an artifact without publishing.

Configure the microsite so the site is complete: landing page from the
internal theme, project title, footer and edit links, and one menu entry
per document. The jbake menu renders one entry per code, so each document
carries its own :jbake-menu: code; include fragments (arc42 chapters,
ADR records, help style) are excluded from the menu.

Correct the two places that claimed no CI exists at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G
@raifdmueller
raifdmueller merged commit b55ffdf into master Sep 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@raifdmueller @rdmueller