# ADR : Révision du format Epic/Feature/Ticket

## Contexte

À l’ère des agents IA, les spécifications produit doivent être :
- **Lisibles par les humains et les agents** : pas d’ambiguïté qui bloque un assistant IA
- **Traçables** : lier épics → features → tickets sans effort
- **Testables automatiquement** : critères d’acceptation mesurables
- **Flexibles** : pas de rigidité bureaucratique, juste assez de structure

Les anciens format spécifications Word, tickets non structurées rendaient les specs difficilement utilisable pour l’automatisation.

## Décision

Réorganiser les 3 niveaux de spécification :

### Epic
**Résultat observable de haut niveau** : "Fiabiliser le traitement mensuel des redevances"

À compléter :
- **Résultat attendu** : le résultat mesurable
- **Population cible** : pour qui ?
- **Problème concret** : quel pain point résout-on ?
- **Mesures de succès** : comment vérifie-t-on ? (ex: "X réduction d’erreurs", "Y % de couverture")
- **Périmetre** : inclus / hors périmetre
- **Dépendances** : autres épics, équipes, systèmes externes impliqués
- **Features rattachées** : quelles fonctionnalités décomposent cette epic ?
- **Risques & questions ouvertes**

### Feature
**Capacité produit concrète** qui contribue à une epic

À compléter :
- **Objectif** : quelle capacité on livre et pourquoi
- **Utilisateurs concernés** : qui bénéficie ?
- **Périmetre** : inclus / hors périmetre **explicitement** (important pour les agents : dire ce qu’on NE fait PAS)
- **Règles métier** : les logiques métier essentielles
- **Tickets associés** : décomposition en unité atomique de travail pourvant être suivi

### Ticket
**Unité atomique de travail** pour le suivi : 

À compléter :
- **Contexte & objectif** : qu’est-ce qu’on livre ?
- **Valeur/raison** : pourquoi maintenant ?
- **Périmetre** : inclus / exclus
- **Scénarios couverts** : cas d’usage testables
- **Plan d’implémentation** : étapes concrètes
- **Critères d’acceptation** : "condition → résultat attendu" (ex: "Si input X → output Y")

## Pourquoi pas de User Story ?

Le format **User Story** est historiquement utilisé dans les démarches Agile pour exprimer un besoin utilisateur de manière simple.

Sa formulation classique est généralement la suivante :

> En tant que **[utilisateur]**, je veux **[action / besoin]**, afin de **[bénéfice attendu]**.

Ce format a longtemps été utile pour faciliter la discussion entre les équipes métier, produit et développement.

Cependant, dans un contexte où une partie croissante du travail est assistée par des **agents de codage IA**, ce format montre ses limites.
1. Un format trop narratif
La User Story permet d’exprimer une intention, mais elle reste souvent trop narrative.

Elle décrit généralement :

- qui est l’utilisateur ;
- ce qu’il souhaite faire ;
- pourquoi il veut le faire.

Mais elle ne donne pas toujours suffisamment d’éléments exploitables pour passer à l’implémentation.

Un agent de codage a besoin d’un contexte plus structuré que la simple intention utilisateur.

2. Un manque de contraintes opérationnelles

Pour produire un travail pertinent, un agent IA doit comprendre :

- le périmètre exact de la demande ;
- les règles métier ;
- les cas limites ;
- les dépendances techniques ;
- les impacts sur l’existant ;
- les critères de validation ;
- les tests attendus.

Or, ces éléments sont rarement portés naturellement par une User Story classique.

Le risque est donc de produire une formulation lisible pour un humain, mais insuffisante pour une IA chargée de proposer un plan d’implémentation ou de générer du code.


**Décision** : garder Epic → Feature → Ticket. User Story disparaît au profit d’une Feature plus structurée.

## Pourquoi c’est important pour l’IA

1. **Les agents IA lisent mal l’implicite** : une section vague = pas utilisable
   - Exemple : "points d’attention" → trop vague pour un assistant
   - Solution : nommer explicitement "règles métier", "hors périmetre", etc.

2. **Traçabilité du graphe de features** : un agent doit pouvoir vérifier qu’une epic est complète
   - Les liens epic → feature → ticket doivent être explicites

3. **Critères testables** : un bot d’automatisation a besoin de savoir exactement quand un ticket est OK
   - "Condition X → résultat Y" est testable
   - "Coder proprement" ne l’est pas

4. **Flexibilité humaine** : les agents n’imposent pas de structure rigide, juste assez pour l’automatisation

## Impact

- Spécifications plus claires pour les humains
- Agents IA peuvent aider à : valider la complétude, extraire les règles métier, vérifier les critères d’acceptation
- Pas de bureaucratie supplémentaire : sections optionnelles remplies selon le besoin
