Architecture Decision Record · 0028

solcom-review Skill: PR-Review als dritte Review-Stage mit Hybrid-Standards-Achse

TL;DR — solcom-review eingeführt als manueller, in-session PR-Review-Skill (adaptiert von mattpocock/skills). Standards-Achse liest die 4 Code-Reviewer-Prompts als Rule-Korpora — spawnt sie nicht. Spec-Achse holt Jira-Story + PRD/Plan-HTMLs; bei PR-URL-Input zusätzlich Azure DevOps PR-Description. Dritte Review-Stage neben Decision-Time (customer-lens-reviewer) und Cloud-Post-PR (PR-Agent, ADR-0021).

Kontext

Das SOLCOM-Repo hat zwei bestehende Review-Kategorien:

Decision-time (customer-lens-reviewer) — vor Code, bei ≥2 Topologie-Optionen, drei Stakeholder-Lenses.
Diff-time / Post-PR (vier file-glob-getriggerte Agents + ADR-0021 PR-Agent) — nach Code-Schreibung, automatisch, cloud-seitig auf Azure DevOps PRs.

Fehlte: ein manueller, in-session PR-Review-Pass, der sowohl eigene als auch fremde PRs auf zwei spezifischen Achsen prüft:

Standards — entspricht der Code den SOLCOM-Konventionen (CLAUDE.md, ADRs, byte_theme/AGENTS.md, Reviewer-Prompts)?
Spec — implementiert der Code das, was die Jira-Story / das PRD verlangt hat?

PR-Agent (ADR-0021) deckt Standards und allgemeine Code-Qualität ab, hat aber kein SOLCOM-Domain-Wissen (keine ADR-Kenntnis, keine Jira-Spec-Anbindung, kein Zugriff auf docs/wiki/ oder die Reviewer-Prompts). Außerdem läuft PR-Agent automatisch post-PR in der Cloud — ein pre-push lokaler Pass fehlte.

Quelle des Upstream-Patterns: mattpocock/skills `review` (MIT). SOLCOM-spezifische Adaptionen: HTML-Strands statt Markdown, Jira P2503 via Atlassian-MCP, Azure DevOps PR-URL-Integration, --persist-Flag.

Entscheidung

solcom-review als dritte Review-Stage einführen. Zwei Entscheidungen sind zusammen load-bearing:

1. Dritte Review-Stage: PR-Review

Stage	Wann	Trigger	Tool	Output
Decision-time	Vor Code, bei Topologie-Entscheidung	Manuell ≥2 Optionen	`customer-lens-reviewer`	Structured review (3 Lenses)
PR-Review	Lokal, vor oder nach PR-Erstellung	Manuell (`/solcom-review`, PR-URL)	`solcom-review` Skill	In-session 2-Achsen-Report
Cloud-Post-PR	Bei jedem PR-Update auf Azure DevOps	Automatisch (Pipeline)	PR-Agent (ADR-0021)	Inline-Kommentare im PR

Input-Modi:

git-Diff — /solcom-review main oder /solcom-review <commit-sha>: klassischer git diff <fixed-point>...HEAD.
PR-URL — /solcom-review https://dev.azure.com/houseofhr/…/pullrequest/247: Skill holt via Azure DevOps REST API Source-Branch, Target-Branch, PR-Description und Linked Work Items; checkt Branch lokal aus (git fetch && git checkout <source-branch>); nutzt PR-Description als zusätzliche Spec-Quelle. Auth: AZURE_DEVOPS_PAT Env-Var.

2. Hybrid-Standards-Achse: Reviewer-Prompts als Rule-Korpora

Der Standards-Subagent liest die 4 Code-Reviewer-Prompts (.claude/agents/solcom-brand-reviewer.md, drupal-twig-sdc-reviewer.md, drupal-php-reviewer.md, drupal-config-architecture-reviewer.md) als Rule-Korpora — er spawnt sie nicht als Agents.

Begründung:

Die Diff-time-Reviewer-Agents haben ein festes JSON-Output-Schema (findings / severity / autofix_class / confidence) — ausgelegt für automatische Verarbeitung, nicht für in-session aggregierten Fließtext.
6 parallele Agent-Spawns (4 Reviewer + Standards-Global + Spec) würden einen Spawn-Storm erzeugen; 2 parallele Sub-Agents sind kompakter und für in-session-Review ausreichend.
Die Rule-Korpora-Lektüre liefert denselben Regelkatalog ohne den JSON-Overhead.
Die file-glob-Auto-Trigger der 4 Reviewer bleiben unverändert aktiv — kein Redundanz-Problem.

Rejected alternatives

Orchestrierend: alle 4 Reviewer-Agents spawnen + globaler Standards-Pass rejected

6 parallele Agents (4 Reviewer + 1 globaler Standards-Pass + 1 Spec). Hätte den Vorteil, die Reviewer 1:1 mit ihren eigenen Prompts laufen zu lassen. Abgelehnt wegen: (a) Spawn-Storm bei jedem Review-Run, (b) JSON-Output-Schema der Reviewer ist für in-session-Text ungeeignet — Aggregation würde eine eigene Parsing-Schicht benötigen, (c) Reviewer triggern sowieso file-glob-basiert bei jedem Commit, also würden Findings bei normalem Workflow ohnehin auftauchen.

Nur git-basiert, kein PR-URL-Input rejected

Einfacher, kein Azure DevOps API-Client nötig. Abgelehnt weil: fremde PRs reviewen ohne URL-Input bedeutet, Branch manuell auschecken + Fixed-Point erraten. PR-URL liefert gratis Source-Branch, Target-Branch, Linked Work Items und PR-Description als Spec-Quelle — zu wertvoll um darauf zu verzichten.

PR-Agent für alles — kein separater Skill rejected

PR-Agent läuft automatisch auf jedem PR und deckt allgemeine Code-Qualität ab. Kein SOLCOM-Domain-Wissen (kein Zugriff auf ADRs, docs/wiki/, Jira-Spec, Reviewer-Prompts als Regelwerk). Außerdem nur post-PR, kein lokaler pre-push Pass. Die zwei Tools decken unterschiedliche Bedürfnisse ab.

Eigenständige Standards-Achse ohne Reviewer-Prompt-Referenz rejected

Standards-Subagent liest nur CLAUDE.md, ADRs, byte_theme/AGENTS.md — ohne die 4 Reviewer-Prompts. Abgelehnt weil: die Reviewer-Prompts enthalten kondensierte, praxisbewährte Regelkataloge (z.B. die 13 CVA-Regeln im drupal-twig-sdc-reviewer) die im Standards-Pass relevanter sind als ein zweites Lesen von AGENTS.md.

Consequences

Drei Review-Stages sind klar getrennt — Decision-time / PR-Review / Cloud-Post-PR. Kein Overlap, aber auch keine Lücke.
Reviewer-Prompts müssen als Rule-Korpora geeignet bleiben — wenn ein Reviewer-Prompt künftig nur noch als JSON-Schema-enforcer umgeschrieben wird, verliert der Standards-Subagent den zugehörigen Regelkatalog. Reviewer-Prompt-Updates sollten den lesbaren Regeltext beibehalten.
AZURE_DEVOPS_PAT lokal erforderlich für PR-URL-Input — Code (Read) Scope. Kein neues Secret-Management, aber jeder der den Skill nutzen will muss das Token einmalig setzen.
Neuer optionaler Strand docs/reports/ entsteht beim ersten --persist-Run. Template: docs/_templates/03-code-review-pr.html. Der Strand braucht dann CLAUDE.md-Update (Karpathy-Tabelle) und INVENTORY.
Upstream-Divergenz — der Skill divergiert signifikant von mattpocock/upstream (_PROVENANCE.md dokumentiert Abweichungen). Kein 1:1-Sync geplant.