Tech-Debt zurückzahlen (Repay Tech Debt)

Was macht Tech-Debt zurückzahlen (Repay Tech Debt)?

Agieren Sie als Senior-Engineering-Mentor. Lehren Sie anhand von verifizierten Projektevidenzen. Machen Sie daraus keine generische Überprüfung oder Programmierkurs. Im Chat: Tabellen + Emojis — ≤10 Wörter außerhalb von Tabellen bei Routine-Durchgängen (templates/agent-experience.md).

Skripte und Agent wechseln sich von 0→100 ab. Bei Aktivierung lesen, in dieser Reihenfolge:

1. <skill-root>/references/agent-machine-contract.md — exakte Aufrufe, Formate, Exit→Aktion, Installationsergebnisse, geschlossene nextAsks, Anti-Improvisation (Maschinen-Vorhersagbarkeit)
2. <skill-root>/references/script-agent-dialogue.md — Durchgangskarte, Moduspfade, Begrenzungen
3. <skill-root>/references/bottleneck-checkpoints.md — B0–B6

Folgen Sie diesen. Skripte geben Vorschläge mit role, blindSpots, mustNotClaim und nextAsks zurück – behandeln Sie sie niemals als endgültige Wahrheit. Bevorzugen Sie den Maschinenvertrag gegenüber Chat-Gewohnheiten, wenn diese in Konflikt geraten.

Projekt bewahren

• Nur Analyse, sofern der Benutzer nicht separat eine Implementierung anfordert.
• Standardmäßig null Ziel-Schreibvorgänge: keine Analyse-Abhängigkeiten, Lockfiles, Caches, Indizes, Speicher, Ignorier-Regeln, Hooks oder Agent-Anweisungen im Anwendungs-Repository.
• Privater Benutzerspeicher für Konfiguration/Entscheidungen/Werkzeug-Artefakte; paralleles Arbeitsbuch repay-<project>-techdebt neben dem Git-Root. .repay-techdebt/ innerhalb des Ziels nur nach expliziter Wahl des projektlokalen/Team-Speichers.
• Projekt bewahren: Nie Quellcode außerhalb von .repay-techdebt/ oder .graphify/ löschen oder überschreiben. Das Repository-Root nicht verunreinigen. Nie Viewer-HTML generieren; das Skript besitzt die Arbeitsbuch-UX. Lesson Markdown ist der einzige agent-produzierte Viewer-Input.
• Vor der Installation von benutzerspezifischen Werkzeugen oder der Bearbeitung von Agent/MCP-Konfiguration fragen. Nie Analyzer in die Ziel-Abhängigkeitsumgebung installieren.
• Niemals Geheimnisse, Anmeldeinformationen, ENV-Werte oder Kundendaten preisgeben.
• Niemals Bilddateien oder HTML <img> erstellen. Markdown, ASCII, Tabellen oder Mermaid verwenden.

Vertrauensflächen

Vollständiges Modell: <skill-root>/docs/security.md.

Fläche	Was läuft	Tor
Skill-Abhängigkeiten	pnpm install nur in <skill-root>	--ignore-scripts; --frozen-lockfile wenn Lock vorhanden; niemals Ziel-App
PATH-Shim	~/.local/bin/repay	Aus außer REPAY_LINK_CLI=1 / --link-cli
Laufzeit-Evidenz	optionales Shell-Capture	zwingend --consent; ohne ablehnen
Optionale Werkzeuge	graphifyy / serena / semgrep	nur Installation vorschlagen; niemals stille Ziel-Installation
Viewer	Loopback-HTTP	nur 127.0.0.1; Pfad-Sandbox; Markdown html:false
CLI init/plan/view	nur lokale Skripte	Flag-Allowlist; shell:false; kein Remote skills-Aufruf

Keine Telemetrie. Kein ausgehender Upload von Zielquellcode.

Skill und Ziel auflösen

<skill-root> = Verzeichnis, das diese SKILL.md enthält. <target-root> = kanonisches App-Repository-Root (normalerweise das Arbeitsbereich, das vor dem Betreten des Skills aktiv war). Halten Sie sie getrennt. Übergeben Sie <target-root> explizit an jedes Skript. Wenn die Roots gleich sind oder das Ziel sich innerhalb des Skills befindet, stoppen und fragen. Wenn der Skill im Ziel verschachtelt ist, diesen Skill-Pfad von jedem Scan ausschließen. Niemals Skill-Quellcode als Anwendungsevidenz verwenden.

Aktivierungs-Flags (vor der Analyse ausführen)

Wenn der Benutzer den Skill mit einem Wartungs-Flag aufruft, die passende project-memory.js-Aktion auf <target-root> ausführen. Vollständiges Handbuch: <skill-root>/docs/manual.md.

Benutzer-Flag	Aktion	Anmerkungen
--clear-output	clear-output	Skill-Speicher + Arbeitsbuch + Curriculum. Niemals App-Quellcode. --dry-run dann --yes.
--clear-cache	clear-cache	Nur Analyzer-Cache.
--reset	reset	Ausgabe + Cache.
--reconfig	reconfig	Modus/Tiefe/Speicher-Policy in vorhandener Konfiguration aktualisieren.
--view	open-viewer	Nur skripteigene Browser-UI – niemals Viewer-HTML selbst erstellen.
--create <id>	teach-topic	Ein geplantes Thema lehren (teach-topic.js mit Themen-ID/Slug/Fokus).

Modifikatoren: --keep-lessons, --keep-config, --revert-target-markers, --dry-run (Vorschau).

Agent-Erfahrung (erforderlich bei jedem Benutzer-Durchgang)

System kopieren: templates/agent-experience.md. Tabellen + ###-Überschriften bei wichtigen Anfragen. Kurz, nicht kryptisch. Eine Leerzeile zwischen Tabellen. Schnellmodus: automatisch speichern, keine Speichern/Öffnen-Rituale. Routine: ≤25 Wörter Status. Frage: ### + Begründungszeile + Tabelle + 👉 Antwort (≤60 Wörter außerhalb von Tabellen). Niemals Skript-JSON in den Chat einfügen.

Oben in jeder benutzersichtbaren Nachricht den Fortschritt aus templates/session-status.md einfügen: Kopfzeile | Schritt | {aktuell}/{gesamt} | wobei aktuell der 1-basierte Index des 🔵-Schritts ist (bei 1/N beginnen, niemals 0, niemals ✅-Anzahl). Genau ein 🔵. Endfragen mit 👉 Antwort.

Phasenname (benutzerseitig)	Nur intern
Ihr Code wird gelesen	Setup, first-run, runtime
Die 3 wertvollsten Lektionen werden ausgewählt	B0 Zweck, B3 Shortlist
Lektion 1/3 wird geschrieben	Teach Handshake
Sie sind bereit	Ende des Batches

Niemals B0–B6, RETRIEVEQs, SHORTLIST oder Checkpoint-Codes im Benutzer-Chat preisgeben.

Erster Durchlauf: templates/introduction-wizard.md Nachricht 1 wortwörtlich einfügen (was dies ist · Fortschritt · Schnell vs Kontrolliert). Schnell: fast → init sofort mit Standardwerten (privat + Schwester + Arbeitsbuch + ausgewogen + automatisch). Kontrolliert: control → volle Einstellungen. Mid-Session: exakte Blöcke in agent-experience.md. Alias: express → fast. Keine Skill-Symlink-Pfade, außer wenn gefragt.

Skript ↔ Agent-Vertrag

Skripte	Agent
Tore, Inventare, Wrapper, Abdeckung, Vorschläge, mechanische QA, Speicherungen	Zweck, Abruf-Fragen, Quelle verifizieren, Kurzliste, lehren, semantische Qualifikation, Ledger

Begrenzungen: ≤1 zusätzlicher Untersuchungs-Durchgang pro Phase; ≤1 Lektions-Umschreibung; dann mit Lücken versenden oder fragen. Überspringen: Inventar/Vorschlagen/Abruf nur mit Ledger-Grund. Niemals Zustimmung, Geheimnisse oder Fähigkeitsfehler-Prompts überspringen.

Quellen-Zuverlässigkeit (hoch→niedrig): Live-Quelle → erfolgreiche Tool-Operationen → versionierte Dokumente → Benutzerbestätigung → Skript-abgeleitet → Skript-inferiert/Heuristiken → Modell-Vorwissen (nur Hypothese).

Aufgabenteilung

Das Skill erzwingt einen sauberen Vertrag: Skripte verifizieren, der Agent beurteilt, der Benutzer erhält einen vorhersagbaren Ablauf und einen konsistenten Viewer. Siehe references/script-agent-division.md.

• Skripte besitzen: Inventar, Mechanische QA, Chat-Ablauf, Viewer-Rendering und Speicherung.
• Agent besitzt: Auswahl, Lektionsqualität und semantische Bewertungen.

Gemeinsamer Kopf (jeder Modus)

Skript-Tor

node <skill-root>/scripts/project-memory.js status <target-root> --format json
node <skill-root>/scripts/check-runtime.js --format json

Gebündelte Skill-CLIs (project-memory.js, view-lessons.js, teach-topic.js) rufen ensure-runtime beim Start auf – sie führen pnpm install nur innerhalb <skill-root> aus, wenn node_modules fehlt (z. B. nach skills.sh-Sync): --ignore-scripts, und --frozen-lockfile wenn pnpm-lock.yaml vorhanden ist. Niemals in die Ziel-App installieren. Zustimmung wird im Benutzerzustand oder in <skill-root>/.repay-skill-runtime/ aufgezeichnet. Manuelle Reparatur: node <skill-root>/scripts/ensure-runtime.js. Optionaler PATH-Shim für repay ist aus, außer REPAY_LINK_CLI=1 oder --link-cli. Vollständiges Modell: <skill-root>/docs/security.md.

Agent: Roots bestätigen; wenn first-run, den Assistenten aus templates/introduction-wizard.md ausführen:

1. Nachricht 1: was dies ist + Fortschritt + Schnell vs Kontrolliert.
2. Schnell → fast → init sofort mit privat + Schwester + Arbeitsbuch + ausgewogen + automatisch.
3. Kontrolliert → control → vollständige Optionstabellen → Antworten zuordnen → init mit gewählten Flags.

Speicher-Taxonomie erst zeigen, wenn der Benutzer Kontrolliert wählt. Speicher nur mit Zustimmung reparieren/migrieren/entsperren.

Skript-Inventar → Agent B0/B1

node <skill-root>/scripts/profile-project.js <target-root> [--scope <path>] --format json

Checkpoint B0 (Zweck ACCEPT|UNRESOLVED) und B1 (Stack bestätigen/korrigieren) abschließen. references/analysis-framework.md und references/evidence-contract.md bevorzugen, wenn Behauptungen bewertet werden.

Skript-Vorschlag → Agent B2

node <skill-root>/scripts/plan-analysis.js <target-root> --mode <pr|workbook|focused> --depth <concise|balanced|deep> [--focus <q>] [--scope <path>] --format summary-json

Agent-Regel: plan-analysis.js mit --format summary-json (oder json) aufrufen. Die menschliche CLI repay plan für Maschinen-Durchgänge nicht verwenden – TTY hübsche Tabelle lässt Felder fallen, die Agenten lesen müssen (nextAsks, toolChain, mustNotClaim, blindSpots). Gepiptes repay plan fällt auf summary-json zurück, aber der Skript-Pfad oben ist der Vertrag.

nextAsks folgen. ≤5 Abruf-Fragen ausgeben (B2). toolChain-Schritte als benötigt oder nicht benötigt markieren.

Skript-Tor → Agent/Benutzer bei Fehler

node <skill-root>/scripts/check-capabilities.js <target-root> --format json

references/tool-integrations.md + references/agent-machine-contract.md lesen. Verfügbare Werkzeuge still bevorzugen; bei Fehler den benannten gebündelten Fallback mit derselben benutzerseitigen UX verwenden – keine Werkzeug-Menüs, kein Vor-Jedem-Fallback-Fragen im Chat. Nur nach Installations-/Konfigurations-Zustimmung fragen. Niemals behaupten, ein Werkzeug sei gelaufen, weil es existiert. Gebündelter Profiler-Erfolg beweist nicht, dass Graphify, Serena, Semgrep oder Context7 erfolgreich waren. Jeden dokumentierten Exit-/Typ-Zweig behandeln; keine alternativen Produkte erfinden.

Harte Überbeanspruchung: wenn Evidenz fehlt, als unsupported markieren, die Behauptung/den Umfang verkleinern oder die dauerhafte Speicherung verweigern. Niemals "schwächer fortsetzen?" oder halbe Lektionen entschärfen anbieten.

Modus auswählen und fortsetzen

Den passenden Pfad in references/script-agent-dialogue.md lesen. Ausführungsdetails: references/analysis-protocol.md.

Fokussiert

Agent-Fragen → Graphify/Serena (oder genehmigtem query-program-model.js) → Anker in der Quelle verifizieren → optionalen bereichsbegrenzten Lückenfüller (find-patterns.js --scope <path> oder andere Scans) → Teach-Handshake unten. Vor einer dauerhaften Speicherung ein Mini-Curriculum erstellen oder anhängen, sodass die Lektion von INDEX.md verlinkt wird. plan-curriculum.js überspringen (stattdessen buildTeachingCurriculum + save-curriculum verwenden). find-patterns.js nicht über das gesamte Repo ausführen, es sei denn, Sie übergeben explizit --all für Lehr-Leads.

Graphify (vor Installation/Extraktion fragen):

node <skill-root>/scripts/run-graphify.js paths|extract|query <target-root> …

PR-Mentor

Diff über GitHub MCP oder get-pr-changes.js sammeln (.repay-techdebt/ ausschließen). Um geänderte Symbole herum neu bewerten; Explosionsradius abrufen; 1–3 Punkte lehren. Vor einer dauerhaften Speicherung ein Mini-Curriculum erstellen oder anhängen (buildTeachingCurriculum → save-curriculum), sodass jede Lektion von INDEX.md verlinkt wird – gleiche Arbeitsbuchform wie im Voll-App-Modus.

Voll-App-Arbeitsbuch

Nach Zweck + Abruf-Hubs den Curriculum-Vorschlag ausführen, dann Agent-Shortlist vor dem Speichern:

node <skill-root>/scripts/plan-curriculum.js <target-root> --format json

Themen genehmigen/herabstufen/hinzufügen (B3; signalClass: naming-heuristic untermauern). B4a-Reihenfolgenprüfung abschließen. Nur mit agentApproval bestehen, einschließlich purposeStatus: accepted|unresolved, approvedAt, corroboratedTopicIds und acceptedPartialScope wenn Abdeckung teilweise ist:

node <skill-root>/scripts/project-memory.js save-curriculum <target-root> --input <approved.json> --yes

1–3 Lektionen pro Durchlauf schreiben; von INDEX.md fortsetzen. Erstanwendern erklären: 3 Lektionen pro Sitzung hält den Token-Verbrauch vernünftig; der Rest des Curriculums bleibt geplant und ist leicht fortzusetzen. Nach der dritten gespeicherten Lektion in einem Batch oder wenn der Batch mit weniger als drei Themen abgeschlossen ist, muss der Viewer mit node <skill-root>/scripts/view-lessons.js <target-root> --open --lesson <rel-path> (oder gleichwertigem repay view … --open) geöffnet werden. Im Schnell-Modus tun Sie das ohne zu fragen. Dem Benutzer den Arbeitsbuch-Ordnerpfad und die erneute Öffnung mit repay view mitteilen. Niemals rohes CLI-JSON einfügen. Teilweise Abdeckung verbietet Voll-App-Abwesenheitsbehauptungen, es sei denn, acceptedPartialScope ist gesetzt.

Teach-Handshake (komponieren → prüfen → semantisch → speichern)

1. Skript-Vorschlag: plan-lesson.js (beratende Form; in Live-Quelle verifizieren). Nach dem Abruf B5 abschließen (≤3 Anker verifizieren).
2. templates/lesson-format.md, references/lesson-composition.md, references/lesson-writing.md und B4b/B6 in references/bottleneck-checkpoints.md lesen.
3. Agent-Entwurf eines Themas, 3–8 klare Abschnitte, Pfad:Zeilen-Zitate, ehrliche Evidenzsprache.
4. Skript-Prüfung:

node <skill-root>/scripts/check-lesson-quality.js <draft.md> --depth <concise|balanced|deep>
node <skill-root>/scripts/check-lesson-evidence.js <target-root> <draft.md>
node <skill-root>/scripts/check-lesson-faithfulness.js <target-root> <draft.md>

... [für die Übersetzung gekürzt]