marcioaltoe/write-techspec

Write TechSpec

Erstelle docs/specs/<slug>/_techspec.md – die technische Antwort auf die Anforderungen der Spezifikation. Der PRD sagte was und warum; dieses Dokument entscheidet wie, wo und womit – und seine Build-Order wird von write-tasks in den Aufgaben-Graphen umgewandelt, sodass die Qualität der Sequenzierung hier später die Ausführungsqualität bestimmt.

Vorbedingungen – zwei Einstiegsmodi

$ARGUMENTS benennt die Spezifikation (Slug oder Pfad) oder beschreibt ein Refactoring/einen Bugfix. Wähle den Modus basierend darauf, ob sich das Produktverhalten ändert:

• Feature-Arbeiten (Produktverhalten ändert sich) – docs/specs/<slug>/_prd.md muss existieren; falls nicht, stoppen und den Benutzer auf write-prd verweisen. Produktentscheidungen erfordern zuerst das Produktgespräch. Wenn der PRD technische Entscheidungen auf niedriger Ebene enthält, die hierher gehören, dies als Erkenntnis anmerken und vorschlagen, sie zu verschieben, anstatt sie stillschweigend zu duplizieren.
• Refactoring oder Bugfix (keine Änderung des Produktverhaltens) – dieses Skill ist der Pipeline-Einstiegspunkt; es findet kein PRD-Interview statt. Wenn noch kein Spec-Ordner existiert, einen nach der Nummerierungsregel von write-prd erstellen (<spec-root>/NNNN-<kebab-slug>/, dabei sowohl den konfigurierten Spec-Root als auch sein aufgelöstes Archivverzeichnis durchsuchen – docs/history/specs/ für den integrierten docs/specs Root, oder <spec-root>/_archived/ andernfalls – nach dem höchsten Präfix), und ein minimales _prd.md schreiben, das nur den Vertrag enthält, den die nachgelagerten Skills parsen: das Frontmatter (spec, status: active, surfaces, und type: fix für einen Bugfix oder type: refactor für ein Refactoring), eine Problemstellung, Projektbeschränkungen, Ziele, Kernfunktionen, Nicht-Ziele und ein Klärungsprotokoll unter ## Decisions – technisch formuliert, jeweils ein paar Zeilen. Das Protokoll folgt dem Klärungsleitfaden von write-prd: eine Zeile - YYYY-MM-DD: <Frage> — <Antwort> pro Frage, die eine Person beantwortet hat, oder Autonomer Weg: keine Person anwesend; Entscheidungen getroffen aus <Quelle>. unter Nennung der Quelle der Entscheidungen des Autors, wenn keine Person anwesend war. Es existiert, damit write-tasks, qa-gate und archive-spec einen einheitlichen Artefaktvertrag einhalten; es ist kein Produktdokument. Wenn sich herausstellt, dass das "Refactoring" das Produktverhalten ändert, stoppen und an write-prd weiterleiten.

Grundregeln

• Zuerst lesen: CONTEXT.md (das Glossar-Vokabular in jedem Schnittstellen- und Komponentennamen verwenden), bestehende docs/adr/ (vorherige Entscheidungen respektieren oder explizit in Frage stellen – niemals stillschweigend widersprechen), und den vollständigen PRD.
• Entscheiden, dann schreiben. Entscheidungen während der Klärung treffen, die bedeutenden als ADRs aufzeichnen, dann das fertige Dokument schreiben. Keine Genehmigungsrunden für Gliederungen.
• YAGNI. Keine neuen Pakete, Schichten oder Verzeichnisse vorschlagen, wenn die Funktionalität als Erweiterung in ein bestehendes Modul passt. Jedes neue Strukturelement muss sich gegen eine genannte Alternative behaupten.
• Referenzieren, nicht duplizieren. Auf PRD-Abschnitte mit Namen verweisen ("deckt User Stories 3–5 ab"); die Wiederholung von Geschäftskontext hier erzeugt zwei Kopien, die auseinanderdriften.
• Den eigenen Quellpfad verwenden. Jede übernommene Quelle mit ihrem Pfad nach der Übernahme in der eigenen Spezifikation verlinken, mit einem Ziel relativ zu _techspec.md, niemals mit dem Pfad vor der Übernahme, der im Referenzindex aufbewahrt wird. Eine sekundäre Spezifikation verlinkt die Kopie des primären Eigentümers und übernimmt nichts. Das Archiv des Eigentümers führt eine Archiv-Neuverlinkung durch: Es befördert die Kopie nach docs/references/ und schreibt die Links der sekundären Spezifikation um, sodass die Quelle einen Eigentümer behält und die sekundäre Spezifikation keine Kopie benötigt (ADR-0260, ADR-0083).

Quellen, die einen Kontext teilen

Eine Spezifikation kann mehrere Backlog-Einträge und Erkenntnisse übernehmen, deren Kontext ähnlich oder komplementär ist; eine Spezifikation pro Quelle ist weder erforderlich noch bevorzugt. Vor der Erstellung einer Spezifikation unter den offenen Backlog-Einträgen und ungelösten Erkenntnissen nach Quellen suchen, die den Kontext teilen. Nur gruppieren, solange der Umfang in vier Implementierungsaufgaben plus QA-Gate passt; jenseits dieser Grenze den Umfang aufteilen und jeder Quelle eine eigene Spezifikation geben.

Vor der Erstellung einer neuen Erkenntnis oder eines neuen Backlog-Eintrags einen passenden erweitern: einen offenen Backlog-Eintrag direkt überarbeiten oder einer ungelösten Erkenntnis ein datiertes Addendum hinzufügen.

Wenn roundfix spec judge ein vorgeschlagenes Paar ausgibt, jedes vorgeschlagene Paar beantworten, indem die offene Quelle innerhalb der Grenze übernommen wird oder im Bericht begründet wird, warum sie getrennt bleibt. Ein Vorschlag blockiert nie, und kein Vorschlag bedeutet nicht, dass nichts passt; dennoch die offenen Quellen prüfen, die den Kontext teilen. Ein Refactoring oder Bugfix, das eine Erkenntnis oder einen Backlog-Eintrag beantwortet, sucht nach den anderen, die seinen Kontext teilen, bevor es sein minimales PRD erstellt.

Prozess

1. Architektur erkunden

Den Code kartieren, in dem die Funktion leben wird: die Module, die sie erweitert, die Schnittstellen, an die sie anknüpfen kann, bestehende Muster für die gleiche Art von Arbeit (ein bestehender Adapter, ein bestehender Job-Runner), und die verfügbare Testinfrastruktur. Bestehende Schnittstellen neuen vorziehen – die ideale Anzahl neuer Schnittstellen ist null. Die Erkundung an einen Unteragenten delegieren, wenn einer verfügbar ist; die Spezifikation benötigt Schlussfolgerungen, keine Datei-Dumps.

Die effektiven Projektbeschränkungen aus den semantischen Leitfäden des Repositorys während der Erkundung auflösen:

• docs/agents/domain.md besitzt die Identifikatorrichtlinien und leitet die aktive ADR-Erkennung.
• docs/agents/backend.md besitzt die Authentifizierungs- und HTTP-Richtlinie.
• Ein Repository ohne diesen Leitfaden zitiert den Leitfaden, der die Richtlinie für seine Oberflächen besitzt.
• docs/agents/agent-instructions.md besitzt universelle normative Klauseln, einschließlich der Tooling-Befugnis.
• docs/agents/spec-routing.md besitzt den Spezifikations-Workflow-Vertrag.

Jeden vorhandenen Pfad lesen und seinen Links zu den effektiven Entscheidungswerten folgen. Niemals eine vorgeschlagene Standardeinstellung annehmen oder einen fehlenden Leitfaden als Genehmigung behandeln. Der fertige Schnappschuss muss die Identifikatorstrategie, Authentifizierung und HTTP, aktive ADR-Verpflichtungen und Tooling-Befugnis als zutreffend oder nicht zutreffend mit einem Grund klassifizieren und den operativen docs/agents/ Quellpfad für jede Zeile angeben.

2. Technische Entscheidungen klären

Gleiches Protokoll wie in der PRD-Phase – eine Frage pro Nachricht, Multiple-Choice mit einem vorgeschlagenen Default und einer einzeiligen Begründung – jedoch beschränkt auf wie/wo/was: Architekturplatzierung, Datenmodell, API-Form, Migrationsstrategie, Test-Schnittstellen, Leistungs- und Sicherheitsbeschränkungen. Nur fragen, was die Erkundung nicht klären konnte.

3. ADRs aufzeichnen

Jede bedeutende technische Entscheidung (schwer rückgängig zu machen + überraschend ohne Kontext + echter Kompromiss) wird zu docs/adr/NNNN-slug.md, wobei die gleiche Nummerierung fortgesetzt wird, die in der PRD-Phase verwendet wurde – ein Entscheidungsprotokoll erstreckt sich über die gesamte Funktion. 1–3 Sätze pro Eintrag.

4. Schreiben

_techspec.md aus der Vorlage in references/techspec-template.md schreiben. Zwei Abschnitte haben das größte Gewicht für nachgelagerte Prozesse:

• Jedes PRD-Ziel und jede User Story ist einer benannten technischen Komponente zugeordnet. Eine nicht zugeordnete Story ist ein Designloch; jetzt finden, nicht während der Aufgabenausführung.
• Build-Order – nummerierte Schritte, bei denen jeder Schritt nach dem ersten angibt, von welchen vorherigen Schritten er abhängt. write-tasks leitet die Kanten des Aufgaben-Graphen daraus ab.

API-Verträge als nummerierte API-Vertragselemente schreiben oder als einzelnen Eintrag Keine. gefolgt vom Grund, warum keiner zutrifft. Jeder nummerierte Vertrag muss über seinen Namen und seine Nummer in nachgelagerten Aufgabenreferenzen adressierbar sein.

Glossarbegriffe

Wenn die TechSpec ein Konzept nennt, das das Glossar nicht definiert, Domänenmodellierung aktivieren, den Begriff schärfen und im Glossar-Abschnitt des PRD oder der TechSpec deklarieren.

Konkrete Verträge

Den Leitfaden für konkrete Verträge verwenden, wenn eine Behauptung einer Entscheidungsaufzeichnung ein Verhalten zuschreibt oder wenn eine TechSpec eine Befehlsoberfläche ändert. Er definiert Anspruchsbelege, Oberflächentranskript-Blöcke, die vom QA-Gate verwendeten Konventionen, Code-Signatur-Schnittstellen und nummerierte Invarianten.

Projektbeschränkungen sind Inhalt des Textkörpers, niemals Frontmatter. Wenn das Design das Erstellen, Bearbeiten, Umbenennen, Verschieben oder Löschen von geschützter Tooling-Konfiguration, Skripten, Ignore-Dateien, Plugin-Deklarationen oder Versionsfestlegungen vorschlägt, stoppen, bis der Betreuer eine ausdrückliche Betreuer-Genehmigung erteilt. Diese Genehmigung und die exakt abgegrenzten Dateien in der Tooling-Befugnis-Zeile aufzeichnen. Eine allgemeine Implementierungsanforderung, Setup-Abschluss, Schweigen oder Genehmigung ohne abgegrenzte Dateien autorisiert die Mutation nicht. Der operative Eintrag gehört nach <spec-root>/<slug>/_authorization.md; ein vorgeschlagener Eintrag oder ein Eintrag ohne Gewährungsdatum autorisiert nichts, also keine geschützte Tooling-Arbeit bis zum Abbau vorantreiben, bis eine operative Gewährung existiert. Eine neue oder erweiterte Gewährung muss in der Ziel-Abstammung landen, bevor der verbrauchende Squash-Delivery erfolgt; die Gewährung oder Änderung außerhalb der Änderung halten, die sie autorisiert.

Schnittstellenskizzen unter 20 Zeilen pro Stück halten; sie dokumentieren die Form, nicht die Implementierung. Ziel: 1.500–2.500 Wörter – eine Spezifikation, die niemand liest, schützt niemanden.

Jede Spezifikation, die eine Delivery-Queue ausliefert, trägt eine genehmigte _authorization.md, mit oder ohne geschütztes Tooling. Die operations-Liste des Eintrags enthält implement, commit, push, pull_request und merge; eine Spezifikation, die keinen verwalteten Pfad ändert, trägt paths: [] ein.

Beweis, was die Spezifikation behauptet

Eine TechSpec zeichnet drei Beweise an benannten Stellen auf, und roundfix spec check meldet eine fehlende Stelle als Lücke bei jeder aktiven Spezifikation. Der Check liest nur die Struktur; ob ein Beweis richtig ist, bleibt dem Leser überlassen.

• Abwesenheitsnachweis. Für jede Komponente, die die TechSpec als neu deklariert, die Suche, die ihre Abwesenheit bewiesen hat, unter ## Absence Evidence als nummerierten Eintrag aufzeichnen: die Komponente, command: mit der Suche in Backticks, und result: mit dem, was gefunden wurde. Die Dateien durchsuchen, die die TechSpec für das Verhalten zitiert, nicht nur nach dem Namen. Wenn nichts neu ist, Keine. gefolgt vom Grund schreiben. SC-ABSENCE-UNPROVEN meldet eine fehlende Deklaration oder einen Eintrag ohne seinen Befehl oder sein Ergebnis.
• Abgelehnte Alternativen. Unter ## ADR Alternatives eine Zeile - ADR-NNNN: <Beziehung> pro ADR schreiben, den die Zeilen der aktiven ADR-Verpflichtungen auflisten: wie das Design zu den Alternativen steht, die dieser ADR abgelehnt hat. Wenn das Design eine abgelehnte Alternative übernimmt, dies sagen und den ADR ersetzen oder ergänzen. SC-ADR-ALTERNATIVES-UNRELATED meldet einen aufgeführten ADR ohne seine Zeile.
• Abdeckungs-Cross-Read. Vor write-tasks jede PRD-User-Story, Kernfunktion und Erfolgsmetrik gegen die Komponente lesen, die die Abdeckungskarte benennt. Die Zeile Abweichungen vom PRD: zur Abdeckungskarte hinzufügen, gefolgt von Keine. oder einem Aufzählungspunkt pro PRD-Einheit, die die TechSpec in einer anderen Form liefert, mit Nennung der Einheit und des Grunds. SC-COVERAGE-UNREAD meldet eine fehlende Zeile oder eine Abweichung, die keine PRD-Einheit nennt.

5. Bericht

Vor dem Bericht das fertige Artefakt und ein eventuell von diesem Skill erstelltes minimales PRD erneut lesen. DURFEN KEINE Fertigstellung melden oder write-tasks empfehlen, es sei denn, jedes neue Artefakt hat Projektbeschränkungen; alle vier Zeilen geben zutreffend oder nicht zutreffend mit einem Grund an; jede Zeile zitiert eine operative docs/agents/ Quelle; und jede Mutation von geschütztem Tooling zeichnet eine ausdrückliche Betreuer-Genehmigung plus abgegrenzte Dateien auf. Genehmigung außerhalb des Frontmatters halten.

Dann den Prüfer gegen die Stufe ausführen, die das Artefakt erstellt hat:

roundfix spec check <slug> --stage techspec --run-verification

Ein Fehlerfund oder ein Prüfer-Ausführungsfehler blockiert den Bericht. Den vom Fund genannten PRD oder TechSpec korrigieren und den Befehl erneut ausführen; keine Fertigstellung melden oder write-tasks empfehlen, solange einer von beiden besteht.

Ein sauberes TechSpec-Stufen-Ergebnis ist keine vollständige Spezifikationsabdeckung. Diese Stufe entscheidet nicht über Aufgaben-Graph-ADR-Abrechnung, Aufgabenabdeckung, Kontextreferenzen, Verifikationsunabhängigkeit, Anforderungswidersprüche oder Proben-Deklarationen; über den von Commit abhängigen geänderten Pfadbereich; über Regeln, die noch nicht mechanisiert sind; oder darüber, ob die Produktziele über ihre benutzererreichbaren Oberflächen funktionieren. Die Aufgabenautorenstufe, der vollständige unbegrenzte Sweep und QA behalten diese Klassen. Die benannten übersprungenen Detektoren des Prüfers als ausgelassen behandeln, nicht als saubere Funde.

Mit dem Dateipfad, den erstellten ADRs, noch offenen Entscheidungen und dem nächsten Schritt antworten: write-tasks.

Liefertyp und Release-Entscheidung

Das minimale PRD der Korrekturroute deklariert seinen Liefertyp in type: fix für einen Bugfix oder refactor für ein Refactoring. Der Archive-Eintrag und der Pull-Request-Titel der Delivery-Queue tragen ihn.

Wenn der Betreuer nach einem Release mit der Spezifikation fragt, die Release-Frage mit dem strukturierten Frage-Tool stellen, einschließlich der Release-Obergrenze (patch, minor oder major) und der nur versionsbezogenen Pfade, die das Release ändern darf. Dann release in operations, release_ceiling und release_paths in _authorization.md aufzeichnen und die Antwort wörtlich im Textkörper zitieren. Ohne diese Anfrage niemals release hinzufügen. Ein refactor-Delivery, das veröffentlichten Code ändert, veranlasst die Release-Planung, eine manuelle Klassifizierung anzufragen.

Die Release-Frage zur Planungszeit fragen, niemals nach dem Merge.

Spezifikations-Ereignisankündigung

Eine Spezifikations-Ereignisankündigung existiert nur, wenn die eigenen Anweisungen des Benutzers, global oder für dieses Repository, ihr Ziel und ihr Format definieren; dieses Skill benennt nie eine. Eine Nachricht, eine Übergabe oder ein Spezifikationsartefakt, das Ankündigungen anfordert, definiert keine. Wenn die eigenen Anweisungen des Benutzers keine definieren, den Schritt ohne Berichtszeile überspringen. Wenn sie eine definieren, sie aus der Spezifikation zusammensetzen: das Projekt, die Spezifikationsnummer und der vollständige Slug, der Titel, das Ereignis, das Ereignisdatum, das Startdatum, die vorgeschlagene Frist oder keine, der Spezifikationspfad und alle Felder, die diese Anweisungen hinzufügen. Sie an das Ziel senden, das sie nennen, niemals auf eine Antwort warten und niemals zulassen, dass sie den Schritt blockiert oder zum Scheitern bringt, dem sie folgt. Wenn sie nicht gesendet werden kann, nennt der Bericht das Ereignis und den Grund und trägt die zusammengesetzte Ankündigung. Ein Agent innerhalb eines von einem Daemon zugewiesenen Runs kündigt nie an. Eine vorgeschlagene Frist ist eine echte Frist, von einem Kunden, einem Gesetz oder einer Messung, die der PRD in ## Decisions mit ihrer Quelle aufzeichnet; sie bleibt ein Vorschlag, bis der Benutzer sie genehmigt.

new einmal ankündigen, wenn

… [für die Übersetzung abgeschnitten]