Architecture Decision Record · 0023

PRD-Decomposition: `to-plan` als Default, `to-issues` als Opt-in für Sub-tasks

Entscheidung. Neuer projekt-lokaler Skill to-plan wird Default für PRD-Decomposition im Solcom-Repo: Output ist ein HTML-Plan-Doc nach docs/plans/ mit Tracer-Bullet-Decomposition-Tabelle, kein Jira-Push. to-issues wird zum expliziten Opt-in umpositioniert — aufzurufen, wenn Sub-tasks in Jira gewollt sind.

Kontext

Karpathys LLM-Wiki-Pattern für docs/ ist etabliert (ADR-0022, HTML-First). PRD-Decomposition existierte bisher in drei Wegen, die alle Lücken aufweisen:

prd-to-plan (global) — schreibt Markdown nach ./plans/*.md. Kollidiert mit der HTML-First-Policy (ADR-0022) und mit dem docs/plans/-Strand (Repo-Root statt docs/, Markdown statt HTML, kein LOG/INDEX).
to-issues (projekt-lokal) — schreibt Jira-Sub-tasks unter einer PRD-Issue und einen Plan-Doc nach docs/plans/. Sub-tasks haben aber im Solcom-Solo-Setup (Stand Mai 2026) keinen klaren Konsumenten: keine AFK-Agents im Tagesgeschäft, kein Sprint-Modus, Stakeholder gucken auf PRD-Ebene, nicht Sub-task-Ebene.
html-doc-authoring direkt mit Template 16-implementation-plan.html — Format-Authority, aber die Tracer-Bullet-Methodik (vertical Slices, end-to-end-Path, HITL/AFK-Klassifikation) muss der Author selbst strukturieren. Keine Decomposition-Disziplin built-in.

Es fehlte ein Default-Skill für „PRD zerlegen, Plan-Doc only, kein Jira-Push", der die Tracer-Bullet-Methodik mitbringt.

Entscheidung

Wir etablieren einen neuen projekt-lokalen Skill to-plan als Default-Decomposition-Skill. Output: docs/plans/YYYY-MM-DD-NNN-feat-<slug>.html mit Tracer-Bullet-Decomposition-Tabelle. Kein Jira-Push.

to-issues bleibt erhalten, wird aber zum Opt-in-Skill umpositioniert: aufzurufen, wenn Sub-tasks explizit gewollt sind (AFK-Agent-Pickup, Sprint-Planung, externer Stakeholder-Druck auf Slice-Ebene).

Entstehende Skill-Topologie

Use-Case	Skill
PRD schreiben	`to-prd` (Jira-Issue + `docs/prds/*.html`)
Default: PRD zerlegen → Plan-Doc	*`to-plan` (nur `docs/plans/.html`)**
Opt-in: Sub-tasks in Jira	`to-issues` (Sub-tasks + Plan-Doc)
PRD-Skizze (kein Decomposition)	`html-doc-authoring` mit Template 14/15

Rejected alternatives

prd-to-plan (global) weiterhin nutzen rejected

Verworfen, weil Markdown im Repo-Root die HTML-First-Policy (ADR-0022) bricht. Der Lint-Skill solcom-docs-lint würde die entstehenden plans/*.md-Files als orphan + broken-strand flaggen. Außerdem fehlt dem globalen Skill die Kenntnis des Solcom-spezifischen docs/plans/-Strands (Naming-Konvention, LOG/INDEX-Pflege).

to-issues Refactor: to-plan als Basis, to-issues setzt darauf auf (Variante B) rejected

Elegantere Architektur: to-plan übernimmt die Decomposition-Logik, to-issues wird zum dünnen Wrapper, der nur noch den Jira-Push ergänzt. Weniger Skill-Duplizierung, klare Kompositions-Hierarchie.

Verworfen, weil ein unmittelbarer Refactor von to-issues direkt nach dem Bau von to-plan dem Memory-Feedback „Refactor ≠ Rewrite" widerspricht. Die Kosten (Refactor-Risiko, Regressions-Potential im Jira-Push-Pfad) überwiegen den Nutzen zum jetzigen Zeitpunkt. Kann nachgezogen werden, wenn der Use-Case sich verfestigt.

Status quo: kein to-plan, html-doc-authoring + Template-16 direkt rejected

Geringste Änderung: kein neuer Skill, der Author wählt Template-16 und strukturiert Tracer-Bullet-Slices selbst. Format-Authority bleibt bei html-doc-authoring.

Verworfen, weil Tracer-Bullet-Disziplin (vertical Slices, HITL/AFK-Marker, Acceptance-Criteria pro Slice) dann am Author hängt, nicht in einer Skill-Routine kodifiziert ist. Der Nutzen einer Routine ist Konsistenz über Sessions hinweg — die fehlt ohne Skill.

Neuer to-plan-Skill als Default-Decomposition-Pfad chosen

Diese Entscheidung. to-plan kapselt Tracer-Bullet-Methodik (vertical Slices, end-to-end-Path, HITL/AFK-Klassifikation, Acceptance-Criteria pro Slice) in einem projekt-lokalen Skill mit Auto-Trigger. Output ist immer HTML nach docs/plans/, immer mit LOG/INDEX-Eintrag, nie mit Jira-Push.

Gewählt, weil der fehlende Konsument für Sub-tasks im Solo-Setup (Stand Mai 2026) den Overhead von to-issues nicht rechtfertigt, und weil die Kodifizierung der Methodik in einem Skill Konsistenz über Sessions gewährleistet.

Consequences

+ Positives

to-plan ist der Default-Skill für PRD-Decomposition im Solcom-Repo — klare, kommunizierbare Regel.
Tracer-Bullet-Methodik (vertical Slices, HITL/AFK-Marker) ist in der Skill-Routine kodifiziert, nicht vom Author abhängig.
Kein Jira-Overhead für Slices, die keinen AFK-Konsumenten haben.
Plan-Docs bleiben HTML-First-konform, werden von solcom-docs-lint nicht als orphan geflaggt.
Wechsel zu to-issues ist low-cost, wenn AFK-Agent-Praxis aktiviert wird.

− Negatives / Risiken

Zwei Decomposition-Skills (to-plan, to-issues) mit ähnlicher Logik — Drift-Risiko, wenn eines aktualisiert wird und das andere nicht.
to-issues muss explizit als Opt-in markiert werden (Skill-Description + Top-Block der SKILL.md) — redaktionelle Pflege erforderlich.
Globaler prd-to-plan-Skill bleibt technisch verfügbar, kann versehentlich aufgerufen werden. Mitigation: CLAUDE.md-Hinweis und Skill-Trigger-Priorisierung.

Operative Folge-Maßnahmen

to-issues SKILL.md: Top-Block und description-Frontmatter explizit als Sub-task-Variante / Opt-in markieren.
html-doc-authoring Wrapper-Pflicht-Liste wird erweitert: to-plan und to-issues stehen in der „schreibt nach docs/"-Liste (beide pflegen LOG und INDEX).
Karpathy-LOG/INDEX-Konsistenz bleibt gewahrt: jeder neue Plan-Doc bekommt einen ingest-LOG-Eintrag und eine INDEX-Card im #plans-Strand.
Globalen prd-to-plan-Skill im Solcom-Kontext als unused markieren (CLAUDE.md-Hinweis).

Wenn AFK-Agent-Praxis später aktiviert wird, ist der Wechsel low-cost: User ruft to-issues statt to-plan — oder rückwirkend to-issues mit einem existierenden Plan-Doc als Input. Kein Umbau der Skill-Topologie erforderlich.