Cadrer en OPALE

Une story OPALE se prépare avant de se coder : analyse, cadrage, spécifications, plan, puis exécution. Vous venez ici quand vous voulez poser le problème avec votre agent, noter les décisions et les questions, ou, au contraire, corriger un défaut sans cérémonie.

Ce que vous demandez à l'agent

💬 Vous demandez à l’agent

« Crée les documents de cadrage de la story 003 de l'épic 012. »

→ L’agent appelleeffortless_cadrage_docs_scaffold

• epic_id = 012
• story_id = 003

💬 Vous demandez à l’agent

« Note, sur la story 003 de l'épic 012, la décision « Exporter en CSV » en phase de cadrage, parce qu'Excel doit ouvrir les exports ; conséquence : gérer l'encodage ; alternative écartée : le JSON. »

→ L’agent appelleeffortless_decision_add

• epic_id = 012
• story_id = 003
• title = Exporter en CSV
• context = Excel doit ouvrir les exports
• decision = Exporter en CSV
• consequences = Gérer l’encodage
• rejected_alternatives = Le JSON
• phase = P-cadrage

💬 Vous demandez à l’agent

« Pose, sur la story 003 de l'épic 012, la question de l'authentification en phase de cadrage : contexte, l'application sera multi-utilisateur ; impact, rien n'avance sans réponse ; suggestion, OAuth2. »

→ L’agent appelleeffortless_question_ask

• epic_id = 012
• story_id = 003
• question = Quelle authentification ?
• context = L’application sera multi-utilisateur
• impact = Rien n’avance sans réponse
• suggestion = OAuth2
• phase = P-cadrage

💬 Vous demandez à l’agent

« Est-ce qu'on peut passer à la phase suivante ? »

→ L’agent appelleeffortless_phase_eligibility

💬 Vous demandez à l’agent

« Liste les décisions et les questions ouvertes du projet. »

→ L’agent appelleeffortless_decisions_list

💬 Vous demandez à l’agent

« Propose trois stories pour découper cet épic : l'export CSV, l'export Excel, l'archivage. Je validerai. »

→ L’agent appelleeffortless_draft_add

• title = L’export CSV

💬 Vous demandez à l’agent

« C'est un petit correctif, « Corriger l'accent dans l'export » : ouvre une story de correction directe, sans cadrage. »

→ L’agent appelleeffortless_story_start

• title = Corriger l’accent dans l’export
• kind = fix

💬 Vous demandez à l’agent

« Quelles recettes restent à vérifier ? »

→ L’agent appelleeffortless_recipe_maturity

Ce que fait l'agent

Préparer les documents d'une story

1. effortless_cadrage_docs_scaffold avec epic_id et story_id : crée dans blueprints/ les documents OPALE manquants de la story et renvoie les fichiers créés. Les documents déjà là ne sont pas touchés.
2. effortless_cadrage_layer_next : au niveau du projet, indique la prochaine couche de cadrage à rédiger parmi les quatre blueprints racine.

Faire avancer les phases

Une story OPALE traverse cinq phases : O-analyse, P-cadrage, A-specs, L-plan, E-execute.

1. effortless_phase_eligibility : lecture seule. Dit si les documents requis de la phase courante existent et quelle est la phase suivante.
2. effortless_phase_next : passe à la phase suivante, avec la date posée par le serveur. Le moteur refait lui-même la vérification de son côté.
3. effortless_story_reloop, si le cadrage est à reprendre : target_phase désigne une phase antérieure à la phase courante.

Tant que la story est avant la phase E-execute, une tâche ne peut pas passer à En cours (voir Piloter le travail).

Consigner les décisions

1. effortless_decision_add : une décision (ADR) rattachée à une story. L'agent renseigne epic_id, story_id, title, context, decision, consequences, rejected_alternatives et la phase OPALE concernée. Le moteur renvoie l'identifiant DEC-NN.
2. effortless_decisions_list : toutes les décisions du projet, avec l'épic et la story d'origine.

Poser et résoudre des questions

1. effortless_question_ask : une question ouverte sur une story (question, context, impact, suggestion, phase). Le moteur renvoie Q-NN.
2. effortless_question_resolve : la résout avec sa answer.
3. effortless_questions_list : toutes les questions du projet.

Les grandes questions ouvertes (BQO)

Une BQO est une question posée au niveau du projet, pas d'une story.

1. effortless_bqo_ask : la consigne.
2. effortless_bqo_list : les liste.
3. effortless_bqo_resolve : y répond (question_id, answer).
4. effortless_bqo_graduate : si elle mérite un chantier, la copie dans un épic existant (epic_id). Ne crée pas d'épic ; la question n'est plus à résoudre au niveau du projet mais depuis cet épic.

Brouillons de story

Pour découper un épic sans créer les stories tout de suite.

1. effortless_draft_add : un brouillon (titre, résumé, kind opale ou fix, tâches proposées, justification, dépendances) dans l'épic actif ou l'épic nommé.
2. effortless_draft_update : corrige un brouillon ; ce qui n'est pas passé reste inchangé.
3. effortless_draft_list : liste ceux d'un épic.
4. effortless_draft_submit : le soumet à votre relecture.
5. effortless_draft_validate : le transforme en vraie story et renvoie l'identifiant créé.
6. effortless_draft_reject : l'écarte.

L'agent soumet ; c'est vous qui dites de valider ou de rejeter.

Propositions sur une story

Une proposition est un résumé attaché à une story, qui attend votre verdict.

1. effortless_proposal_add : la pose (statut en attente) sur la story active, ou sur story_id.
2. effortless_proposal_validate : la valide.
3. effortless_proposal_reject : la rejette.

La voie courte : un correctif

Pour un défaut à corriger tout de suite, l'agent n'a pas besoin de cadrer.

1. effortless_story_start avec kind: "fix" : la story ne demande aucun cadrage et s'ouvre directement en phase d'exécution. Avec activate: true, elle devient la story active.
2. effortless_task_add puis effortless_task_update : la suite se passe comme pour une story normale (Piloter le travail).

Les recettes et les preuves

1. effortless_recipe_maturity : lecture seule. Classe les scénarios de recette par maturité (stable, candidat, beta, prévu), rend ce qu'il reste à faire et les recettes bloquées par un manque. Option : limiter à un epic_id ou un story_id.
2. effortless_interruption_proof : prouve qu'un ordre d'écriture survit à une interruption réelle. Le moteur coupe la commande déclarée (SIGKILL) à chaque position qu'elle annonce, puis lance le contrôle d'état. proof_id désigne une preuve que vous avez déclarée dans effortless.json, sous settings.interruption_proofs ; positions restreint les coupures (par défaut, toutes).

Ce que vous obtenez

• Des documents de cadrage dans blueprints/, en Markdown, à relire dans votre éditeur.
• Les décisions et les questions dans l'écran Connaissance, avec leur origine.
• Les stories, leur phase et leurs brouillons dans le Backlog (blocs Drafts, Proposition et Reloop sur les pages d'épic et de story).
• Les questions ouvertes et les recettes non vérifiées dans Ce qui t'attend du Tableau de bord.

Quand l'agent est refusé

Situation	Ce que dit le refus	Ce qu'il faut faire
Une tâche passe à En cours alors que la story n'a pas fini son cadrage	cadrage:phaseIncomplete	Rendre les documents manquants de la phase, ou ouvrir un correctif direct avec story_start et kind: "fix".
Passage à la phase suivante, documents requis absents	pilotage:phaseMissingDocs	Rédiger les documents nommés par le refus.
Passage à la phase suivante alors que la story est déjà en dernière phase	pilotage:phaseAlreadyLast	Rien à lever : clore la story, ou la reboucler vers une phase antérieure.
Phase déjà complétée	pilotage:phaseAlreadyCompleted	Avancer vers la phase suivante, ou revenir en arrière avec story_reloop.
Décision dont un champ contient une entité HTML échappée (par exemple &)	cadrage:entiteHtml	Réécrire le champ sans l'entité.
Résoudre au niveau projet une BQO déjà graduée en épic	cadrage:questionGraduated	Répondre depuis les BQO de l'épic qui la porte, avec question_resolve.
BQO inconnue	cadrage:questionNotFound	Lister les BQO avec bqo_list et reprendre le bon identifiant.
Lire les items d'une story sans nommer l'épic et la story	pilotage:noStoryTarget	Passer epic_id ET story_id ; project_tree les nomme.
Preuve d'interruption non déclarée	proof:unknown	La déclarer dans settings.interruption_proofs de effortless.json.
Preuve dont la commande n'annonce aucune position	proof:noPosition	Faire écrire EFFORTLESS-POS <n> à la commande à chaque point de coupure.
Preuve dont la commande ne se lance pas	proof:launchFailed	Vérifier la commande déclarée.