lukas/nixos-config
Archived
1
0
Fork 1
Code Issues Pull requests Releases Wiki Activity
This repository has been archived on 2026-09-17. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
nixos-config/docs/intent/reviewer-scale-depth-to-risk.md
pijukka 05575df408 docs: commit backlog of already-resolved intent/review corpus files 
board-agent's own README documents docs/intent/ and docs/research-intent/
as tracked corpus directories, and docs/review/<slug>.md as the reviewer's
persisted report per card - but the pipeline only writes these files to
the checkout, it never commits them itself. This had built up a backlog
of intent/review docs for cards already marked deployed or archiviert in
the live board state, which were sitting uncommitted in the working tree.

Adds that backlog as-is: the originating intents, their reviewer reports,
the research-intent/research pair for the board UX evaluation, and one
standalone process-retrospective report (board-review-pipeline-context-
overhead.md, same genre as the two already-tracked audit reports in
docs/review/). No code changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7UVrKsttMP9a6FiGFna9b
2026-09-10 12:06:53 +02:00

3.8 KiB
Raw Permalink Blame History

Intent: Reviewer-Prüftiefe und Berichtslänge am Diff-Risiko skalieren

Ziel

agents/reviewer.md so ergänzen, dass sich Prüftiefe und Berichtslänge am Risiko des geprüften Diffs orientieren, statt immer im vollen bisherigen Umfang zu laufen — kürzere Laufzeit und ein knapperer Bericht für triviale, risikoarme Änderungen, unverändert ausführliche Prüfung und Berichtsform für riskante Änderungen.

Hintergrund

Der Bericht docs/review/blunix-remove-ripgrep.md zu einer Ein-Zeilen-Änderung umfasste sieben nummerierte Prüfschritte sowie mehrere ausführliche Meta-Abschnitte (Prüfmethoden, nicht ausgeführte Prüfungen, Unsicherheiten). Der einzige substantielle Befund im Bericht kam aus dem repo-weiten git grep nach verbleibenden Referenzen auf den entfernten Bezeichner. Ziel dieser Karte ist, genau diesen wertvollen Kernschritt für jeden Review-Lauf zu erhalten, während der übrige Umfang und die Berichtsform mit dem tatsächlichen Risiko des Diffs skalieren.

Umfang / Auftrag an den Builder

  • In agents/reviewer.md ein Kriterium für „riskant" definieren: Die Änderung betrifft secrets/, eine Datei mit erkennbarem Netzwerk-, Firewall-, sshd- oder Auth-Bezug, eine systemd-Unit-Definition, oder umfasst mehr als eine Datei oder mehr als etwa 10 geänderte Zeilen. Trifft mindestens eines dieser Kriterien zu, gilt weiterhin die volle bisherige Prüftiefe und Berichtsstruktur, wie im Rollenvertrag heute beschrieben.
  • Für alle anderen (nicht-riskanten) Diffs ein verkürztes Berichtsformat vorschreiben: nur „Geprüfter Commit" (1–2 Zeilen), das Ergebnis des verpflichtenden git grep-Checks (siehe unten), Befunde (falls vorhanden), sowie Fazit und Entscheidung. Die mehrfachen Meta-Abschnitte („Tatsächlich ausgeführte Prüfmethoden" als nummerierte Liste, „Nicht ausgeführte Prüfungen", ausführliche „Unsicherheiten") entfallen oder werden zu höchstens einer Zeile zusammengefasst.
  • Unabhängig davon, ob der Diff als riskant oder nicht-riskant eingestuft wird, bleibt ein git grep nach dem geänderten Bezeichner (z. B. Paket- oder Optionsname) über den Commit-Baum ein verpflichtender Mindestschritt — dieser Check darf durch die Kürzung nicht wegfallen.

Ausgeschlossen

  • Keine Änderung an der Auslöse-/Watcher-Infrastruktur (completion_watcher.py, systemd.paths-Einheiten) — für zusätzliche Latenzursachen dort gibt es keinen verifizierten Befund, nur Vermutung.
  • Kein Eingriff in das Marker-Block-Format (===REVIEW-REPORT===...===END-REVIEW-REPORT===) oder die Entscheidungs-Zeilen-Erkennung in worker.py — die muss mit beiden Berichtsformaten unverändert funktionieren.

Annahmen

  • Der Zeilenschwellenwert (~10 Zeilen) und die Datei-Anzahl-Grenze (mehr als eine Datei) sind ein pragmatischer Startwert, keine empirisch hergeleitete Zahl — bei Bedarf später nachjustierbar.

Offene Risiken

  • Eine zu niedrig angesetzte Risiko-Schwelle könnte künftig einen eigentlich riskanten Diff fälschlich ins Kurzformat einsortieren. Der verpflichtende git grep-Schritt mindert dieses Risiko, ersetzt aber nicht die volle Prüftiefe bei echten Risikokandidaten.

Erfolgskriterien

  • agents/reviewer.md enthält die Risiko-Kriterien und beide Berichtsformate klar unterschieden.
  • Ein nachfolgender trivialer Board-Review erzeugt sichtbar einen kürzeren Bericht als das bisherige volle Format.
  • Dieser Intent dient zugleich als Pipeline-Test: Er wird als dritte von drei zusammengehörigen Karten (nach docs/intent/planner-precise-package-removal-scope.md) durch geplant → in_umsetzung gezogen. Ihr eigener Review-Durchlauf nutzt noch den bisherigen Stand von agents/reviewer.md (die neue Fassung ist zu diesem Zeitpunkt noch nicht deployed) — das ist erwartet, kein Fehler.