FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

Verwenden Sie dieses Skill, wenn der Benutzer die migrierte Quellbefehl audit-whitepapers ausführen möchte.

Befehlsvorlage

Whitepaper & Zusammenfassungskarten auditieren

Umfassende Prüfung der Aktualität und Qualität aller Whitepaper (FR + EN) und Zusammenfassungskarten (FR + EN). Bewertet jedes Dokument im Vergleich zur aktuellen Guide-Version, prüft die FR/EN-Parität und validiert die Konsistenz der Metadaten.

Argumente

• --fix - Erstellt Aktualisierungsvorschläge und Frontmatter-Patches (ändert keine Dateien)
• --verbose - Zeigt alle Kriterien einschließlich bestandener an, nicht nur Fehler
• --cards-only - Nur Zusammenfassungskarten auditieren (Haupt-Whitepaper überspringen)
• --wp-only - Nur Haupt-Whitepaper auditieren (Zusammenfassungskarten überspringen)

Verwendung

/audit-whitepapers                  # Vollständiges Audit, nur Fehler
/audit-whitepapers --fix            # Audit + priorisierte Aktualisierungsvorschläge
/audit-whitepapers --verbose        # Vollständige Details für alle Kriterien
/audit-whitepapers --cards-only     # Nur Zusammenfassungskarten
/audit-whitepapers --wp-only        # Nur Whitepaper

---

Phase 1: Erkennung

Ziel: Alle prüfbaren Dokumente lokalisieren und erfassen.

Schritte

1. Aktuelle Guide-Version lesen: Lesen Sie die Datei VERSION im Projektstammverzeichnis. Dies ist die Zielversion, mit der alle Dokumente abgeglichen werden sollen.

2. Verzeichnisse scannen nach .qmd-Dateien:

   whitepapers/fr/         (Haupt-Whitepaper FR)
   whitepapers/en/         (Haupt-Whitepaper EN)
   whitepapers/recap-cards/fr/    (Zusammenfassungskarten FR)
   whitepapers/recap-cards/en/    (Zusammenfassungskarten EN)
   

3. Jede Datei klassifizieren:

   • Haupt-Whitepaper: Dateien, die [0-9][0-9]-*.qmd in whitepapers/fr/ oder whitepapers/en/ entsprechen
   • Spickzettel: Dateien, die *cheatsheet*.qmd entsprechen (separat verfolgt, nicht bewertet)
   • Benutzerdefiniertes Whitepaper: Dateien, die *-whitepaper.qmd oder *-cheatsheet.qmd von externen Partnern entsprechen (strangebee, purchasely, devwithai) – von der Bewertung ausgeschlossen, separat aufgelistet
   • Zusammenfassungskarte: Alle .qmd-Dateien in recap-cards/fr/ oder recap-cards/en/
   • Bundle/Include: fiches-recap-serie.qmd, Dateien im Unterverzeichnis fiches/ – ausgeschlossen (es handelt sich um zusammengesetzte Dokumente)

4. YAML-Frontmatter parsen für jede eingeschlossene Datei (zwischen erstem --- und zweitem --- lesen). Extrahieren:

   • title, subtitle, author, date
   • version (Guide-Version, die in Haupt-WPs und Zusammenfassungskarten verfolgt wird)
   • wp-version (eigene Semver-Version des Whitepapers, nur Haupt-WPs)
   • guide-version (explizites Guide-Versionsfeld, das in Zusammenfassungskarten verwendet wird)
   • card-number, category, difficulty (nur Zusammenfassungskarten)
   • series (nur Haupt-WPs)

5. Erkennungszusammenfassung anzeigen:

   Guide-Version: {VERSION}
   Gefunden: {N} Haupt-Whitepaper ({FR}/{EN} FR/EN), {N} Zusammenfassungskarten ({FR}/{EN} FR/EN)
   Ausgeschlossen: {N} benutzerdefinierte Dateien (strangebee, purchasely, devwithai), {N} Bundle-Dateien
   

---

Phase 2: Versionslückenanalyse (40 Punkte pro Datei)

Ziel: Bewerten, wie aktuell jedes Dokument im Verhältnis zum Guide ist.

Semver-Vergleichslogik

Versionsstrings als MAJOR.MINOR.PATCH parsen. Die Metrik für Veralterung ist minor_gap = current_minor - file_minor (unter Verwendung derselben MAJOR). Wenn MAJOR abweicht, als kritisch behandeln.

Für Haupt-Whitepaper ist das Guide-Versionsfeld version. Für Zusammenfassungskarten ist das Guide-Versionsfeld guide-version (auf version zurückfallen, wenn nicht vorhanden).

Bewertungstabelle

Kriterium	Punkte	Erkennung
Guide-Version aktuell (0-1 Minor zurück)	15	minor_gap <= 1
Guide-Version aktuell (2-3 Minor zurück)	10	minor_gap 2-3 (Teilpunkte, ersetzt die 15)
Guide-Version alt (4-10 Minor zurück)	5	minor_gap 4-10 (Teilpunkte)
wp-version-Feld vorhanden und gültiges Semver	5	Feld existiert UND entspricht \d+\.\d+\.\d+ (nur WP)
wp-version konsistent mit FR/EN-Paar	10	Gleicher wp-version-Wert in der korrespondierenden Datei (nur WP)
guide-version konsistent mit FR/EN-Paar	10	Gleicher guide-version (oder version) in der korrespondierenden Datei (Karten)

Frische-Labels:

• 0-1 Minor zurück: Aktuell
• 2-3 Minor zurück: Veraltet
• 4-10 Minor zurück: Stark veraltet
• 11+ Minor zurück: Kritisch

Hinweis: Die 15, 10, 5 Punkte für die Guide-Version schließen sich gegenseitig aus (nur die höchste anwendbare Stufe vergeben).

---

Phase 3: Prüfung auf veralteten Inhalt (20 Punkte pro Datei)

Ziel: Erkennen, ob sich die Guide-Abschnitte, die ein Whitepaper abdeckt, seit der letzten Aktualisierung geändert haben.

Whitepaper-zu-Guide-Zuordnung (eingebettet)

WP#	FR-Dateinamen-Präfix	EN-Dateinamen-Präfix	Guide-Abschnitte
00	00-introduction	00-series-introduction	guide/ultimate-guide.md Ch.1-2
01	01-prompts	01-effective-prompts	Ch.2 Prompting-Abschnitte
02	02-personnalisation	02-customization	Ch.3 Memory, Ch.4 Agents, Ch.5 Skills
03	03-securite	03-security	Ch.7 Hooks, Sicherheitsabschnitte
04	04-architecture	04-architecture	Ch.2 Interna, Architekturabschnitte
05	05-equipe	05-team	Ch.3 Team-Konfiguration, Ch.9 CI/CD
06	06-privacy	06-privacy	Ch.2 Daten-/Datenschutzabschnitte
07	07-guide-reference	07-reference-guide	Ch.10 Referenz
08	08-agent-teams	08-agent-teams	Ch.9 Agent-Teams
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	Geschäfts-/ROI-Inhalte

Schritte

1. Für jedes Haupt-Whitepaper das Feld date extrahieren. Wenn das Datum nicht im Format YYYY-MM-DD vorliegt, es parsen (z. B. "2026-02-12" oder "März 2026").
2. Führen Sie git log --since="{date}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/ aus, um die Commits zu zählen, die den Guide-Inhalt seit dem Datum des Whitepapers berührt haben.
3. Bewerten:

Kriterium	Punkte	Erkennung
Keine Guide-Commits seit WP-Datum	10	git log gibt 0 Commits zurück
Wenige Commits seit WP-Datum (1-5)	7	1-5 Commits (Teilpunkte)
Moderate Commits (6-15)	4	6-15 Commits (Teilpunkte)
Viele Commits (>15)	0	Mehr als 15 Commits
Zuordnung für dieses WP definiert	5	WP-Nummer in der obigen Zuordnungstabelle
Git-Verlauf zugänglich	5	git log-Befehl wird ohne Fehler ausgeführt

Zusammenfassungskarten: Detaillierte Git-Analyse überspringen. Pauschale Veralterungsbewertung basierend auf minor_gap vergeben:

• 0-1 zurück: 20 Pkt.
• 2-3 zurück: 15 Pkt.
• 4-10 zurück: 8 Pkt.
• 11+ zurück: 0 Pkt.

---

Phase 4: FR/EN-Paritätsprüfung (20 Punkte pro Datei)

Ziel: Jedes Dokument sollte ein vollständiges, versionskonsistentes Gegenstück in der anderen Sprache haben.

Paarungsstrategie

Haupt-Whitepaper: Abgleich über das zweistellige numerische Präfix (z. B. 00, 03, 10). FR- und EN-Dateinamen unterscheiden sich, aber das Präfix ist konsistent.

Zusammenfassungskarten: Abgleich über identischen Dateinamen (beide Sprachverzeichnisse verwenden dieselben Dateinamen).

Bewertungstabelle

Kriterium	Punkte	Erkennung
Gegenstückdatei in anderer Sprache vorhanden	10	Datei mit passendem Präfix (WP) oder identischem Namen (Karten) gefunden
wp-version stimmt zwischen Paaren überein	5	Gleicher wp-version-Wert (nur WP)
Guide-Version stimmt zwischen Paaren überein	5	Gleicher version/guide-version-Wert

Bewerten Sie sowohl die FR- als auch die EN-Datei eines Paares in Bezug auf die Parität identisch (wenn das Paar vollständig ist, erhalten beide 20; wenn eines fehlt, erhält die vorhandene Datei 0 Punkte für die Parität).

---

Phase 5: Metadatenqualität (20 Punkte pro Datei)

Ziel: Validierung der Vollständigkeit des Frontmatters, der Feldformate und der Konsistenz zwischen Dateien desselben Typs.

Haupt-Whitepaper (max. 20 Punkte)

Kriterium	Punkte	Erkennung
Erforderliche Felder vorhanden	6	Hat alle: title, subtitle, author, date, version, wp-version, series
version folgt Semver-Muster	3	Entspricht \d+\.\d+\.\d+
wp-version folgt Semver-Muster	3	Entspricht \d+\.\d+\.\d+
date ist parsbar und liegt nicht in der Zukunft	3	Gültiges Datum, nicht nach heute
series-Wert ist konsistent	2	Gleich "Codex Ultimate Guide"
Kein fehlendes wp-version (nicht leer oder abwesend)	3	Feld hat einen nicht leeren Wert

Zusammenfassungskarten (max. 20 Punkte)

Kriterium	Punkte	Erkennung
Erforderliche Felder vorhanden	5	Hat alle: title, subtitle, card-number, category, difficulty, guide-version, author, version, date
card-number stimmt mit Dateinamen-Präfix überein	4	z. B. C01 in card-number entspricht c01- im Dateinamen
category gültig für Sprache	4	FR: einer von "Technique", "Methodologie", "Conception"; EN: einer von "Technical", "Methodology", "Design" ("Conceptual" als inkonsistent im EN markieren)
difficulty ist gültiger Wert	3	Einer von: "beginner", "intermediate", "advanced"
guide-version und version-Felder stimmen überein	4	Beide Felder existieren und haben denselben Wert innerhalb derselben Datei

Bekanntes Problem zur automatischen Erkennung: EN C-Serien-Karten verwenden zwei verschiedene Kategoriewerte ("Conceptual" auf c01-c05, "Design" auf c06+). Diese Inkonsistenz im Abschnitt "Metadatenprobleme" des Berichts explizit kennzeichnen.

---

Phase 6: Bewertung und Benotung

Bewertungsformel (pro Datei)

Gesamt = Versionslücke (40) + Inhaltsaktualität (20) + FR/EN-Parität (20) + Metadatenqualität (20)
Punktzahl = (Gesamt / 100) * 100  [als Prozentsatz]

Notenskala

Note	Punktzahl	Status
A	90-100	Aktuell, vollständig synchronisiert
B	80-89	Gut (Produktionsschwelle)
C	70-79	Baldige Aktualisierung erforderlich
D	60-69	Veraltet, sollte priorisiert werden
F	<60	Kritisch: wahrscheinlich veralteter Inhalt

Gesamt-Gesundheitswert

Gewichtete Gesundheit = (Summe der WP-Punktzahlen * 2 + Summe der Karten-Punktzahlen * 1) / (WP-Anzahl * 2 + Karten-Anzahl * 1)

Whitepaper werden 2x gewichtet, da sie jeweils 20-80 Seiten umfassen, im Vergleich zu 2-seitigen Zusammenfassungskarten. Ein veraltetes Whitepaper birgt ein höheres Risiko.

---

Phase 7: Bericht

Den folgenden Markdown-Bericht ausgeben. Verwenden Sie <details>-Blöcke für einzelne Dateiaufschlüsselungen, um die oberste Ebene überschaubar zu halten.

# Whitepaper & Zusammenfassungskarten-Audit

**Datum**: {today}
**Guide-Version**: {VERSION}
**Gesamt-Gesundheit**: {score}% ({grade})
**Geprüfte Dateien**: {total} ({wp_count} Whitepaper, {card_count} Zusammenfassungskarten)

---

## Versionsstatus-Dashboard

| Status | Whitepaper | Zusammenfassungskarten | Gesamt |
|--------|------------|------------------------|--------|
| Aktuell (0-1 Minor zurück)   | N | N | N |
| Veraltet (2-3 Minor zurück)   | N | N | N |
| Stark veraltet (4-10 zurück)   | N | N | N |
| Kritisch (11+ zurück)      | N | N | N |

**Derzeit verwendete Versionen**:
- Haupt-WP 00-09: {version} ({gap} Minor-Versionen zurück)
- Haupt-WP 10: {version} ({gap} Minor-Versionen zurück)
- Zusammenfassungskarten: {guide-version} ({gap} Minor-Versionen zurück)

---

## Whitepaper-Punktzahlen

| WP# | Titel | version | Lücke | wp-version | Parität | Punktzahl | Note |
|-----|-------|---------|-------|------------|---------|-----------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/Lücke | N%    | X     |
...

<details>
<summary>Aufschlüsselung der einzelnen Kriterien (WP 00)</summary>

| Phase | Kriterium | Ergebnis | Punkte |
|-------|-----------|----------|--------|
| Versionslücke | Guide-Version aktuell | Kritisch (-11) | 0/15 |
| Versionslücke | wp-version gültiges Semver | OK | 5/5 |
| ... | ... | ... | ... |
| **Gesamt** | | | **N/100** |
</details>

---

## Zusammenfassungskarten-Punktzahlen

| Serie | Karten | Durchschn. guide-version | Durchschn. Lücke | Durchschn. Punktzahl | Note |
|--------|-------|--------------------------|------------------|----------------------|-------|
| T (Technisch)    | 22 | ... | -N | N% | X |
| M (Methodologie)  | 22 | ... | -N | N% | X |
| C (Konzeptionell)   | 13 | ... | -N | N% | X |

<details>
<summary>Einzelne Karten-Punktzahlen</summary>

| Karte | Kategorie | guide-version | Lücke | Parität | Metadaten | Punktzahl | Note |
|-------|-----------|---------------|-------|--------|-----------|-----------|-------|
...
</details>

---

## FR/EN-Paritätsbericht

### Whitepaper
| WP# | FR | EN | wp-version Übereinstimmung | version Übereinstimmung |
|-----|----|----|----------------------------|-------------------------|
...

### Zusammenfassungskarten
- **FR-Anzahl**: {N} | **EN-Anzahl**: {N}
- **Fehlende FR**: [Liste oder "Keine"]
- **Fehlende EN**: [Liste oder "Keine"]
- **Versionsabweichungen**: [Liste oder "Keine"]

---

## Metadatenprobleme

### Bekannt: Inkonsistenz der EN-Zusammenfassungskarten-Kategorie
EN C-Serien-Karten verwenden zwei verschiedene Werte für die Kategorie "Conceptual/Design":
- "Conceptual": c01, c02, c03, c04, c05
- "Design": c06, c07, c08, ...
Empfehlung: Auf "Design" standardisieren, um der Guide-Terminologie zu entsprechen.
Betroffene Dateien: whitepapers/recap-cards/en/c01-*.qmd bis c05-*.qmd ("Conceptual" in "Design" ändern)

### Andere Probleme
[Liste fehlender Felder, falscher Formate, Datumsprobleme ...]

---

## Priorisierte Maßnahmen

### Kritisch (Note F, 11+ Versionen zurück)
[Liste der spezifischen Whitepaper mit Dateipfaden]

### Hoch (Note D-F, 2+ Versionen zurück)
[Liste der spezifischen Dateien]

### Mittel (Metadatenqualität, Kategoriekorrekturen)
[Liste der spezifischen Probleme]

### Niedrig (Kosmetik, Datumsabgleich)
[Liste der spezifischen Probleme]

---

## Nächste Schritte

1. Führen Sie `/update-whitepapers --since {oldest_version}` aus, um alle veralteten WPs zu aktualisieren
2. Beheben Sie die Inkonsistenz der EN-Kategorie (5 Dateien: c01 bis c05, ändern Sie "Conceptual" in "Design")
3. Führen Sie `/audit-whitepapers` nach den Aktualisierungen erneut aus, um den Fortschritt zu verfolgen
4. Ziel: 80%+ Gesundheit (Note B) über alle Dateien hinweg

---

Korrekturmodus (--fix)

Wenn --fix übergeben wird, hängen Sie nach dem Bericht einen Abschnitt Korrekturvorschläge an. Dieser Abschnitt bietet konkrete Patches, ändert jedoch KEINE Dateien.

Frontmatter-Versionspatches

Für jede Datei mit einer veralteten Guide-Version ausgeben:

# Datei: whitepapers/fr/00-introduction-serie.qmd
# Änderung:
version: "3.27.6"  ->  version: "{current_VERSION}"
date: 2026-02-12   ->  date: {today}

Kategorie-Korrektur-Patches (EN-Zusammenfassungskarten)

Zu aktualisierende Dateien (Kategorie: "Conceptual" -> "Design"):
- whitepapers/recap-cards/en/c01-trust-calibration.qmd
- whitepapers/recap-cards/en/c02-*.qmd
- whitepapers/recap-cards/en/c03-*.qmd
- whitepapers/recap-cards/en/c04-*.qmd
- whitepapers/recap-cards/en/c05-*.qmd