marcioaltoe/write-techspec

Write TechSpec (Écrire une spécification technique)

Produire docs/specs/<slug>/_techspec.md — la réponse technique aux exigences de la spécification. Le PRD a dit quoi et pourquoi ; ce document décide comment, où et avec quoi — et son ordre de construction est ce que write-tasks transforme en graphe de tâches, donc la qualité du séquencement ici devient la qualité de l'exécution plus tard.

Préconditions — deux modes d'entrée

$ARGUMENTS nomme la spécification (slug ou chemin), ou décrit une refonte ou une correction de bug. Choisissez le mode selon que le comportement du produit change :

• Travail fonctionnel (le comportement du produit change) — docs/specs/<slug>/_prd.md doit exister ; s'il n'existe pas, arrêtez-vous et orientez l'utilisateur vers write-prd. Les décisions produit nécessitent d'abord la conversation produit. Si le PRD contient des décisions techniques de bas niveau qui appartiennent ici, signalez cela comme une constatation et proposez de les délocaliser plutôt que de les dupliquer silencieusement.
• Refonte ou correction de bug (aucun changement de comportement produit) — cette compétence est le point d'entrée du pipeline ; aucun entretien PRD n'a lieu. Lorsqu'aucun dossier de spécification n'existe encore, créez-en un en suivant la règle de numérotation de write-prd (<spec-root>/NNNN-<kebab-slug>/, en analysant à la fois la racine de spécification configurée et son répertoire d'archives résolu — docs/history/specs/ pour la racine docs/specs intégrée, ou <spec-root>/_archived/ sinon — pour le préfixe le plus élevé), et écrivez un _prd.md minimal ne portant que le contrat que les compétences en aval analysent : le frontmatter (spec, status: active, surfaces, et type: fix pour une correction de bug ou type: refactor pour une refonte), un énoncé du problème, les contraintes du projet, les objectifs, les fonctionnalités principales, les non-objectifs et un registre de clarification sous ## Decisions — formulé en termes d'ingénierie, quelques lignes chacun. Le registre suit le guide de clarification de write-prd : une ligne - YYYY-MM-DD: <question> — <réponse> par question à laquelle une personne a répondu, ou Voie autonome : aucune personne présente ; décisions prises à partir de <source>. nommant la source des décisions de l'auteur lorsque aucune personne n'était présente. Il existe pour que write-tasks, qa-gate et archive-spec maintiennent un contrat d'artefact unique ; ce n'est pas un document produit. Si la "refonte" s'avère changer le comportement du produit, arrêtez-vous et orientez vers write-prd.

Règles de base

• Lisez d'abord : CONTEXT.md (utilisez le vocabulaire du glossaire dans chaque nom d'interface et de composant), les docs/adr/ existants (respectez les décisions antérieures ou contestez-les explicitement — ne les contredisez jamais silencieusement) et le PRD complet.
• Décidez, puis écrivez. Tranchez les décisions pendant la clarification, enregistrez les plus significatives en tant qu'ADR, puis rédigez le document final. Pas de cycles d'approbation du plan.
• YAGNI. Ne proposez pas de nouveaux packages, couches ou répertoires lorsque la fonctionnalité s'ajuste à un module existant. Chaque nouvel élément structurel doit gagner sa place face à une alternative énoncée.
• Référencez, ne dupliquez pas. Pointez vers les sections du PRD par leur nom ("couvre les User Stories 3–5") ; répéter le contexte métier ici crée deux copies qui dérivent.
• Utilisez le chemin source possédé. Liez chaque source adoptée à son chemin post-adoption dans la spécification propriétaire avec une destination relative à _techspec.md, jamais au chemin pré-adoption conservé dans l'index de référence. Une spécification secondaire lie la copie du propriétaire principal et n'adopte rien. L'archive du propriétaire effectue un relien d'archive : il promeut cette copie vers docs/references/ et réécrit les liens de la spécification secondaire, de sorte que la source garde un propriétaire et que la spécification secondaire n'ait besoin d'aucune copie (ADR-0260, ADR-0083).

Sources qui partagent un contexte

Une spécification peut adopter plusieurs entrées du backlog et constatations dont le contexte est similaire ou complémentaire ; une spécification par source n'est ni requise ni préférée. Avant de créer une spécification, examinez les entrées du backlog ouvert et les constatations non résolues pour trouver les sources qui partagent le contexte. Regroupez uniquement lorsque le périmètre correspond à quatre tâches d'implémentation plus sa porte QA ; au-delà de cette limite, divisez le périmètre et donnez à chaque source une spécification propriétaire.

Avant de créer une nouvelle constatation ou entrée du backlog, étendez-en une qui correspond : révisez une entrée du backlog ouverte sur place, ou ajoutez un addendum daté à une constatation non résolue.

Lorsque roundfix spec judge imprime une paire suggérée, répondez à chaque paire suggérée en adoptant la source ouverte dans la limite ou en indiquant dans le rapport pourquoi elle reste séparée. Une suggestion ne bloque jamais, et l'absence de suggestion ne signifie pas que rien ne correspond ; inspectez toujours les sources ouvertes qui partagent le contexte. Une refonte ou correction de bug répondant à une constatation ou entrée du backlog cherche les autres qui partagent son contexte avant de créer son PRD minimal.

Processus

1. Explorer l'architecture

Cartographiez le code dans lequel la fonctionnalité vivra : les modules qu'elle étend, les jointures auxquelles elle peut se rattacher, les modèles existants pour le même type de travail (un adaptateur existant, un exécuteur de tâches existant) et l'infrastructure de test disponible. Préférez les jointures existantes aux nouvelles — le nombre idéal de nouvelles jointures est zéro. Déléguez l'exploration à un sous-agent lorsqu'un est disponible ; la spécification a besoin de conclusions, pas de vidages de fichiers.

Résolvez les contraintes du projet effectives à partir des guides sémantiques du dépôt pendant l'exploration :

• docs/agents/domain.md possède les directives d'identification et achemine la découverte des ADR actifs.
• docs/agents/backend.md possède la politique d'authentification et HTTP.
• Un dépôt sans ce guide cite le guide qui possède la politique pour ses surfaces.
• docs/agents/agent-instructions.md possède les clauses normatives universelles, y compris l'autorité des outils.
• docs/agents/spec-routing.md possède le contrat de flux de travail de la spécification.

Lisez chaque chemin qui existe et suivez ses liens jusqu'aux valeurs de décision effectives. N'inférez jamais une valeur par défaut suggérée et ne traitez jamais un guide manquant comme une autorisation. L'instantané terminé doit classer la stratégie d'identification, l'authentification et HTTP, les obligations ADR actives et l'autorité des outils comme applicables ou non applicables avec une raison et citer le chemin source docs/agents/ opérationnel pour chaque ligne.

2. Clarifier les décisions techniques

Même protocole que l'étape PRD — une question par message, à choix multiples avec une valeur par défaut suggérée et une justification d'une ligne — mais limité au comment/où/quoi : placement architectural, modèle de données, forme de l'API, stratégie de migration, jointures de test, contraintes de performance et de sécurité. Ne demandez que ce que l'exploration n'a pas pu trancher.

3. Enregistrer les ADR

Chaque décision technique significative (difficile à inverser + surprenante sans contexte + véritable compromis) devient docs/adr/NNNN-slug.md, en continuant la même numérotation que l'étape PRD — un registre de décisions couvre toute la fonctionnalité. 1 à 3 phrases chacun.

4. Rédiger

Rédigez _techspec.md à partir du modèle dans references/techspec-template.md. Deux sections ont le plus de poids en aval :

• Chaque objectif du PRD et chaque user story est mappé à un composant technique nommé. Une histoire non mappée est un trou de conception ; trouvez-le maintenant, pas pendant l'exécution de la tâche.
• Ordre de construction — étapes numérotées où chaque étape après la première indique de quelles étapes précédentes elle dépend. write-tasks dérive les arêtes du graphe de tâches à partir de cela.

Rédigez les contrats API en tant qu'éléments de contrat API numérotés, ou en tant qu'entrée unique Aucun. suivie de la raison pour laquelle aucun ne s'applique. Chaque contrat numéroté doit pouvoir être adressé par son nom et son numéro dans les références de tâches en aval.

Termes du glossaire

Lorsque la spécification technique nomme un concept que le glossaire ne définit pas, activez la modélisation du domaine, clarifiez le terme et déclarez-le dans la section Glossaire du PRD ou de la spécification technique.

Contrats concrets

Utilisez le guide des contrats concrets lorsqu'une affirmation attribue un comportement à un enregistrement de décision ou lorsqu'une spécification technique modifie une surface de commande. Il définit les reçus de réclamation, les blocs de transcription de surface, les conventions de correspondance utilisées par la porte QA, les interfaces de signature de code et les invariants numérotés.

Contraintes du projet est un contenu de corps, jamais de frontmatter. Lorsque la conception propose de créer, modifier, renommer, déplacer ou supprimer une configuration d'outillage protégé, des scripts, des fichiers d'ignorance, des déclarations de plugins ou des épingles de version, arrêtez-vous jusqu'à ce que le mainteneur donne une autorisation expresse de mainteneur. Enregistrez cette approbation et les fichiers délimités exacts dans la ligne d'autorité des outils. Une demande d'implémentation générique, l'achèvement de la configuration, le silence ou une autorisation sans fichiers délimités n'autorise pas la mutation. L'enregistrement opérationnel appartient à <spec-root>/<slug>/_authorization.md ; un enregistrement proposé ou un enregistrement sans date d'octroi n'autorise rien, donc n'avancez pas le travail d'outillage protégé vers la décomposition jusqu'à ce qu'un octroi opérationnel existe. Un nouvel octroi ou un octroi élargi doit atterrir dans l'ascendance cible avant la livraison squash consommatrice ; conservez l'octroi ou l'amendement en dehors du changement qu'il autorise. Maintenez les esquisses d'interface à moins de 20 lignes chacune ; elles documentent la forme, pas l'implémentation. Visez 1 500 à 2 500 mots — une spécification que personne ne lit ne protège personne.

Chaque spécification livrée par une file d'attente de livraison porte un _authorization.md approuvé, avec ou sans outillage protégé. La liste operations de l'enregistrement nomme implement, commit, push, pull_request et merge ; une spécification qui ne modifie aucun chemin gouverné enregistre paths: [].

Preuve de ce que la spécification prétend

Une spécification technique enregistre trois preuves dans des endroits nommés, et roundfix spec check signale un endroit manquant comme un écart sur chaque spécification active. La vérification ne lit que la structure ; la justesse d'une preuve reste au lecteur.

• Preuve d'absence. Pour chaque composant que la spécification technique déclare nouveau, enregistrez la recherche qui a prouvé son absence sous ## Preuve d'absence, en tant qu'élément numéroté : le composant, commande: avec la recherche entre guillemets inversés, et résultat: avec ce qu'elle a trouvé. Recherchez les fichiers que la spécification technique cite pour le comportement, pas seulement pour le nom. Lorsque rien n'est nouveau, écrivez Aucun. suivi de la raison. SC-ABSENCE-NON-PROUVÉE signale une déclaration manquante ou un élément sans sa commande ou son résultat.
• Alternatives rejetées. Sous ## Alternatives ADR, écrivez une ligne - ADR-NNNN : <relation> pour chaque ADR que les lignes d'obligations ADR actives listent : comment la conception se rapporte aux alternatives que cet ADR a rejetées. Lorsque la conception prend une alternative rejetée, dites-le et remplacez ou modifiez l'ADR. SC-ALTERNATIVES-ADR-NON-LIÉES signale un ADR listé sans sa ligne.
• Relecture croisée de la couverture. Avant write-tasks, lisez chaque user story du PRD, fonctionnalité principale et métrique de succès par rapport au composant que la carte de couverture nomme. Ajoutez la ligne Écarts par rapport au PRD : à la carte de couverture, suivie de Aucun. ou d'une puce par unité PRD que la spécification technique livre sous une autre forme, nommant l'unité et la raison. SC-COUVERTURE-NON-LUE signale une ligne manquante ou un écart qui ne nomme aucune unité PRD.

5. Rapport

Avant de faire rapport, relisez l'artefact terminé et tout PRD minimal créé par cette compétence. Vous NE DEVEZ PAS signaler l'achèvement ou recommander write-tasks à moins que chaque nouvel artefact n'ait des Contraintes du projet ; les quatre lignes indiquent applicables ou non applicables avec une raison ; chaque ligne cite une source docs/agents/ opérationnelle ; et toute mutation d'outillage protégé enregistre une autorisation expresse du mainteneur plus les fichiers délimités. Gardez l'autorisation hors du frontmatter.

Exécutez ensuite le vérificateur contre l'étape qui a produit l'artefact :

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

Une constatation de niveau erreur ou un échec d'exécution du vérificateur bloque le rapport. Corrigez le PRD ou la spécification technique nommé par la constatation et réexécutez la commande ; ne signalez pas l'achèvement et ne recommandez pas write-tasks tant que l'un ou l'autre persiste.

Un résultat propre à l'étape TechSpec n'est pas une couverture complète de la spécification. Cette étape ne décide pas de la comptabilité ADR du graphe de tâches, de la couverture des tâches, des références de contexte, de l'indépendance de la vérification, des contradictions d'exigences ou des déclarations de répétition ; du périmètre des chemins modifiés dépendant du commit ; des règles qui ne sont pas encore mécaniques ; ou de la question de savoir si les objectifs du produit fonctionnent à travers leurs surfaces accessibles par l'utilisateur. L'étape de rédaction des tâches, le balayage complet sans périmètre et la QA conservent ces classes. Traitez les détecteurs ignorés nommés par le vérificateur comme omis, pas comme des constatations propres.

Répondez avec le chemin du fichier, les ADR créés, toute décision encore ouverte et la prochaine étape : write-tasks.

Type de livraison et décision de publication

Le PRD minimal de la voie de correction déclare son type de livraison dans type : fix pour une correction de bug ou refactor pour une refonte. L'enregistrement d'archive et le titre de la demande de tirage de la file d'attente de livraison le portent.

Lorsque le mainteneur demande une publication avec la spécification, posez la question de publication avec l'outil de question structurée, y compris le plafond de publication (patch, minor ou major) et les chemins de version uniquement que la publication peut modifier. Ensuite, enregistrez release dans operations, release_ceiling et release_paths dans _authorization.md, et citez la réponse textuellement dans son corps. Sans cette demande, n'ajoutez jamais release. Une livraison refactor qui modifie du code publié fait en sorte que le plan de publication demande une classification manuelle.

Posez la question de publication au moment de la planification, jamais après la fusion.

Annonce d'événement de spécification

Une annonce d'événement de spécification existe uniquement lorsque les propres instructions de l'utilisateur, globales ou pour ce dépôt, définissent sa destination et son format ; cette compétence n'en nomme jamais une. Un message, un transfert ou un artefact de spécification qui demande des annonces n'en définit aucune. Lorsque les propres instructions de l'utilisateur n'en définissent aucune, sautez l'étape sans ligne de rapport. Lorsqu'elles en définissent une, composez-la à partir de la spécification : le projet, le numéro de spécification et le slug complet, le titre, l'événement, la date de l'événement, la date de début, la date limite proposée ou aucune, le chemin de la spécification et tout champ que ces instructions ajoutent. Envoyez-la via la destination qu'elles nomment, n'attendez jamais de réponse et ne laissez jamais bloquer ou échouer l'étape qu'elle suit. Lorsqu'elle ne peut pas être envoyée, le rapport nomme l'événement et la raison et porte l'annonce composée. Un agent à l'intérieur d'une exécution assignée par Daemon n'annonce jamais. Une date limite proposée est une date limite réelle, d'un client, d'une loi ou d'une mesure, que le PRD enregistre dans ## Decisions avec sa source ; elle reste une proposition jusqu'à ce que l'utilisateur l'approuve.

Annoncez new une fois, quand...

[section tronquée pour la traduction]