Prompt file imported from zekiriabd/SDD-Pro (
.codex/prompts/us-generate.md). Fill in{{arguments}}before use. Copyright stays with the author.
Arguments: {{arguments}}
/us-generate â DĂ©coupe une FEAT en User Stories
â ïž Commande interne v7.0.0 â invoquĂ©e par
/sdd-fullSTEP 2. Utilisateur final : préférer/sdd-fullou/dev-run(gÚrent pré-conditions, idempotence, état).
Invoque l'agent PO pour découper une FEAT fonctionnelle en User
Stories structurées (cible UsGranularityTarget défaut 3, warn au-delà de
UsGranularityWarnAt défaut 6, hard cap UsGranularityHardCap défaut 10)
dans workspace/.
Usage :
/us-generate {n}â oĂč{n}est le numĂ©ro de la FEAT/us-generate {n} --replace-pseudoâ migration POC â standard : supprime la pseudo-US gĂ©nĂ©rĂ©e par/sdd-pocavant de gĂ©nĂ©rer les vraies US
STEP 1 â Valider les arguments
Arguments :
{n}(entier â„ 1, obligatoire)--allow-large-feat(optionnel, v7.0.0 P2 #13) â bypass conscient du hard capUsGranularityHardCap(default 10). Ă utiliser pour FEATs mĂ©tier lĂ©gitimement trĂšs larges (â„ 11 flux distincts). Effet : exportSDD_ALLOW_LARGE_FEAT=1avant invocation agentpo, audit-log dansworkspace/.sys/.audit/force-bypass.log. PrĂ©fĂ©rer split FEAT.--replace-pseudo(optionnel, fix C1 audit 2026-08-30) â migration POC â standard (chemin promis par/sdd-pocSTEP 8 etfeat_to_pseudo_us.py). Supprime AVANT gĂ©nĂ©ration les pseudo-US POC de la FEAT (fichiersworkspace/us/{n}-*.mdportant le marqueur frontmattergenerated-by: feat_to_pseudo_us.py), puis la gĂ©nĂ©ration PO produit les vraies US granulaires. Sans ce flag, une pseudo-US rĂ©siduelle cohabite avec les vraies US (le PO Ă©crase{n}-{m}-{Name}.mdpar basename, pas par{m}â la pseudo{n}-1-{FeatName}.mdsurvivrait si le{Name}rĂ©el diffĂšre) â WARN collision Ă©mis (cf. STEP 2.4 et po.md STEP 2.bis). No-op silencieux si aucune pseudo-US dĂ©tectĂ©e (idempotent).
Si {n} absent â demander :
Quel est le numéro de la FEAT à découper ? (ex. : 1 pour workspace/feats/1-Auth.md)
Si non numĂ©rique â ERROR :
ERROR: /us-generate â argument invalide
CAUSE: [INVALID_ARG] "{argument}" n'est pas un entier
FIX: relancer /us-generate {n} avec n entier (ex. /us-generate 1)
Propagation --allow-large-feat
if [[ "$@" == *--allow-large-feat* ]]; then
export SDD_ALLOW_LARGE_FEAT=1
mkdir -p workspace/.sys/.audit
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) /us-generate {n} --allow-large-feat (bypass UsGranularityHardCap)" \
>> workspace/.sys/.audit/force-bypass.log
fi
L'agent po (STEP 5) lit cette env var pour passer outre le hard cap.
STEP 2 â VĂ©rifier la FEAT existe
Glob workspace/feats/{n}-*.md.
- 0 fichier â ERROR :
ERROR: /us-generate â FEAT introuvable CAUSE: [FEAT_NOT_FOUND] aucun fichier workspace/feats/{n}-*.md FIX: crĂ©er la FEAT via /feat-generate ou la dĂ©poser manuellement -
1 fichier â ERROR :
ERROR: /us-generate â numĂ©rotation invalide CAUSE: [FEAT_AMBIGUOUS] plusieurs fichiers commencent par {n}- dans workspace/feats/ FIX: renommer pour qu'un seul fichier ait le prĂ©fixe {n}-
STEP 2.4 â Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30)
Détecter les pseudo-US POC de la FEAT via le marqueur frontmatter écrit par
feat_to_pseudo_us.py (generated-by: feat_to_pseudo_us.py) :
PSEUDO_US=$(grep -l "generated-by: feat_to_pseudo_us.py" workspace/us/{n}-*.md 2>/dev/null)
if [[ "$@" == *--replace-pseudo* ]]; then
if [ -n "$PSEUDO_US" ]; then
N_PSEUDO=$(echo "$PSEUDO_US" | wc -l)
echo "$PSEUDO_US" | xargs rm -f
echo "[PO] $N_PSEUDO pseudo-US POC supprimée(s) avant génération (--replace-pseudo). (5%)"
else
echo "[PO/SKIP] --replace-pseudo : aucune pseudo-US POC détectée (no-op idempotent). (5%)"
fi
elif [ -n "$PSEUDO_US" ]; then
echo "đĄ [PO/WARN] Pseudo-US POC prĂ©sente(s) sans --replace-pseudo : $PSEUDO_US" >&2
echo " Elle(s) survivront Ă la gĂ©nĂ©ration si le {Name} rĂ©el diffĂšre â doublon d'US {n}-1." >&2
echo " RecommandĂ© : /us-generate {n} --replace-pseudo (migration POC â standard)." >&2
fi
Pourquoi ici et pas dans l'agent
po: la suppression est une dĂ©cision d'orchestration (flag CLI) ; l'agentporeste strictement exĂ©cutif. Il porte nĂ©anmoins le mĂȘme check en filet de sĂ©curitĂ© WARN (invocationpostandalone hors/us-generate) â cf.agents/po.mdSTEP 2.bis.
STEP 2.5 â Checkpoint skip (v6.6.4, opt-in)
Si CheckpointMode: resume dans Project Config (défaut off =
comportement v6.6.3 strict) :
from sdd_lib.checkpoint import is_phase_resumable
inputs = [
f"workspace/feats/{n}-*.md", # FEAT parent
"workspace/stack/stack.md", # Project Config + stacks actifs
]
resumable, reason = is_phase_resumable(
feat=n, phase="us-generate", input_paths=resolved_inputs,
)
if resumable:
print(f"â /us-generate {n}: skipped (checkpoint hit)")
# STOP avec succÚs, ne pas re-déléguer à l'agent PO
Si CheckpointMode â {off, record} â skip ce STEP, continuer.
Ămissions possibles : [CHECKPOINT_HASH_MISMATCH], [CHECKPOINT_INPUT_MISSING],
[CHECKPOINT_STATE_UNREADABLE]. Cf. error-classification.md §1.14.
STEP 3 â Invoquer l'agent PO
Lancer l'agent po (défini dans .claude/agents/po.md) avec le numéro
{n} en argument. L'agent gÚre le découpage, la traçabilité et l'écriture
des fichiers US dans workspace/.
Attendre la fin de l'agent. Relayer sa sortie telle quelle (ligne de succĂšs ou bloc ERROR 3 lignes).
STEP 3.0 â RĂ©soudre le sentinel Parent FEAT hash (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)
Si l'agent po a réussi (US écrites), patcher les sentinels
sha256:COMPUTE_REQUIRED en hash sha256 réel avant STEP 3.bis.
L'agent po n'a pas le tool Bash (cf. po.md frontmatter tools: Read, Write, Edit, Glob, Grep) et ne peut pas calculer le hash
lui-mĂȘme. Il Ă©crit le sentinel littĂ©ral, et cette commande le rĂ©sout
en post-step déterministe (0 token LLM, ~50 ms).
v7.0.0-alpha audit P0-workflow 2026-06-05 â historiquement l'inline
python -c "..."vivait ici. Refactor : extrait verssdd_scripts/resolve_us_hash_sentinel.py(SSoT) + posĂ© comme SubagentStop hook matcher=po(defense-in-depth). Le hook ferme le gap oĂčpoĂ©tait invoquĂ© standalone (hors/us-generate) et laissait le sentinel non rĂ©solu â tous les downstream Ă©mettaient[FEAT_HASH_MISMATCH]. Ce STEP reste le chemin nominal ; le hook est un filet de sĂ©curitĂ© (idempotent â no-op si dĂ©jĂ rĂ©solu).
Invocation (déterministe, 0 token LLM, ~50 ms, cross-platform) :
python .sdd/python/sdd_scripts/resolve_us_hash_sentinel.py --feat-number {n}
Garanties (préservées vs implémentation inline) :
- Aucune dépendance externe (
sed/python/Git Bash) â Python stdlib seulement - UTF-8 sans BOM (compatible parser frontmatter YAML cross-OS)
- Line endings préservés (
newline=''â conserve LF original, pas de CRLF Windows) - Idempotent : re-exĂ©cution sur US dĂ©jĂ patchĂ©es â 0 patch
| Exit | Sens | Action caller |
|---|---|---|
0 |
succÚs (N US patchées OU rien à faire) | continuer STEP 3.bis |
2 |
sentinel persiste aprĂšs patch (corruption FS) | STOP + ERROR [PO_HASH_PLACEHOLDER] |
3 |
erreur infra (FEAT file missing, FS perms) | STOP + ERROR [INFRA_BLOCKED] |
Format ERROR (exit 2) :
ERROR: /us-generate {n} â sentinel hash non rĂ©solu
CAUSE: [PO_HASH_PLACEHOLDER] sha256:COMPUTE_REQUIRED persiste dans {N} fichier(s) US aprĂšs patch
FIX: vérifier permissions FS sur workspace/us/, relancer /us-generate {n} (idempotent)
STEP 3.bis â Checkpoint record (v6.6.4, opt-in)
Si l'agent PO a rĂ©ussi (US Ă©crites) ET CheckpointMode â {record, resume} :
from sdd_lib.checkpoint import record_input_hash
record_input_hash(
run_id=$RUN_ID,
phase="us-generate",
input_paths=resolved_inputs, # FEAT + stack.md
)
Erreur silencieuse si state.json absent â WARN, non bloquant.
STEP 3.ter â Auto-ingest FEAT/US dans console.db (depuis 2026-05-21)
Si l'agent PO a réussi (US écrites), invoquer systématiquement le script
déterministe ingest_feats_us.py pour populer correctement les tables
feats et us de workspace/db/console.db (cf. gap framework
identifiĂ© 2026-05-21 â auparavant seules les colonnes skeleton feat_n +
feat-{n} étaient remplies par les auditors via ensure_feat_skeleton(),
laissant name, actors_json, ac_count, sfd_count, br_count,
fd_count, covers_json, status à null/zéro et brisant l'affichage
de la console web dashboard).
python .sdd/python/sdd_scripts/ingest_feats_us.py 2>&1 | tail -1
| Exit | Sens | Action caller |
|---|---|---|
0 |
Ingest OK | continuer (log 1 ligne [OK] ingested N FEATs + M US) |
1 |
DB introuvable / corrompue | WARN 1 ligne, continuer (non bloquant) |
Idempotent : utilise ON CONFLICT(feat_n|us_id) DO UPDATE â re-exĂ©cution
sans effet sur les counts (rĂ©-Ă©crit avec mĂȘmes valeurs).
Coût : 0 token LLM, ~50 ms, parse markdown déterministe (regex SFD-N /
BR-N / AC-N / FD-N / ## Actors / Covers:).
Non bloquant : un échec de l'ingest n'invalide pas le succÚs du PO. Les US sur disque restent la SSoT ; le DB n'est qu'un cache projeté pour la console web.
STEP 4 â Inventaire des mockups HTML (depuis v4)
Glob workspace/ui/{n}-*.html pour détecter les mockups déjà déposés.
Glob workspace/us/{n}-*.md pour récupérer les basenames d'US.
Cross-check :
- HTML dont basename matche une US â couvert
- HTML dont basename ne matche aucune US â orphelin (WARN)
- US sans HTML â info (frontend possible sans mockup OU backend-only)
Ămettre la liste compactement (1 ligne par US et 1 ligne par orphelin).
Si aucun HTML détecté ET au moins une US a une composante UI attendue,
émettre une info non bloquante invitant à déposer les mockups
(convention {n}-{m}-{Name}.html).
STEP 5 â Confirmation finale
Si l'agent PO réussit, ajouter le récap final :
â
FEAT {n}-{FeatName} â planification terminĂ©e
US générées : {U} fichiers dans workspace/us/
Mockups HTML : {H} fichiers dans workspace/ui/ (ou "aucun")
HTML orphelins : {O} (Ă corriger ou retirer)
US sans mockup : {U-H}
Prochaine étape :
- (optionnel) déposer/réviser les mockups HTML (workspace/ui/{n}-{m}-{Name}.html)
- /dev-run {n} pour matérialiser le code (arch + db + back + front en parallÚle)
- ou /sdd-full {n} pour pipeline complet
Si l'agent échoue, ne rien ajouter (l'ERROR 3 lignes de l'agent suffit).
RĂšgles de cette commande
- Pas de Q/R utilisateur aprĂšs le STEP 1 (l'agent est autonome)
- Pas de modification de la FEAT parente
- Pas de gĂ©nĂ©ration de code (rĂ©servĂ© Ă
/dev-backend,/dev-frontend,/dev-run) - Pas de lecture des mockups HTML ou du stack (réservé aux agents dev-*)
