refactor(contract): split architecture-documentation into vocabulary contract + arc42-authoring skill#577
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (3)
🚧 Files skipped from review as they are similar to previous changes (2)
WalkthroughDie Änderung ergänzt eine neue arc42-Authoring-Skill mit Referenzdokumenten zu Scaffolding, Kapitel 8/10/11, Traceability und ADR↔Risk-Regeln. Zusätzlich werden mehrere Changesarc42-Authoring-Skill-Definition
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 markdownlint-cli2 (0.22.1)skill/arc42-authoring/SKILL.mdmarkdownlint-cli2 v0.22.1 (markdownlint v0.40.0) skill/arc42-authoring/references/adr-risk-wiring.mdmarkdownlint-cli2 v0.22.1 (markdownlint v0.40.0) skill/arc42-authoring/references/chapter-10-quality-scenarios.mdmarkdownlint-cli2 v0.22.1 (markdownlint v0.40.0)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
JensGrote
force-pushed
the
feat/split-architecture-documentation-contract
branch
from
d30c1e2 to
ec0d14b
Compare
JensGrote
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skill/arc42-authoring/references/adr-risk-wiring.md`:
- Line 27: The fenced code block at the top of adr-risk-wiring.md currently
starts with triple backticks only (` ``` `); update that opening fence to
include the language identifier by changing it to "```markdown" so the block
becomes "```markdown" followed by the "# ADR-NNN: <Title>" line to enable syntax
highlighting.
In `@website/public/data/contracts.json`:
- Around line 41-47: Update the two references/catalog.md files to include the
missing anchor entries so they match the anchor IDs listed in contracts.json and
the files in docs/anchors; specifically add entries for "arc42" (if absent),
"adr-according-to-nygard", "bdd-given-when-then", "pugh-matrix", and
"quality-attribute-scenario" (and any other anchor IDs present in
website/public/data/contracts.json but missing from catalog.md), ensuring each
entry uses the same anchor ID string and the same display/title format used for
existing anchors in those catalog.md files so the catalogs stay synchronized
with docs/anchors and contracts.json.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 30278b24-ca55-4d67-8bfb-6ebbc02f891b
📒 Files selected for processing (8)
skill/arc42-authoring/SKILL.mdskill/arc42-authoring/references/adr-risk-wiring.mdskill/arc42-authoring/references/chapter-10-quality-scenarios.mdskill/arc42-authoring/references/chapter-11-structure.mdskill/arc42-authoring/references/chapter-8-baseline.mdskill/arc42-authoring/references/scaffolding.mdskill/arc42-authoring/references/traceability-rules.mdwebsite/public/data/contracts.json
|
|
||
| When creating a new ADR, use this template: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Sprachkennung für Code-Block ergänzen.
Der Fenced Code Block sollte eine Sprachkennung haben, um Syntax-Highlighting zu ermöglichen. Fügen Sie markdown nach den öffnenden Backticks hinzu.
📝 Vorgeschlagene Korrektur
-```
+```markdown
# ADR-NNN: <Title>🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skill/arc42-authoring/references/adr-risk-wiring.md` at line 27, The fenced
code block at the top of adr-risk-wiring.md currently starts with triple
backticks only (` ``` `); update that opening fence to include the language
identifier by changing it to "```markdown" so the block becomes "```markdown"
followed by the "# ADR-NNN: <Title>" line to enable syntax highlighting.
Source: Linters/SAST tools
JensGrote
force-pushed
the
feat/split-architecture-documentation-contract
branch
from
ec0d14b to
3ab1a88
Compare
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skill/arc42-authoring/references/chapter-10-quality-scenarios.md (1)
1-29:⚠️ Potential issue | 🔴 CriticalPflicht-Check zur Anchor-Synchronisation: erforderliche Dateien/Verzeichnisse fehlen
Der Check kann nicht durchgeführt werden, weil im Repo keindocs/anchors-Verzeichnis gefunden wurde undskill/arc42-authoring/references/catalog.mdnicht existiert (stattdessen nurskill/semantic-anchor-translator/references/catalog.mdvorhanden). Entsprechend muss die fehlendedocs/anchors-Quelle und/oder der fehlendeskill/arc42-authoring-Catalog ergänzt bzw. korrigiert werden.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skill/arc42-authoring/references/chapter-10-quality-scenarios.md` around lines 1 - 29, Der Pflicht-Check schlägt fehl, weil das Verzeichnis docs/anchors fehlt und die erwartete Datei skill/arc42-authoring/references/catalog.md nicht vorhanden ist (stattdessen existiert nur skill/semantic-anchor-translator/references/catalog.md); behebe dies, indem du entweder das fehlende docs/anchors-Verzeichnis und die darin benötigten Anchor-Quellen anlegst oder den Pfad in der Check-Logik/CI so korrigierst, dass auf die vorhandene skill/semantic-anchor-translator/references/catalog.md verwiesen wird; stelle sicher, dass die Anchors im richtigen Format und Ort liegen und passe ggf. alle Referenzen/Configs an, die auf skill/arc42-authoring/references/catalog.md verweisen.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@skill/arc42-authoring/references/chapter-10-quality-scenarios.md`:
- Around line 1-29: Der Pflicht-Check schlägt fehl, weil das Verzeichnis
docs/anchors fehlt und die erwartete Datei
skill/arc42-authoring/references/catalog.md nicht vorhanden ist (stattdessen
existiert nur skill/semantic-anchor-translator/references/catalog.md); behebe
dies, indem du entweder das fehlende docs/anchors-Verzeichnis und die darin
benötigten Anchor-Quellen anlegst oder den Pfad in der Check-Logik/CI so
korrigierst, dass auf die vorhandene
skill/semantic-anchor-translator/references/catalog.md verwiesen wird; stelle
sicher, dass die Anchors im richtigen Format und Ort liegen und passe ggf. alle
Referenzen/Configs an, die auf skill/arc42-authoring/references/catalog.md
verweisen.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 7ec70d77-6e35-4a77-b0fe-27a550f46863
📒 Files selected for processing (8)
skill/arc42-authoring/SKILL.mdskill/arc42-authoring/references/adr-risk-wiring.mdskill/arc42-authoring/references/chapter-10-quality-scenarios.mdskill/arc42-authoring/references/chapter-11-structure.mdskill/arc42-authoring/references/chapter-8-baseline.mdskill/arc42-authoring/references/scaffolding.mdskill/arc42-authoring/references/traceability-rules.mdwebsite/public/data/contracts.json
✅ Files skipped from review due to trivial changes (3)
- skill/arc42-authoring/references/traceability-rules.md
- skill/arc42-authoring/references/scaffolding.md
- skill/arc42-authoring/references/chapter-8-baseline.md
🚧 Files skipped from review as they are similar to previous changes (2)
- skill/arc42-authoring/references/chapter-11-structure.md
- website/public/data/contracts.json
…+ 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 LLM-Coding#529
JensGrote
force-pushed
the
feat/split-architecture-documentation-contract
branch
from
3ab1a88 to
d0aeea1
Compare
1 participant
refactor(contract): split architecture-documentation into vocabulary contract + arc42-authoring skill
(German version below)
Splits the over-grown
architecture-documentationcontract (2922 chars) into:arc42-authoring/— carries the how-toCloses #529. Absorbs
crosscutting-conceptsinto the skill.Assessment against project taxonomy
Contract/Skill boundary — catalog evidence
templatefield incontracts.jsonSKILL.md+references/+prompts/architecture-documentation)arc42-authoring)Size analysis — the outlier
architecture-documentationsocratic-code-theory-recoveryexplaining-teachingtdd-hamburg-stylearchitecture-documentationis the only contract >1200 chars that has no companion skill.socratic-code-theory-recoveryis similarly long but justified as a condensed reminder of its companion skill — the procedural depth lives in the skill, not the contract alone.Precedent: "invoke a skill for depth" pattern
The
explaining-teachingcontract (#573) proves this pattern works:socratic-code-theory-recoveryskillConsistency with Harness Inventory
The Harness Inventory page (
docs/harness-inventory.adoc) separates "what a layer checks" (definition) from "how to deploy it" (procedure). Same lens: contract = the what, skill = the how.Changes
1. New skill:
skill/arc42-authoring/Content extracted 1:1 from the current
architecture-documentationandcrosscutting-conceptscontracts. No information lost — only relocated.2. Shrunken contract:
architecture-documentationFrom 2922 chars → ~340 chars:
3. Absorbed:
crosscutting-conceptsMoved to
skill/arc42-authoring/references/chapter-8-baseline.md. The contract entry is removed fromcontracts.json.4. Socratic overlap resolution
The
socratic-code-theory-recoveryskill'sreferences/arc42.mdcontains a Phase 1 decomposition guide (Q-IDs, when to stop decomposing) — this is specific to the Socratic workflow, not to arc42 authoring. No overlap — both skills coexist without duplication:arc42-authoringsocratic-code-theory-recoveryTradeoff acknowledged
The traceability rules move from always-on to on-demand. For architecture work the skill is invoked anyway — no loss. For someone only reading the contract as a reminder, the detail was already too large for always-on context — this is a correction, not a regression (as #529 states).
Deutsche Version
refactor(contract): architecture-documentation in Vokabular-Contract + arc42-authoring-Skill aufteilen
Teilt den überwachsenen
architecture-documentation-Contract (2922 Zeichen) auf in:arc42-authoring/— enthält das WieSchließt #529. Absorbiert
crosscutting-conceptsin den Skill.Bewertung gegen die Projekt-Taxonomie
Contract/Skill-Grenze — Katalog-Evidenz
template-Feld incontracts.jsonSKILL.md+references/+prompts/architecture-documentation)arc42-authoring)Größenanalyse — der Ausreißer
architecture-documentationsocratic-code-theory-recoveryexplaining-teachingtdd-hamburg-stylearchitecture-documentationist der einzige Contract >1200 Zeichen ohne Begleit-Skill.socratic-code-theory-recoveryist ähnlich lang, aber gerechtfertigt als kondensierte Erinnerung seines Begleit-Skills — die prozedurale Tiefe lebt im Skill, nicht allein im Contract.Präzedenzfall: „invoke a skill for depth"-Pattern
Der
explaining-teaching-Contract (#573) beweist, dass dieses Pattern funktioniert:socratic-code-theory-recovery-SkillKonsistenz mit der Harness Inventory
Die Harness-Inventory-Seite (
docs/harness-inventory.adoc) trennt „was eine Schicht prüft" (Definition) von „wie man sie deployt" (Prozedur). Gleiche Linse: Contract = das Was, Skill = das Wie.Änderungen
1. Neuer Skill:
skill/arc42-authoring/Inhalt 1:1 extrahiert aus den aktuellen Contracts
architecture-documentationundcrosscutting-concepts. Keine Information geht verloren — nur umgezogen.2. Eingedampfter Contract:
architecture-documentationVon 2922 Zeichen → ~340 Zeichen:
3. Absorbiert:
crosscutting-conceptsVerschoben nach
skill/arc42-authoring/references/chapter-8-baseline.md. Der Contract-Eintrag wird auscontracts.jsonentfernt.4. Socratic-Überschneidung aufgelöst
Die
references/arc42.mddessocratic-code-theory-recovery-Skills enthält einen Phase-1-Dekompositions-Guide (Q-IDs, wann man aufhört zu dekomponieren) — das ist spezifisch für den Socratic-Workflow, nicht für arc42-Authoring. Keine Überschneidung — beide Skills koexistieren ohne Duplikation:arc42-authoringsocratic-code-theory-recoveryTrade-off anerkannt
Die Traceability-Regeln wandern von always-on zu on-demand. Für Architekturarbeit wird der Skill ohnehin aufgerufen — kein Verlust. Für jemanden, der den Contract nur als Erinnerung liest, war das Detail bereits zu umfangreich für always-on-Kontext — dies ist eine Korrektur, keine Regression (wie #529 feststellt).
Summary by CodeRabbit
Documentation
Chores