Benjamin Admin
78f0ffa9de
Roadmap item 4. After WHAT applies / WHAT is missing / WHICH first, the GF asks HOW. The Implementation Playbook renders, for one capability, the full journey — why / which regulations it closes / tools / process / evidence / controls — and chains the Optimization Roadmap into per-measure playbooks. Another renderer over the same Capability spine (ADR-003/004), not a new engine: ~95% of the data already exists, it just needs a different rendering. - compliance/playbook/: build_playbook() + playbooks_for_plan() (chains optimization -> playbook, acyclic; reuses leverage for "closes which regulations"). Capabilities without curated content render as honest status:missing stubs — the content-owed signal. - knowledge/implementation_playbooks/: curated knowledge layer (Reasoning Knowledge Acquisition), two deep expert drafts (SBOM, CVD/PSIRT, status draft, expert-draft-not-normative) + README. The bottleneck is now CONTENT, not software; Playbook (own knowledge) != regulatory domain. - ADR-004: Implementation Playbooks = renderer + knowledge layer; content is the bottleneck. - reference suite: "Implementation Playbook" section renders the SBOM journey + Roadmap->Playbook table (high-leverage caps flagged "fehlt (Inhalt)" — content backlog, highest leverage first). - refactor: extracted markdown helpers to reference_scenarios/_helpers.py to keep generate.py under the 500-LOC budget. 9 playbook tests (40 with optimization+transition+company), mypy --strict clean, check-loc 0. Product code with no app caller + knowledge/ADR/reference = non-runtime -> no deploy (ADR-001). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
52 lines
3.4 KiB
Markdown
52 lines
3.4 KiB
Markdown
# ADR-004: Implementation Playbooks — a renderer plus a knowledge layer
|
|
|
|
- **Status:** Accepted
|
|
- **Datum:** 2026-06-27
|
|
- **Typ:** Architektur-Entscheidung
|
|
- **Bezug:** [ADR-003](ADR-003-capability-delta-engine-with-renderers.md), [ADR-002](ADR-002-transition-is-data-not-architecture.md), Architektur-Freeze v1.0, [[transition-reasoning]]
|
|
|
|
## Kontext
|
|
|
|
BreakPilot beantwortet inzwischen drei Fragen: *Was gilt?* (Reasoning), *Was fehlt?*
|
|
(Capability Delta), *Womit anfangen?* (Optimization). Danach fragt der Geschäftsführer fast immer:
|
|
**„Wie komme ich dort hin?"** — nicht *was*, sondern *wie* (z. B. „Top-Maßnahme: PSIRT — und wie
|
|
baue ich einen PSIRT auf? Welche Tools? Wie machen das andere?").
|
|
|
|
Diese Umsetzungs-Ebene ist weder Reasoning noch Gap noch Roadmap. Das Risiko: sie als neue Engine
|
|
zu bauen — obwohl ~95 % der Daten bereits existieren (`Capability → Procedure → Control → Evidence`).
|
|
Sie muss nur **anders gerendert** werden.
|
|
|
|
## Entscheidung
|
|
|
|
1. **Ein Implementation Playbook ist ein RENDERER über einer Capability** (`compliance/playbook`),
|
|
kein neuer Datenpfad. Es setzt die Reise zusammen aus: kuratiertem Playbook-Wissen + der
|
|
regulatorischen **Leverage** (welche Regelwerke eine umgesetzte Capability schließt, aus der
|
|
Optimization) + **injizierten** Procedure/Control/Evidence-Links (Execution-owned).
|
|
|
|
2. **Playbook ≠ regulatorische Domäne (bewusste Unterscheidung):**
|
|
- Ein **Playbook** ist BreakPilots EIGENE Wissensschicht (`Capability → empfohlene Vorgehensweise
|
|
→ Tools → Prozess → typische Nachweise → Controls`). Es führt KEIN neues Regelwerk ein.
|
|
- Eine **regulatorische Domäne** (z. B. ISO 14001 → Umweltrecht) ist neues *regulatorisches*
|
|
Wissen (Obligations, Anwendbarkeit), Eigentum von Legal Knowledge / Execution.
|
|
Beide skalieren unabhängig — und jede neue Domäne dockt sofort an denselben Playbook-Mechanismus an.
|
|
|
|
3. **Der Engpass ist INHALT, nicht Software.** Der Renderer ist klein und fertig; der Wert wächst mit
|
|
Zahl und Tiefe der Playbooks. Eine Capability ohne Playbook rendert als `status: missing`-Stub —
|
|
das ehrliche „Content owed"-Signal. Playbook-Inhalt ist Reasoning-**Knowledge-Acquisition**
|
|
(wie `knowledge/transition_patterns/`): KI liefert den Erstentwurf, BreakPilot reviewt/versioniert/besitzt.
|
|
|
|
## Konsequenzen
|
|
|
|
- **Aus Diagnose wird Beratung:** derselbe Capability-Strang, der Auditor-Fragen (Interview) und
|
|
GF-Maßnahmen (Roadmap) liefert, liefert nun auch die Umsetzungsreise (Playbook). Konsistent mit
|
|
ADR-003 (ein Modell, viele Renderer).
|
|
- **Reifegrad + Ehrlichkeit:** Playbook-Inhalt ist `draft → reviewed → validated → proven`, ein
|
|
**Experten-Entwurf, KEINE normative Anforderung**; Tools/Schritte sind Empfehlungen. Controls
|
|
werden aus Execution injiziert — keine Execution-Daten im Reasoning-Produktcode.
|
|
- **Freeze-konform:** kein neues Metamodell, kein neuer Graph, kein neuer Corpus — `Playbook` ist
|
|
eine abgeleitete Sicht (computed-not-stored). Abhängigkeit `playbook → optimization →
|
|
transition_reasoning` ist azyklisch; die Capability Delta Engine bleibt hermetisch.
|
|
- **Priorisierung:** Playbooks kommen VOR neuen Domänen (ISO 14001), damit jede künftige Capability
|
|
sofort eine Umsetzungsreise bekommt. Content-Backlog = höchster Hebel zuerst.
|
|
- Diese ADR ist non-runtime → kein Deploy (siehe [ADR-001](ADR-001-runtime-deploy-policy.md)).
|