Étape 2 du cycle · /sdd research
Phase Research — valider la viabilité de l'intention
La phase Research (v1.18, §3.5) s'intercale entre l'Intent Statement et la SPEC. Elle ne juge pas la qualité d'une spécification — c'est le rôle du SQS — mais répond à une question antérieure : cette intention est-elle réalisable, à quel coût, avec quels risques, vu le code réel ?
Pourquoi une étape entre l'Intent et la SPEC
Sans phase Research, le cycle saute directement de l'intention à la spécification : on décrit comment construire quelque chose dont on n'a jamais vérifié que le terrain le permettait. C'est l'anti-pattern « specs-to-code » : des SPECs rédigées en chambre, déconnectées des contraintes existantes — patterns en place, dettes accumulées, dépendances réelles. L'agent découvre ces contraintes en pleine exécution, et la session dérive.
La Research inverse l'ordre des opérations : avant d'écrire la moindre exigence, elle cartographie le code concerné, évalue la faisabilité avec l'architecture actuelle, et liste les risques et inconnues. Le résultat est archivé dans .aiad/research/RESEARCH-NNN-<slug>.md, toujours rattaché à un Intent parent — la Research se rattache à un POURQUOI humain, jamais à une idée flottante.
Elle ne score pas la SPEC (rôle de l'Execution Gate), ne remplace pas l'Intent Statement (le POURQUOI reste humain), et ne décide pas à la place de l'humain : la Research informe, l'humain tranche.
Le Discovery — un ancrage obligatoire dans le code
Le cœur de la Research est le Discovery : une cartographie du code impacté, déléguée à un agent Explore en lecture seule pour préserver le budget de contexte de la session principale. Chaque zone identifiée doit être citée sous la forme chemin:ligne (ou evidence: …), avec ses contraintes existantes et la surface de test déjà en place.
## Discovery (ancrage code — agent Explore, read-only)
- Fichiers / zones impactés : src/auth/login.ts:42, evidence: …
- Contraintes existantes : patterns, dettes, dépendances en place
- Surface de test existante : test/auth/*.test.tsLa règle est dure et volontaire : sans au moins un ancrage réel dans le code, le verdict machine reste JNSP. Une Research sans Discovery est une opinion, pas une analyse. Toute inconnue qui exige une décision humaine se note TODO-JNSP: <question> — elle ne se cache jamais derrière un GO confiant.
Un verdict gradué, tranché par l'humain
La Research se conclut par une ligne de verdict que seul un humain identifiable peut poser (skill human-authorship-check). L'agent rassemble les faits, présente les options, propose éventuellement une recommandation — mais ne fabrique jamais la décision. Le verdict est ensuite durci par un scorer déterministe : npx aiad-sdd research RESEARCH-NNN.
| Décision humaine | Verdict machine | Exit | Suite du cycle |
|---|---|---|---|
| GO | PASS | 0 | /sdd spec autorisé — aucune inconnue bloquante |
| CONDITIONAL GO | CONDITIONAL | 0 | /sdd spec autorisé, conditions explicites à lever |
| DEFER | FAIL | 1 | Reporté (dépendance, timing, info manquante) — nouvelle Research requise |
| NO-GO | FAIL | 1 | Abandonné (coût ou risque trop élevé) — nouvelle Research requise |
| Discovery vide · TODO-JNSP ouvert · verdict absent | JNSP | 2 | Décision humaine requise avant de continuer |
Un CONDITIONAL GO sans conditions listées est rejeté par le scorer (verdict JNSP) : une condition implicite est une inconnue déguisée. Chaque verdict est accompagné d'une confiance exprimée en pourcentage — un GO à 60 % de confiance dit autre chose qu'un GO à 95 %.
Si la ligne Verdict : n'a pas d'auteur humain identifiable, l'agent ne la pose pas et sort JNSP. Fabriquer un GO/NO-GO à la place de l'humain est exactement le type d'invention que le framework interdit.
Le hook discovery-gate.js — un prérequis vérifié
La Research n'est pas une recommandation polie : c'est un prérequis vérifié mécaniquement. Le hook .aiad/hooks/discovery-gate.js est consulté par /sdd spec et /sdd exec : sans Research liée à l'Intent, avec un Discovery ancré et un verdict GO ou CONDITIONAL GO, la rédaction de SPEC et le lancement d'agent sont refusés.
npx aiad-sdd research <RESEARCH-id> # exit 0 → OK · 1 → DEFER/NO-GO · 2 → JNSP
JNSP — Discovery manquant pour INTENT-NNN
Ce qui manque : une Research liée avec Discovery ancré (chemin:ligne)
et verdict GO/CONDITIONAL GO.
Question à l'humain : lance d'abord `/sdd research INTENT-NNN`.Un DEFER ou un NO-GO ferme la porte de /sdd spec de façon durable : il faut une nouvelle Research pour la rouvrir. C'est cohérent avec l'empirisme du framework — si le contexte a changé, on le redémontre sur pièces, on ne recycle pas un verdict périmé.
Proportionnalité — un garde-fou, pas une bureaucratie
Toutes les intentions ne méritent pas une Research complète. Pour une intention triviale et sans risque, le Product Engineer peut court-circuiter explicitement le prérequis — à condition de tracer la décision dans la SPEC. Le court-circuit silencieux, lui, est interdit : c'est la trace qui distingue un choix assumé d'un oubli.
La commande aiad-sdd proportionality <INTENT-id> recommande le chemin court (Research légère) ou le chemin lourd (Research complète) selon le niveau de risque. En mode --guided, la skill grill-me interroge le GO/NO-GO une question à la fois, avec une recommandation que l'humain valide ou corrige.
Une correction de libellé ne justifie pas une Research d'une heure ; une refonte du flux d'authentification, si. Le bon réflexe : --fast pour les intentions claires et peu risquées, mode guidé et Discovery approfondi dès que le code touché est critique.