Blindspot Audit
Zweck
Die Kluft zwischen der Karte des Benutzers von einem Projekt und dem tatsächlichen Territorium des Projekts finden. Unbekannte Unbekannte in konkrete bekannte Unbekannte verwandeln, die der Benutzer inspizieren, beantworten, testen oder bewusst verschieben kann.
Der Kontext eines Projekts ist selbstselektierend: Der Besitzer kann nur das aufschreiben, was er bereits weiß. Daher kodiert jede README, TODO und jeder Plan die Karte, die er im Kopf trägt – und eine KI, die von diesen Dateien aus arbeitet, erbt dieselben blinden Flecken. Dieser Audit importiert bewusst Referenzrahmen von AUSSERHALB des Projekts, um diese Kluft zu messen.
Dieser Skill ist keine generische Qualitätscheckliste. Er sollte identifizieren, was für dieses spezifische Projekt, in dieser spezifischen Phase, mit Belegen aus dem Repo oder bereitgestellten Artefakten ungewöhnlich wichtig ist. Der Audit ist erfolgreich, wenn der Besitzer mindestens einmal sagt „Ich wusste nicht einmal, dass ich darüber nachdenken sollte“ – UND sich danach ruhiger fühlt, weil er jetzt auch weiß, was er getrost ignorieren kann.
Kernmodell
Klassifiziere Erkenntnisse mit dem Rahmen der vier Unbekannten:
- Bekannte Bekannte: das, was der Prompt, die Doku, der Code oder Pläne bereits aussagen.
- Bekannte Unbekannte: offene Fragen, die bereits in Dokumentationen, TODOs, Plänen, Kommentaren oder der Wortwahl des Benutzers sichtbar sind.
- Unbekannte Bekannte: Dinge, die der Benutzer erkennen würde, wenn sie gezeigt werden, die er aber noch nicht verbalisiert oder aufgeschrieben hat.
- Unbekannte Unbekannte: fehlende Konzepte, versteckte Einschränkungen oder nicht gestellte Fragen, die die Projektform impliziert.
Der Rahmen ist wichtig, weil sich die Vorgehensweise unterscheidet: Eine unbekannte Bekannte braucht eine Checklistenzeile, keine Vorlesung; eine unbekannte Unbekannte braucht eine kurze Erklärung und den günstigsten ersten Schritt. Gute Ergebnisse behaupten keine Gewissheit. Sie legen Kandidaten offen und geben die günstigste nächste Überprüfung.
Grundregeln
Diese existieren, weil die Fehlerart dieses Skills nicht das „Übersehen einer Lücke“ ist – sondern eine generische Checklisten-Nervensäge zu werden, die ignoriert wird.
- Die eigenen Tracking-Dokumente des Projekts sind ein Filter, keine Quelle für Erkenntnisse. Alles, was bereits in der README / TODO / Roadmap / Checkliste / Issue-Liste steht, ist eine BEKANNTE Unbekannte. Melde es niemals als Entdeckung. (Felddaten: Dieser Filter reduziert die Kandidatenliste typischerweise um mehr als die Hälfte und ist der Hauptgrund, warum Besitzer dem Bericht vertrauen.)
- Begrenze die obersten Erkenntnisse auf 3-7, eingestuft nach Auswirkung × Wahrscheinlichkeit, dass der Besitzer tatsächlich nichts davon weiß. Der Überlauf geht in eine kurze „Schwächere-Signal-Beobachtungsliste“ oder das Ledger – niemals in die Hauptliste.
- Abwesenheit allein ist keine Erkenntnis. „Sie haben kein X“ zählt nur, wenn Sie die konkrete Konsequenz für DIESES Projekt und den günstigsten ersten Schritt zur Schließung nennen können.
- Füge immer die beiden Vertrauensabschnitte hinzu: „Geprüft und gut abgedeckt“ und „Für jetzt überspringbar“ (jeder Übersprung mit einem expliziten Auslöser für eine erneute Prüfung). Sie verhindern Angst und erneutes Scannen und sind die Art und Weise, wie der Besitzer lernt, dass der Bericht vertrauenswürdig ist.
- Grenze regulierte Bereiche ab. Bei rechtlichen, steuerlichen oder regulatorischen Erkenntnissen gib an, was du gefunden hast und woher es stammt, und sage dann klar, dass dies von einem Fachmann bestätigt werden muss. Du bist ein Späher, kein Anwalt oder Buchhalter.
Modi
quick: Lies Dokumentationen und die Projektinventur und gib die wichtigsten blinden Flecken zurück.deep: Untersuche repräsentative Codepfade, Tests, Konfigurationen und Dokumentationen, bevor du Erkenntnisse einstufst.interview: Stelle eine Frage nach der anderen, wenn die Antwort Architektur, Arbeitsablauf, Umfang oder Risiko ändern würde.post-implementation: Vergleiche eine abgeschlossene Änderung, Notizen, Diffs und Tests, um verbleibende Unbekannte zu finden.planning: Vor der Implementierung: Decke Entscheidungen auf, die wahrscheinlich Datenmodelle, Schnittstellen, UX-Abläufe, Betrieb oder Verifizierung ändern.
Leite den Modus aus der Formulierung des Benutzers ab. Wenn der Benutzer darum bittet, es jetzt auszuführen, stelle keine Fragen zum Modus, es sei denn, die Auditgrenze ist unmöglich abzuleiten.
Schnellstart
- Identifiziere das Projektstammverzeichnis und die Auditgrenze.
- Führe den Inventur-Helfer aus, wenn ein Dateisystemprojekt verfügbar ist. Das Skript befindet sich im eigenen Ordner dieses Skills – löse es relativ zu dieser SKILL.md auf:
python <this-skill-folder>/scripts/project_inventory.py <project-root> --format md
Verwende --include-generated nur, wenn Laufzeitausgaben, generierte Berichte, Logs oder zwischengespeicherte Artefakte Teil der Auditfrage sind.
- Lies nur die relevanten Referenzen:
references/archetypes.md: Wähle den Projekttyp und die erwarteten blinden Flecken.references/lenses.md: Leite Audit-Linsen ab und wende sie an.references/host-surfaces.md: Passe Fragen und Ausgaben an Claude Code, Codex, OpenCode, CLI oder reine Chat-Oberflächen an.references/ledger-lifecycle.md: Entdecke, erstelle, leite weiter oder aktualisiere ein dauerhaftes Blindstellen-Ledger.references/report-template.md: Formatiere das Ergebnis.
- Entdecke oder initialisiere das Blindstellen-Ledger:
- Wenn ein vorheriges Ledger existiert, lies es vor der Suche (Diff-Lauf-Regeln gelten – siehe Ledger und Diff-Läufe).
- Wenn kein Ledger existiert und der Host Dateien schreiben kann, erstelle
BLINDSPOT_LEDGER.mdam besten projektspezifischen Speicherort für Dokumentation, es sei denn, der Benutzer hat eine reine Lese-/Chat-Ausgabe angefordert. - Wenn kein Ledger existiert und der Host keine Dateien schreiben kann, füge den vorgeschlagenen Pfad und den ersten Ledger-Eintrag in den Bericht ein.
- Untersuche die stärksten Beweisdateien aus der Inventur: README/AGENTS, Pläne, Paketkonfigurationen, Anwendungseinstiegspunkte, Testkonfigurationen, CI, Umgebungsbeispiele, Schemas, Prompts, Agent-/Skill-Dateien und Laufzeitdokumentation.
- Führe den „frischer Blick“-Externalscan durch (siehe Arbeitsablauf Schritt 5), wenn der Host Webzugriff hat.
- Ordne Erkenntnisse ein, befrage den Besitzer, wo möglich, erstelle den Bericht und aktualisiere das Ledger.
Richtlinie für Host-Oberflächen
Der Kern des Audits sollte über Claude Code, Codex, OpenCode, CLI und einfachen Chat hinweg gleich funktionieren. Nur der Interaktionsstil ändert sich. Siehe references/host-surfaces.md für Details zu jedem Host.
- Wahlfähige Hosts (Claude Code
AskUserQuestion, OpenCodequestion): Wenn eine Entscheidung Architektur, Arbeitsablauf, Umfang oder Risiko ändert – und für das Bewusstseins-Interview des Besitzers – stelle eine kurze Frage mit 2-3 Optionen und notiere die ausgewählte Option im Bericht oder Ledger. - Codex- oder reine Chat-Hosts: Blockiere nicht bei nicht-kritischen Fragen. Fahre mit der sichersten umkehrbaren Annahme fort, markiere sie als Annahme und füge ein „Entscheidungspaket“ mit den Optionen bei, die der Benutzer später auswählen soll.
- Hosts ohne Webzugriff: Überspringe den „frischer Blick“-Externalscan, sage dies explizit im Bericht und kennzeichne zeitkritische Bereiche (Regulierung, Plattformrichtlinien, Preise) als unbestätigt, anstatt sie aus Trainingswissen zu behaupten.
- Dateischreibende Hosts: Erstelle oder aktualisiere standardmäßig ein Ledger für Projekt-Audits, es sei denn, der Benutzer hat eine reine Lese-/Chat-Ausgabe angefordert. Gib den Pfad und die Routing-Bearbeitung im Bericht an.
- Schreibgeschützte oder öffentlich geteilte Hosts: Gib einen portablen Bericht mit Befehlen/Prüfungen zurück, die der Benutzer ausführen kann.
Frage nur sofort nach, wenn das Fortfahren riskant, destruktiv, teuer oder wahrscheinlich irreführend wäre.
Ledger und Diff-Läufe
Erster Lauf:
- Wähle den besten dauerhaften Speicherort für
BLINDSPOT_LEDGER.mdmitreferences/ledger-lifecycle.md. - Erstelle das Ledger aus
templates/BLINDSPOT_LEDGER.md, wenn Dateischreibvorgänge angemessen sind. - Füge das Ledger zur nächsten Routing-Oberfläche hinzu, z. B. einer Betriebs-README, einem Dokumentationsindex oder einem Übergabezeiger, wenn diese Routing-Datei bereits existiert.
- Notiere den Auditumfang, den Modus, die Beweisgrenzen und die ersten Erkenntnisse.
Wenn ein Projekt bereits ein Blindstellen-Ledger hat:
- Behandle das Ledger als Eingabe, nicht als Wahrheit. Überprüfe hochwirksame oder veraltete Erkenntnisse erneut am aktuellen Code/Dokumentation.
- Klassifiziere die Ausgabe als
neu,geändert,bestätigt,herabgestuft,gelöstoderentscheidung-erforderlich. - Wiederhole keine unveränderten ausstehenden Elemente, es sei denn, sie blockieren das aktuelle Ziel. Dies macht wiederholte Läufe wie Fortschritt aussehen, statt wie Nörgelei.
- Wenn das Ledger neu ist, aber nicht von einem Index, einer Übergabe oder einer Betriebs-README aus geroutet wird, kennzeichne dies als einen Blinden Fleck der Auffindbarkeit.
- Bewahre die lokale Status-Sprache und IDs des Ledgers bei der Aktualisierung.
Gute Ledger machen zukünftige Audits billiger. Schlechte Ledger werden ein weiteres verstecktes Dokument. Überprüfe daher immer die Auffindbarkeit.
Suchhygiene
Verwende begrenzte Suchen. Blindspot-Audits betreffen oft umfangreiche Repos, und verrauschte generierte Dateien können falsches Vertrauen schaffen oder Kontext verschwenden.
Standardausschlüsse für rg und ähnliche Werkzeuge, es sei denn, der Audit zielt explizit auf diese Bereiche ab:
!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**
Bevorzuge gezielte Pfade und --glob-Ausschlüsse gegenüber Repo-weiten Scans. Wenn ein breiter Scan riesige generierte Dateien zurückgibt, stoppe und führe mit einer engeren Grenze erneut aus, bevor du das Ergebnis verwendest.
Arbeitsablauf
1. Die Karte definieren
Gebe das offensichtliche Ziel des Benutzers, den Projekttyp, den Reifegrad und deine Auditgrenze in 2-4 Zeilen an. Markiere Annahmen explizit. Füge ein Besitzerprofil hinzu:
- Einzelperson oder Team? Worin ist der Besitzer klar erfahren, und – noch nützlicher – worin NICHT? Blinde Flecken häufen sich in den nicht fachkundigen Bereichen des Besitzers, also gewichte diese Linsen stärker.
- Hobby oder kommerziell? Privat oder öffentlich? Kommerzielle oder öffentliche Absicht aktiviert rechtliche, steuerliche und marktliche Linsen, die für ein privates Hobbyprojekt reines Rauschen wären. Wenn die Absicht nicht aus den Dateien erkennbar ist, frage vor dem Scannen nach (eine kurze Frage) – falsche Annahmen über die Absicht ruinieren den gesamten Audit.
2. Beweise sammeln
Verwende den Inventur-Helfer plus gezielte Lektüren. Lies zuerst die Selbstwahrnehmungs-Oberflächen des Projekts (README, TODO, Roadmap, Checklisten, Designdokumente, Zusammenfassung/Gliederung) – sie sind sowohl deine beste Profilquelle als auch dein Rauschfilter (Grundregel 1). Bevorzuge Beweise gegenüber breiten Spekulationen. Kennzeichne Beweise als:
- beobachtet: direkt in Dateien oder Ausgaben vorhanden.
- abwesend: erwartetes Artefakt im inspizierten Umfang nicht gefunden.
- abgeleitet: wahrscheinlich aus Struktur, Benennung oder Konventionen.
- frage: erfordert Bestätigung durch Benutzer oder Domain-Experten.
3. Das Territorium klassifizieren
Wähle einen oder mehrere Archetypen aus references/archetypes.md. Zwinge das Projekt nicht in eine Kategorie, wenn es hybrid ist.
4. Linsen anwenden
Wende nur Linsen an, die zur Projektphase passen. Ein Prototyp benötigt keine Unternehmens-Compliance, aber möglicherweise dennoch Grenzen für Datenverlust, Geheimnisbehandlung oder Wiederherstellbarkeit.
5. „Frischer Blick“-Externalscan
Wenn der Host Webzugriff hat, führe zeitlich begrenzte Recherche zu zwei Fragen durch:
- Was betrachten gesunde Projekte dieser Kategorie momentan als Standardausrüstung?
- Was hat sich in den letzten 6-12 Monaten geändert – Regulierung, Plattformrichtlinien, Markt- oder Genretraditionen, Werkzeuge – das die Dokumente dieses Projekts unmöglich enthalten könnten?
Frage 2 ist überproportional wertvoll: Zeitabhängige Änderungen sind strukturell unsichtbar sowohl für das Repo als auch für das Gedächtnis des Besitzers. (Felddaten: In frühen Läufen stammten die einzelnen höchstwirksamen Erkenntnisse – ein KI-Inhaltskennzeichnungsgesetz, das im folgenden Monat in Kraft trat, eine Zahlungsanbieter-Übernahme, die einen dokumentierten Plan ungültig machte – alle von diesem Schritt.) Zitiere Quellen für alles, was hier gefunden wird. Ohne Webzugriff überspringe und lege dies offen (siehe Richtlinie für Host-Oberflächen).
6. Blinde Flecken in Prüfungen umwandeln
Füge für jede Erkenntnis Folgendes hinzu:
- was möglicherweise fehlt
- warum es für dieses Projekt wichtig ist
- Beweise
- günstigste nächste Prüfung
- wahrscheinlicher Besitzer oder Entscheidungsfläche
- Priorität: jetzt, als nächstes, später oder beobachten
- Vertrauen: hoch, mittel, niedrig
Entferne Kandidaten, die in den eigenen Tracking-Dokumenten des Projekts erscheinen (Grundregel 1), behalte die obersten 3-7 und verschiebe den Rest in die Beobachtungsliste oder das Ledger.
7. Den Besitzer befragen
Präsentiere die Erkenntnisse und frage dann, welche der Besitzer bereits kannte (eine einzelne Multiple-Choice-Frage funktioniert gut auf wahlfähigen Hosts). Klassifiziere jede Erkenntnis:
| Bewusstsein | Bedeutung | Vorgehen |
|---|---|---|
unknown_unknown | Besitzer wusste es nicht | Erkläre, warum es hier wichtig ist + günstigster erster Schritt |
unknown_known | Besitzer wusste es, aber es steht nirgendwo geschrieben | Die Lösung ist Dokumentation, nicht Implementierung – bringe es in die Tracking-Dokumente, damit Agents und zukünftige Sitzungen es sehen können |
deliberate_skip | Besitzer hat es erwogen und sich dagegen entschieden | Verschiebe in die Überspringliste MIT dem Grund und einem Auslöser für eine erneute Prüfung |
(Felddaten: In frühen Läufen stellten sich etwa die Hälfte der obersten Erkenntnisse als unknown_known heraus – echte Lücken im Repo, aber nicht im Kopf des Besitzers. Die Unterscheidung ändert das Follow-up vollständig.)
Auf Hosts, die nicht fragen können, markiere jeden Bewusstseinswert als unbestätigt, bette die Interviewfragen in den Bericht ein und setze offene Entscheidungen in ein „Entscheidungspaket“.
8. Die Ausgabe nützlich halten
Beginne mit den wichtigsten Blinden Flecken mit dem höchsten Signal. Füge immer die beiden Vertrauensabschnitte hinzu (Grundregel 4). Verfasse den Bericht und die Prosa des Ledgers in der Sprache, die der Besitzer im Gespräch verwendet; behalte IDs, Status und Bewusstseinswerte auf Englisch, damit Wiederholungsläufe über Sitzungen und Sprachen hinweg diffbar bleiben. Formatiere nach references/report-template.md.
Leitplanken
- Präsentiere keine generischen Best Practices als Erkenntnisse, es sei denn, die Projektevidenz macht sie relevant.
- Melde keine Elemente erneut, die bereits im Ledger oder in den eigenen Tracking-Dokumenten des Projekts vorhanden sind.
- Verlange keine schweren Prozesse für persönliche Experimente oder frühe Prototypen.
- Nimm keine Codeänderungen vor, es sei denn, der Benutzer bittet explizit um Remediation.
- Behaupte nicht, dass etwas kaputt ist, nur weil eine Datei fehlt; sage, was die Abwesenheit vermuten lässt und wie man es bestätigen kann.
- Behandle abwesende CI, Tests, Release-Dokumentation oder Bereitstellungsdateien nur dann als Blinden Fleck, wenn das Projekt wiederholbare Lieferung, gemeinsame Übergabe oder produktionsähnliche Zuverlässigkeit beansprucht. Persönliche Notizen und frühe Prototypen benötigen diese möglicherweise nicht.
- Überschütte den Benutzer nicht mit jedem möglichen Risiko. Ordne nach Projektpassung, Schadensreichweite, Umkehrbarkeit und Wahrscheinlichkeit.
- Wenn der Benutzer kein Experte auf dem Gebiet ist, füge kurze Lehranmerkungen für ungewohnte Blinde Flecken hinzu.
- Wenn eine Erkenntnis vom aktuellen externen Plattformverhalten abhängt, verifiziere mit offiziellen Dokumenten oder aktueller Forschung, bevor du sie als Tatsache behandelst; ohne Webzugriff, präsentiere sie als unbestätigt.
- Wenn eine Research-Frage länger als 2-3 Minuten dauert, protokolliere die Frage selbst als Blinden Fleck: „Die Recherche zu X wurde aufgeschoben, weil sie den zeitlichen Rahmen der Sitzung überschritt.“
- Überschreite nicht den für diesen Modus und diese Aufgabe angemessenen Aufwand.
Wann dieser Skill NICHT verwendet werden sollte
- Wenn der Benutzer eine bestimmte Fehlerbehebung oder ein bestimmtes Feature wünscht – verwende stattdessen einen Implementierungs- oder Debugging-Skill.
- Für eine abschließende Qualitätsbewertung oder Sicherheitsüberprüfung – dieser Skill deckt alle Unbekannten auf, bestätigt jedoch keine Abwesenheit.
- Wenn der Benutzer ein klares, gut dokumentiertes Ziel mit wenigen offenen Fragen hat – die Investition in die Erkennung von Blindstellen übersteigt dann den Nutzen.
- Wenn der Benutzer ausdrücklich eine oberflächliche Checkliste wünscht – ein generischer "10 Dinge, die man überprüfen sollte"-Skill wäre billiger und besser geeignet.
Referenzen und Vorlagen
Der Skill enthält die folgenden Dateien, auf die im obigen Text verwiesen wird:
references/archetypes.mdreferences/lenses.mdreferences/host-surfaces.mdreferences/ledger-lifecycle.mdreferences/report-template.mdtemplates/BLINDSPOT_LEDGER.mdscripts/project_inventory.py
Diese werden im Stammverzeichnis des Skills relativ zu dieser SKILL.md-Datei erwartet.