Architecture Decision Record

External-context snapshots in `docs/context/` mit Ingestion- und Discovery-Agents

Externes Referenz-Material wird als versionierte Markdown-Snapshots unter docs/context/ abgelegt, gepflegt durch ein dreiteiliges Bundle: Skill solcom-docs-context, Agent solcom-docs-ingestion, Agent solcom-docs-explorer.

Kontext

Im SOLCOM-Repo lebt produktrelevantes Wissen bisher in mehreren docs/-Strängen: CONTEXT.md (Domain-Glossar + ADR-Index), docs/adr/, docs/plans/, docs/prds/, docs/brainstorms/, docs/agents/, .claude/memory/ (ADR-0006).

Was fehlt: ein Anker für externes Referenz-Material, das von außerhalb des Repos kommt und für Code-/Design-Entscheidungen load-bearing ist. Konkrete Quellen: IT-Landschaft-Diagramme aus Miro, Workshop-Outputs (Whiteboard-Fotos, Slack-Uploads), externe Vendor-/Stakeholder-Specs (z. B. Personio-API-Spec), Onboarding-Decks (PowerPoint, Keynote), Confluence-/SharePoint-Snapshots. Diese Quellen leben heute in fremden Tools — Devs und Agenten haben keinen verlässlichen, diff-baren Zugriff.

Parallel dazu werden bei Planungs-Aufgaben bestehende docs/-Inhalte aus mehreren Strängen oft übersehen. Es gibt kein etabliertes Discovery-Pattern, das vor dem ersten Plan-Schritt sicherstellt, dass kein bereits dokumentierter Kontext verloren geht.

Pattern-Vorbild: ADR-0012 (solcom-build-frontend) hat gezeigt, dass ein neues Workflow-Bundle aus Skill + Agent(s) + docs-Konvention durch ein eigenes ADR begleitet wird.

Entscheidung

Folder-Konvention: docs/context/0NNN-kebab-name.md, fortlaufende dreistellige Nummer, nicht wiederverwendet (analog ADR-Naming). Snapshot-Originale (PDF/PNG/PPTX) werden nicht ins Repo committed — der source-Frontmatter-Eintrag hält den Pointer.
Frontmatter-Pflichtfelder: title, source, source_type (miro|confluence|pdf|pptx|docx|png|sharepoint|slack-upload|other), captured (ISO-Datum), last_synced (ISO-Datum), tags (knapp, konsistent), supersedes (frühere Nummer oder null). Bewusst nicht übernommen: das 4-Sektionen-ADR-Schema.
Inventar: docs/context/INVENTORY.md — eine Tabellenzeile pro Snapshot. Wird beim Session-Start automatisch via CLAUDE.md/AGENTS.md mitgelesen (auto-load), einzelne Snapshots werden lazy nachgeladen. Abgelöste Einträge bleiben in der Tabelle, durchgestrichen, mit Verweis auf den Nachfolger.
Skill solcom-docs-context (.claude/skills/solcom-docs-context/SKILL.md) ist die Source-of-Truth für Format, Naming, Intake-Workflow, Re-Sync-Regeln und Abgrenzung zu anderen docs/-Strängen.
Agent solcom-docs-ingestion (.claude/agents/solcom-docs-ingestion.md, model: sonnet) ist der operative Intake-Agent. Trigger: User übergibt Quelle. Workflow: Quelle lesen → Markdown mit Frontmatter draften → nächste 0NNN zuweisen → INVENTORY-Zeile anhängen → Diff zur User-Review zeigen. Committet nicht selbst.
Agent solcom-docs-explorer (.claude/agents/solcom-docs-explorer.md, model: sonnet) ist der proaktive Cross-Strand-Discovery-Agent. Trigger: jeder Planungs-Schritt. Suchbereich: docs/{context,adr,plans,prds,brainstorms}/ (nicht docs/agents/, nicht Code, nicht .claude/). Output: strukturierter Discovery-Report mit relevanten Snippets pro Strang, Lücken-Hinweisen und empfohlener Lese-Reihenfolge. Read-only.
Auto-Load-Verankerung: AGENTS.md bekommt eine Sektion „External context (docs/context/)" die INVENTORY.md als Pflicht-Erstanlauf bei Architektur-/Plan-Sessions ausweist und auf beide Agents verlinkt.
Agent-Boundaries: docs/context/** inkl. INVENTORY.md wird in die „Refactoring skills must never edit documentation"-Klausel aufgenommen. Snapshots sind editorial.
Glossar-Eintrag: „External context snapshot" wird in CONTEXT.md aufgenommen, mit der Abgrenzung „kein ADR (keine eigene Entscheidung), kein Plan (keine Implementierungsschritte) — konservierter Snapshot fremder Inhalte".

Rejected alternatives

rejected Step-0 in bestehenden Planning-Skills statt Discovery-Agent

Jeder Skill müsste separat gepflegt werden und Drift wäre wahrscheinlich. Der Discovery-Output bekäme kein eigenes Output-Schema. Ein eigener Sub-Agent in einem separaten Context-Window verhindert, dass das Plan-Drafting durch zu viel Doku-Material überladen wird.

rejected Ein einzelner Agent für Ingestion und Discovery zusammen

Beide Modi haben unterschiedliche Trigger, unterschiedliche Tool-Sets (Ingestion braucht Edit/Write, Discovery ist read-only) und unterschiedliche Output-Formate. Konsolidierung würde die Agent-Definition unnötig groß und vage machen.

rejected Discovery-Subagent erst nach ≥5 Snapshots in docs/context/ bauen

Verworfen, weil der Explorer auch ohne docs/context/-Material die anderen vier docs/-Stränge durchsucht und sofort Wert liefert. Das Pattern „beim Planen erst mal docs/ durchschauen" ist von Tag 1 an wertvoll.

rejected Originale (PDF/PNG/PPTX) ins Repo committen

Repo-Größe wächst schnell. Die source-Pointer-Strategie reicht; Re-Sync erfordert ohnehin den Original-Zugriff. Snapshot-MD trägt die kondensierten Inhalte, nicht die Originale.

rejected MEMORY.md als Filename statt INVENTORY.md

Namenskollision mit dem etablierten .claude/memory/MEMORY.md-Index aus ADR-0006. Zwei MEMORY.md mit unterschiedlicher Semantik im selben Repo wäre verwirrend.

rejected Snapshots im 4-Sektionen-ADR-Format strukturieren

ADRs sind Trade-off-Dokumente mit fester Schablone, Snapshots sind Quellen-Treue mit variabler Struktur. Eine Schablone würde die Treue zur Originalquelle untergraben.

Consequences

Onboarding-Erlebnis verbessert sich: neue Devs sehen beim Session-Start INVENTORY.md mitgeladen und können sich gezielt einzelne Snapshots holen, ohne in Miro/Confluence einzuloggen.
Pflege-Pflicht entsteht: wenn eine Quelle sich ändert, ist Re-Sync via neuem Eintrag mit supersedes nötig. last_synced-Spalte in INVENTORY.md macht Drift sichtbar; ohne aktiven Re-Sync veralten Snapshots stillschweigend.
Discovery-Overhead bei Planungs-Sessions: der Explorer-Aufruf kostet einen separaten Subagent-Roundtrip mit Sonnet-Compute, bevor der eigentliche Plan-Workflow startet. Akzeptiert, weil das Risiko, übersehene Vor-Entscheidungen erst im Code zu entdecken, deutlich teurer ist.
Vier Workflow-Skills (write-a-prd, prd-to-plan, request-refactor-plan, improve-codebase-architecture) sollten den Explorer proaktiv als ersten Schritt aufrufen. Diese Verdrahtung passiert nicht automatisch — sie wird über die jeweiligen Skill-Texte und über die Sektion „External context" in AGENTS.md kommuniziert.
Bewusste Restrisiken: Drift zwischen Snapshot und Originalquelle ist ohne Re-Sync-Disziplin unvermeidlich. NDA-/kundenvertrauliches Material könnte versehentlich ingested werden — Skill-Text warnt explizit, aber technisch nicht enforced. Variabler Body schwächt automatische Auswertbarkeit.
Pattern-Konsistenz mit ADR-0006 und ADR-0012 gewahrt: .claude/memory/ (Code-Patterns) und docs/context/ (externe Snapshots) bleiben semantisch getrennt; das Workflow-Bundle-Pattern (Skill + Agents + docs-Konvention) folgt dem Vorbild von solcom-build-frontend.