/decide

Vous êtes l'auteur d'un seul document de décision architecturale (ADR) dans ai-docs/decisions/. Le registre de décisions est le substrat qui rend le raisonnement antérieur rappelable — chaque choix significatif qui contraint le travail futur, exclut explicitement une alternative ou fixe une expiration est enregistré afin que les futurs ingénieurs et agents IA puissent le retracer.

Vous NE modifiez PAS le code de production dans cette compétence. Le seul artefact que vous écrivez est le nouveau fichier ADR ou sa modification. Les suggestions de rétroliens vers canonical-patterns.md / architectural-smells.md sont recommandées dans votre résumé, mais ne sont pas exécutées par vous (une tâche d'édition explicite ajoute ces rétroliens après revue humaine).

Comment le succès est évalué

Le nouvel ADR (ou modifié) passe la vérification de l'étape 3 : .venv/bin/python scripts/decisions.py audit et link-check sont propres, avec le résultat réel rapporté.
L'étape 1 a confirmé qu'aucune décision existante ne couvre déjà le sujet — un doublon avorte en --amend ou en supersession, jamais un second ADR pour le même choix.
Les rétroliens related_smell / related_pattern sont définis si applicable, et le résumé recommande les lignes Decided in: NNNN correspondantes — recommandé, pas auto-exécuté.
Rien en dehors de ai-docs/decisions/ n'a été écrit. Écrivez vers ces portes dès l'étape 0.

Croyances fondamentales

Le seuil d'une décision est réel. Tout choix qui (a) contraint une compétence ou un refactor futur, (b) exclut explicitement une alternative, ou (c) fixe une date d'expiration est candidat. Les surprises, notes de débogage et statuts de projet ne sont PAS des décisions — ceux-ci vont dans .claude/tasks/lessons.md, les messages de commit ou les listes de tâches.
Un ADR par choix. Si le travail couvre deux choix couplés, écrivez deux ADR. Un seul ADR documentant deux embranchements indépendants est difficile à remplacer, difficile à lier et devient une entrée de cimetière.
Les rétroliens rendent le registre navigable. Chaque ADR doit définir related_smell et/ou related_pattern dans le préambule le cas échéant, ET votre résumé recommande d'ajouter les rétroliens Decided in: NNNN aux entrées correspondantes de canonical-patterns.md / architectural-smells.md. Sans rétroliens, le registre est en écriture seule.
Supersession plutôt que suppression. Une décision remplacée reste dans le registre avec status: superseded et superseded_by: NNNN. Ne supprimez jamais un ADR — la chaîne est la piste d'audit.
Cadence cible : 2-5/trimestre. Plus que cela sur un seul projet signale un sur-enregistrement — le registre devient un tiroir à bazar. Si vous vous surprenez à rédiger le troisième ADR en une semaine, faites une pause et demandez-vous si les derniers sont vraiment des décisions ou simplement des préférences.
Les ADR rétroactifs sont valides. Une convention de longue date qui contraint le travail futur mérite un ADR même si elle précède le registre. Marquez-la comme telle dans le corps (> ADR rétroactif.).

Analyse des arguments

Quatre formes — choisissez-en exactement une.

Forme A — Nouvel ADR (par défaut)

/decide <slug>

<slug> est un identifiant court en kebab-case du sujet (par ex. textchoices-for-state, spec-first-refactor, celery-safe-dispatch). L'orchestrateur choisit le prochain id 4 chiffres disponible (le plus petit entier non utilisé, avec zéro non significatif), dérive le titre du slug et prépare un ADR avec le statut proposed.

Forme B — Remplacer un ADR existant

/decide --supersede <existing-id> --slug <new-slug>

Écrit un nouvel ADR (prochain id, statut proposed) avec supersedes: [<existing-id>]. Planifie également une modification du préambule de l'ADR remplacé (status: superseded, superseded_by: <new-id>) mais ne le COMMET PAS — le nouvel ADR doit d'abord être approuvé par un humain.

Forme C — Modifier un ADR existant

/decide --amend <id>

Modifiez l'un des champs suivants : status, superseded_by, applies_to, tags, related_smell, related_pattern. Les modifications du corps sont hors de propos (ouvrez le fichier directement pour celles-ci — modifier la décision d'un ADR est elle-même une décision, elle devrait donc généralement être une supersession à la place).

Forme D — Liste

/decide --list

Raccourci pour .venv/bin/python scripts/decisions.py list. Aucun nouveau fichier écrit.

Présentez la spécification analysée à l'utilisateur (intention + id cible + candidats related_smell/related_pattern issus de canonical-patterns.md / architectural-smells.md) et attendez l'approbation avant d'écrire dans les Formes A et B. Les Formes C / D s'exécutent immédiatement.

Le contrat pour le jeton d'approbation correspond à /extract-enum et /fix-workflow : le premier jeton non-vide doit être approved, approve, go, lgtm, proceed, ou yes.

Pipeline

Étape 0 — Configuration

Avant : argument analysé. Après : prochain id résolu (Formes A, B) ; chemin du fichier cible résolu (Forme C) ; ${REPO_ROOT}/ai-docs/decisions/ existe.

# Trouver le prochain id (Formes A, B)
NEXT_ID=$(.venv/bin/python -c "
import pathlib, re
ids = []
for p in pathlib.Path('ai-docs/decisions').glob('[0-9][0-9][0-9][0-9]-*.md'):
    m = re.match(r'(\d{4})-', p.name)
    if m: ids.append(int(m.group(1)))
print(f'{(max(ids)+1) if ids else 1:04d}')
")
NEW_PATH="ai-docs/decisions/${NEXT_ID}-${SLUG}.md"

Si le slug existe déjà à un autre id, abandonnez et recommandez --amend sur l'ADR existant.

Étape 1 — Collecte du contexte

Avant : id cible connu. Après : candidats pattern-connexe et smell-connexe identifiés.

Lisez ces fichiers (petits, rapides, limités au sujet) :

ai-docs/decisions/README.md — conventions du registre
.claude/docs/canonical-patterns.md — recherchez les noms de pattern qui correspondent au sujet de la décision (grep insensible à la casse sur les mots du slug)
.claude/docs/architectural-smells.md — même recherche pour les noms de smell
.venv/bin/python scripts/decisions.py list --json — registre complet (pour ne pas re-décider accidentellement une question déjà décidée)

Pour la Forme B (supersession), lisez également le corps de l'ADR remplacé pour que le nouvel ADR puisse nommer ce qui a changé. Citez directement la phrase Décision de la décision remplacée, puis expliquez la divergence.

Étape 2 — Rédiger l'ADR

Avant : contexte collecté. Après : ${NEW_PATH} écrit (Formes A, B) ou champ modifié par --amend mis à jour (Forme C).

Préparez les Formes A/B avec le script du registre, puis modifiez le fichier généré. La préparation est la source de vérité exécutable pour la forme du préambule :

.venv/bin/python scripts/decisions.py init "${SLUG}"

Forme ADR émise par scripts/decisions.py init — gardez ces champs de préambule présents, même si une valeur est vide :

---
id: "<NNNN>"
namespace: core
title: "<Phrase titre en majuscule — verbe en tête si possible>"
status: proposed              # proposed | accepted | superseded | deprecated
date: <YYYY-MM-DD aujourd'hui>
deciders: []                  # demandez si incertain avant de remplir
supersedes: []                # rempli uniquement en Forme B
superseded_by: null
applies_to: []
embodied_by: []               # requis une fois accepté ; voir ADR 0033
tags: []
related_smell: <ancre-de-smell ou null>      # depuis architectural-smells.md
related_pattern: <ancre-de-pattern ou null>  # depuis canonical-patterns.md
---

# <title>

<Désistement optionnel pour ADR rétroactif>

## Contexte

<2 à 4 paragraphes expliquant l'état antérieur, le problème récurrent et
le déclencheur de cette décision. Soyez précis — citez des fichiers réels,
des incidents réels, des modes de défaillance réels. Un contexte vague = irremplaçable plus tard.>

## Décision

<Un court paragraphe énonçant la règle, puis des puces s'il y a plusieurs
sous-règles. La section Décision est la phrase porteuse unique ;
tout le reste existe pour la soutenir.>

## Alternatives considérées

- **<Nom Alt 1>.** <Déclaration en une ligne>. Rejetée : <raison>.
- **<Nom Alt 2>.** <Déclaration en une ligne>. Rejetée : <raison>.
- (Au moins deux alternatives ; "pas de décision" compte généralement comme une.)

## Conséquences

**Plus facile :**
- <amélioration durable>

**Plus difficile :**
- <compromis que la décision accepte>

**Maintenant attendu / maintenant interdit :**
- <nouvelle contrainte que les lints, les réviseurs ou les futurs agents appliqueront>

## Vérification

- **Outillage** : <règle de lint / test / commande d'audit, avec chemin de fichier>
- **Rétrolien doc** : <quelle entrée canonical-patterns.md / architectural-smells.md
  portera `Decided in: <NNNN>`>
- **Artefacts existants** : <pointeur vers les spécifications / commits / PR qui
  sont déjà conformes>

Après la préparation, remplissez le titre/le corps et les valeurs connues de deciders, applies_to, tags, related_smell et related_pattern. Pour la Forme B, modifiez supersedes: [<existing-id>] dans le nouvel ADR.

Pour la Forme C (amendement), modifiez uniquement le champ de préambule demandé via l'outil Edit. Ne touchez PAS au corps. Si l'amendement définit status: superseded sans superseded_by, abandonnez et demandez l'id de remplacement.

Étape 3 — Vérifier

Avant : ADR écrit. Après : decisions.py audit et link-check se terminent avec code 0.

.venv/bin/python scripts/decisions.py audit && \
  .venv/bin/python scripts/decisions.py link-check

Si l'un échoue, affichez le diagnostic et ARRÊTEZ — l'ADR est sur le disque mais pas enregistré. Échecs courants :

proposed > 30 days — pertinent uniquement pour les ADR plus anciens (n'arrivera pas avec un ADR fraîchement rédigé)
broken supersedes — la modification de l'ADR remplacé de la Forme B n'a pas abouti
applies_to path missing — corrigez le glob applies_to

Étape 4 — Journal d'efficacité

Avant : vérification réussie. Après : une ligne ajoutée à reports/_meta/effectiveness.jsonl.

.venv/bin/python scripts/log_effectiveness.py \
  --skill decide \
  --scan-id "decision-${NEXT_ID}" \
  --target "${NEW_PATH}" \
  --findings-total 1 \
  --buckets "{\"new_decision\": 1}"

Pour la Forme C (amendement), le bucket est {"amended_decision": 1} et findings- total reste 1.

Étape 5 — Résumer

Rapportez à l'utilisateur en ≤8 lignes :

Chemin vers le nouvel ADR (ou modifié).
ID et titre.
Candidats rétroliens pattern-connexe et smell-connexe issus de l'étape 1, avec la ligne exacte que chaque entrée doit ajouter : Decided in: ${NEXT_ID} sous le pattern/smell correspondant.
Commande suivante suggérée :
- Forme A/B : revue humaine → marquer status: accepted via /decide --amend ${NEXT_ID} une fois approuvé.
- Forme C : rien — l'amendement est le travail.

Ne modifiez PAS vous-même canonical-patterns.md / architectural-smells.md. La suggestion du candidat rétrolien est le travail ; l'humain décide s'il faut l'ajouter.

Non-objectifs

Modifier canonical-patterns.md ou architectural-smells.md (recommander le rétrolien, ne l'écrivez pas — c'est une revue séparée).
Ajouter une règle de lint (c'est le travail de /prevent-regression ; l'ADR peut en recommander une dans sa section Vérification).
Créer une nouvelle fonctionnalité / refactor (l'ADR motive le travail ; le travail est /plan-feature ou /refactor-subsystem).
Enregistrer des leçons ou des surprises (celles-ci vont dans .claude/tasks/lessons.md).
Dépasser 2-5 ADR/trimestre sans un pic correspondant de choix transversaux réels — faites une pause et réévaluez.

Quand les choses tournent mal

Symptôme	Action
Le slug existe déjà à un autre id	Abandonner ; recommander `--amend <existant>` à la place
La cible `--supersede` n'existe pas	Abandonner ; demander l'id correct (`/decide --list` pour confirmer)
Le champ de préambule de la cible `--amend` est inconnu	Abandonner ; lister les champs supportés (status, superseded_by, applies_to, tags, related_smell, related_pattern)
`decisions.py audit` se termine avec code 1	Afficher le diagnostic exact ; ne pas journaliser l'efficacité ; demander à l'utilisateur de corriger le registre avant de réessayer
`link-check` trouve une référence `Decided in: NNNN` cassée quelque part	Le signaler mais ne pas modifier la référence cassée ; c'est un nettoyage séparé
La Forme B demande de remplacer un ADR déjà remplacé	Suivre la chaîne jusqu'à la feuille et remplacer la feuille à la place ; signaler la profondeur de la chaîne dans le résumé
L'étape 1 trouve une décision existante qui couvre déjà ce sujet	Abandonner la rédaction du nouvel ADR ; recommander à l'utilisateur `/decide --amend <existant>` pour étendre `applies_to` ou escalader via la supersession

Structure du dépôt

.claude/skills/decide/
├── SKILL.md                  # ce fichier — orchestrateur
└── knowledge/
    └── rules.md              # heuristiques de seuil ADR, anti-patrons

L'orchestrateur (vous) NE lit PAS knowledge/rules.md — ce fichier est une référence hors ligne pour les concepteurs / mainteneurs futurs expliquant les règles de seuil et les anti-patrons ADR courants que la compétence est architecturée pour éviter. De futurs sous-agents explorateurs (si ajoutés) le liraient.

KhurrumMahmood/senior-vibe-engineer

Qu'est-ce que senior-vibe-engineer ?

Demander à votre IA préférée

Documentation