ritamgh/claude-skills

Evidenzvertrag

Erstelle Pläne, die testbar und im tatsächlichen Repository verankert sind – nicht auf plausiblen Vermutungen basieren.

Aktivierung

Wende diesen Skill automatisch an, wenn die Aufgabe einen nichttrivialen Implementierungsplan oder eine Planüberprüfung erfordert. Warte nicht darauf, dass der Benutzer ihn explizit aufruft.

Überspringe den vollständigen Vertrag bei trivialen Änderungen, bei denen Ziel, Verhalten und Überprüfung bereits offensichtlich sind. Gib stattdessen die einfache Prüfung an.

Dieser Skill dient ausschließlich der Planung. Bearbeite keine Implementierungsdateien, es sei denn, der Benutzer hat dich auch gebeten, den Plan auszuführen.

Workflow

1. Absicht und Erfolg festlegen

Formuliere das gewünschte Ergebnis in einem Satz. Extrahiere konkrete Akzeptanzkriterien aus der Anfrage. Falls die Formulierung mehrdeutig ist, untersuche das Repository, bevor du den Benutzer fragst. Frage nur, wenn nach der Untersuchung materiell unterschiedliche Ergebnisse möglich bleiben.

2. Minimale ausreichende Evidenz sammeln

Bevor du eine Architektur vorschlägst oder betroffene Dateien benennst:

1. Lies PROJECT_CONTEXT.md, falls vorhanden.
2. Lokalisiere die Einstiegspunkte des Features durch gezielte Suche.
3. Lies die kleinste Menge relevanter Implementierungs-, Konfigurations- und Testdateien.
4. Verfolge wichtige Aufrufer, Abhängigkeiten, Persistenzgrenzen und öffentliche Schnittstellen.
5. Dokumentiere Widersprüche zwischen Dokumentation und Code. Behandle Code und ausführbares Verhalten als stärkere Evidenz.

Vermeide breite Repository-Durchsuchen, wenn gezielte Evidenz ausreicht.

3. Jede materielle Behauptung klassifizieren

Verwende diese Labels intern und mache sie sichtbar, wenn es nützlich ist:

• Beobachtet: direkt durch eine Datei, ein Symbol, ein Befehlsergebnis, einen Test oder eine Laufzeitbeobachtung gestützt.
• Abgeleitet: stark durch beobachtete Evidenz impliziert, aber nicht direkt nachgewiesen.
• Unbekannt: materielle Information, die nicht ermittelt wurde.

Präsentiere niemals eine abgeleitete oder unbekannte Behauptung als Tatsache. Gib für wichtige beobachtete Behauptungen einen Code-Ort oder eine Werkzeugbeobachtung an. Erfinde keine Dateipfade, APIs, Abhängigkeiten oder existierendes Verhalten.

4. Blockierende Unbekannte auflösen

Untersuche Unbekannte, die Architektur, Umfang, Datenfluss, Kompatibilität oder Akzeptanzverhalten ändern könnten. Wenn eine Unbekannte nicht lokal aufgelöst werden kann:

• benenne sie explizit,
• erkläre, warum sie wichtig ist,
• schlage die sicherste begrenzte Annahme vor, und
• frage den Benutzer nur, wenn das Fortfahren das falsche Ergebnis produzieren könnte.

5. Einen evidengestützten Plan erstellen

Jeder nichttriviale Planpunkt muss enthalten:

1. Änderung: der kleinste kohärente Implementierungsschritt.
2. Evidenz: beobachtete Repository-Fakten, die den Schritt rechtfertigen, mit relevanten Pfaden oder Symbolen.
3. Betroffene Oberfläche: Dateien, Schnittstellen, Daten, Aufrufer, Abhängigkeiten oder Workflows, die sich wahrscheinlich ändern.
4. Erfolgsprüfung: eine ausführbare Test-, Build-, Lint-, Laufzeit- oder Akzeptanzbeobachtung.
5. Risiko oder Annahme: nur wenn materiell, gekennzeichnet als abgeleitet oder unbekannt.

Bevorzuge Pläne, die eine Anforderung auf eine überprüfbare Beobachtung abbilden. Füge Regressionsabdeckung für Fehlerbehebungen und kompatibilitätsempfindliche Änderungen hinzu.

6. Planprüfung durchführen

Überprüfe vor der Präsentation des Plans:

• Jedes angeforderte Ergebnis ist mindestens einem Planpunkt zugeordnet.
• Jeder Planpunkt hat eine Evidenz und eine konkrete Erfolgsprüfung.
• Genannte Dateien und Symbole wurden beobachtet, nicht erraten.
• Materielle Annahmen sind sichtbar und klassifiziert.
• Abhängigkeiten und Integrationsgrenzen sind abgedeckt.
• Der Plan verwendet die kleinste Änderung, die die Anfrage erfüllt.
• Es wurden keine spekulativen Funktionen oder unnötigen Refactorings hinzugefügt.

Wenn die Prüfung fehlschlägt, untersuche oder überarbeite den Plan, bevor du ihn zurückgibst.

Ausgabeformat

Halte das Ergebnis kurz, es sei denn, die Aufgabe ist komplex.

## Evidenzvertrag
- Beobachtet: `pfad/zur/datei` stellt fest ...
- Abgeleitet: ... weil ...
- Unbekannt: ...; begrenzte Annahme oder erforderliche Entscheidung ...

## Plan
1. **Änderung** ...
   - Evidenz: ...
   - Betroffen: ...
   - Überprüfung: ...
   - Risiko/Annahme: ...

## Abschlussprüfung
- [ ] Anforderungs-Check-Zuordnung ist vollständig
- [ ] Es verbleiben keine unbeschrifteten Annahmen
- [ ] Akzeptanzprüfungen sind ausführbar

Leere Abschnitte zu abgeleiteten oder unbekannten Angaben weglassen. Bei kleinen Plänen jeden Punkt auf eine einzelne Zeile komprimieren, dabei aber Evidenz und Überprüfung beibehalten.

Anti-Patterns

Nicht:

• einen Plan allein aus Dateinamen ableiten,
• „wahrscheinlich“, „vermutlich“ oder „sollte“ verwenden, ohne eine Schlussfolgerung zu kennzeichnen,
• behaupten, dass Tests bestanden haben, ohne sie ausgeführt zu haben,
• eine simulierte Prüfung durch einen verfügbaren echten Akzeptanzpfad ersetzen,
• den Benutzer mit Fragen belasten, die aus dem Repository beantwortet werden können,
• den Vertrag bei trivialen Änderungen zu einem bürokratischen Aufwand machen,
• mit der Implementierung beginnen, nur weil der Plan vollständig ist.