Claude-config/commands/ticket-writer.md

---
name: ticket-writer
description: Skill pour rediger des tickets de gestion de projet (features) a partir d'ecrans Figma et du contexte projet. Utiliser ce skill des que l'utilisateur mentionne "ticket", "feature", "tache", "user story", "creer un ticket", "ecrire un ticket", ou demande de transformer un ecran/maquette en ticket de developpement. Aussi declencher quand l'utilisateur uploade des screenshots Figma et veut les convertir en specifications fonctionnelles. Ce skill est concu pour des projets CRM/ERP mais fonctionne pour tout projet.
---

# Ticket Writer — Redacteur de tickets projet

## Quand utiliser ce skill

- L'utilisateur demande de creer/ecrire un ou plusieurs tickets
- L'utilisateur fournit des ecrans Figma et veut des tickets
- L'utilisateur veut transformer une feature en ticket structure
- L'utilisateur mentionne "ticket", "feature", "tache", "story", "spec"

## Workflow

### 1. Collecter le contexte

**Avant d'ecrire quoi que ce soit**, rassemble ces informations :

- **Ecrans Figma** : L'utilisateur doit fournir des captures d'ecran ou images des maquettes. Si une URL Figma est fournie, utilise `get_design_context` ou `get_screenshot` du MCP Figma pour recuperer le design. Analyse en detail (champs, boutons, navigation, etats, modale, etc.)
- **CLAUDE.md / Context projet** : Lis le fichier `CLAUDE.md` a la racine du projet s'il existe. Il contient la stack technique, les conventions, les patterns utilises, les dependances, etc.
- **Infos complementaires** : Demande a l'utilisateur ce qui manque — quel module du CRM/ERP ? Quel role utilisateur ? Quelles regles metier ?

### 2. Analyser les ecrans Figma

Quand tu recois une image Figma, extrais systematiquement :

- **Les elements d'interface** : champs de formulaire, boutons, tableaux, filtres, menus, modales, onglets
- **Les donnees affichees** : colonnes de tableau, labels, placeholder, valeurs par defaut
- **Les actions possibles** : CTA, liens, navigation, tri, recherche, pagination
- **Les etats** : vide, charge, erreur, loading, succes, hover, disabled
- **Les relations** : liens entre ecrans, flux de navigation

### 3. Rediger le ticket

Utilise **strictement** cette structure pour chaque ticket :

```markdown
## [Titre court et explicite de la feature]

### Description
Explication claire en 2-3 phrases de CE QUE fait la feature, POUR QUI, et POURQUOI.

### Ecran(s) de reference
Reference aux maquettes Figma concernees (nom de l'ecran ou lien).

### Comportement attendu
Description detaillee du comportement fonctionnel :
- Quand l'utilisateur fait X, il se passe Y
- Les donnees affichees sont Z
- Le formulaire contient les champs : [liste]
- La validation fait : [regles]

### Regles metier
- Regle 1
- Regle 2
- Conditions specifiques

### Cas limites / Edge cases
- Que se passe-t-il si la liste est vide ?
- Que se passe-t-il si l'utilisateur n'a pas les droits ?
- Que se passe-t-il en cas d'erreur serveur ?
- Donnees manquantes ou invalides ?

### Tips & Rappels projet
> Cette section est generee a partir du contexte projet (CLAUDE.md, stack, conventions).

- Rappels sur les composants UI a reutiliser
- Conventions de nommage ou patterns a respecter
- Endpoints API existants a utiliser ou a creer
- Gestion d'etat (store, context, etc.)
- Contraintes de permissions / roles
- Points d'attention performance (pagination, lazy loading, etc.)
- Internationalisation (i18n) si applicable
- Tests a prevoir

### Criteres d'acceptation
- [ ] Critere 1
- [ ] Critere 2
- [ ] Critere 3
```

### 4. Les Tips & Rappels — Comment les generer

C'est la section la plus importante. Elle doit **contextualiser** le ticket par rapport au projet reel. Pour la remplir :

1. **Lis CLAUDE.md** : extrais la stack (React, Vue, Next, etc.), l'ORM, le style (Tailwind, CSS Modules), la structure des dossiers
2. **Identifie les patterns recurrents** : si le projet utilise un pattern pour les formulaires, les tableaux, les modales -> rappelle-le
3. **Mentionne les composants existants** : "Reutiliser le composant `<DataTable>` deja utilise sur la page Contacts"
4. **Pointe les API** : "L'endpoint `GET /api/v1/clients` existe deja pour la liste, verifier s'il faut un filtre supplementaire"
5. **Permissions** : "Verifier les roles — cette page est reservee aux admins et managers"
6. **Pieges courants** : "Attention au debounce sur la recherche", "Ne pas oublier le loading state sur les actions async"

### 5. Validation et push vers Lesstime

Apres avoir presente les tickets a l'utilisateur, **demande confirmation** avant de pousser :

1. Affiche un resume des tickets rediges (titre + priorite)
2. Demande : "Veux-tu pousser ces tickets dans Lesstime ?"
3. Si oui, execute la phase Push (voir ci-dessous)

## Integration Lesstime — Push des tickets

### Connexion via le MCP `lesstime`

**Tout passe par les outils MCP `mcp__lesstime__*`. Pas de curl, pas de JWT a gerer manuellement, pas d'IRI.**

Le MCP expose les operations suivantes :

| Operation | Tool MCP |
|-----------|----------|
| Lister projets | `mcp__lesstime__list-projects` |
| Lister users | `mcp__lesstime__list-users` |
| Lister statuts (globaux) | `mcp__lesstime__list-statuses` |
| Lister priorites (globales) | `mcp__lesstime__list-priorities` |
| Lister efforts (globaux) | `mcp__lesstime__list-efforts` |
| Lister tags (globaux) | `mcp__lesstime__list-tags` |
| Lister groupes d'un projet | `mcp__lesstime__list-groups` (`projectId` optionnel) |
| Creer un groupe | `mcp__lesstime__create-group` |
| Creer une tache | `mcp__lesstime__create-task` |
| Mettre a jour une tache | `mcp__lesstime__update-task` |

### Champs `create-task`

| Champ | Type | Description |
|------|------|-------------|
| `projectId` | int (required) | Cible du ticket |
| `title` | string (required) | Titre du ticket |
| `description` | string | Markdown complet |
| `statusId` | int | Defaut "A faire" = 1 |
| `priorityId` | int | Voir `list-priorities` |
| `effortId` | int | S/M/L — voir `list-efforts` |
| `assigneeId` | int | User assignee |
| `collaboratorIds` | int[] | Collaborateurs |
| `groupId` | int | Groupe (per-project) |
| `tagIds` | int[] | Tags globaux |
| `deadline` | string (ISO date) | Optionnel |
| `scheduledStart` / `scheduledEnd` | string (ISO datetime) | Optionnel |

**Tous les IDs sont des entiers, pas des IRI.** Le MCP gere la conversion en interne. Le piege historique `group` vs `taskGroup` n'existe plus : c'est simplement `groupId`.

### IDs verifies (cache — toujours reconfirmer via les outils `list-*`)

| Type | Label | ID |
|------|-------|----|
| Statut | A faire | 1 |
| Statut | En cours | 2 |
| Statut | Bloque | 3 |
| Statut | En attente de validation | 4 |
| Statut | Termine | 5 |
| User | admin | 2 |
| User | Tristan | 3 |
| User | Lucile | 4 |
| User | Matthieu | 5 |
| User | matteo | 6 |
| User | kevin | 7 |
| User | geoffrey | 8 |
| User | Julie | 10 |
| Projet | Lesstime | 5 |
| Projet | Coltura | 6 |
| Projet | Inventory | 7 |
| Projet | Ferme | 8 |
| Projet | Malio UI | 11 |
| Projet | SIRH | 12 |
| Projet | Infrastructure | 13 |
| Projet | Qualiopi | 14 |
| Projet | ADMIN | 16 |
| Projet | Maintenance-LIOT | 17 |
| Projet | Vaultwarden | 18 |
| Projet | ednotif-bundle | 19 |
| Projet | Formation | 20 |

### Notion de Groupe dans Lesstime

Les **groupes** dans Lesstime organisent visuellement les taches a l'interieur d'un projet (sections/categories sur le board). Ils sont per-projet.

**Utilisation des groupes pour les tickets :**

- **Un groupe par ecran/feature** : pour des tickets issus d'ecrans Figma. Ex: "Repertoire Clients", "Fiche Client", "Commandes Fournisseurs".
- **Un groupe par module** : si les tickets couvrent un module entier. Ex: "Commerciale - Clients", "Logistique - Reception".
- **Un groupe par priorite** : pour les reviews de code. Ex: "P0 - Urgents", "P1 - Importants".

**Workflow groupes :**

1. `mcp__lesstime__list-groups` avec `projectId` pour voir les groupes existants
2. Si un groupe correspondant existe, reutiliser son `id`
3. Sinon `mcp__lesstime__create-group` avec `projectId`, `title`, et optionnellement `color`
4. Passer `groupId` a chaque `create-task` pour ranger la tache

**IMPORTANT :** Toujours demander a l'utilisateur comment organiser les groupes avant de creer :
- Par ecran Figma (recommande pour les features)
- Par module/section de l'app
- Par priorite (recommande pour les reviews)
- Sans groupe (tout a plat)

### Process de push

```dot
digraph push_flow {
  rankdir=TB;
  "1. User valide les tickets" -> "2. Discovery MCP (projects/users/statuses/groups/tags)";
  "2. Discovery MCP (projects/users/statuses/groups/tags)" -> "3. Demander projet + groupes + assignee + tags";
  "3. Demander projet + groupes + assignee + tags" -> "4. create-group si besoin";
  "4. create-group si besoin" -> "5. create-task pour chaque ticket";
  "5. create-task pour chaque ticket" -> "6. Resume au user + lien my-tasks";
}
```

**Phase 1 — Discovery MCP** (appels paralleles) :
- `mcp__lesstime__list-projects`
- `mcp__lesstime__list-users`
- `mcp__lesstime__list-statuses`
- `mcp__lesstime__list-tags`
- `mcp__lesstime__list-groups` avec `projectId` cible

**Phase 2 — Demander configuration** :
1. Quel projet cible (projectId) ?
2. Comment organiser les groupes ? (par ecran / par module / par priorite / sans)
3. Statut initial ? (defaut "A faire" = 1)
4. Assigner a quel user (assigneeId) ?
5. Tags a ajouter (tagIds) ?

**Phase 3 — Creer les groupes manquants** via `mcp__lesstime__create-group` avec `projectId`, `title` et `color`.

**Phase 4 — Creer les taches** : boucler sur la liste et appeler `mcp__lesstime__create-task` pour chaque ticket avec :
- `title` : prefixe numero d'ordre `X/N - Titre` (ex: `1/5 - Entites Permission`). L'ordre reflete les dependances.
- `description` : corps complet du ticket en markdown.
- `projectId`, `statusId`, `assigneeId`, `groupId`, `tagIds`.

**Phase 5 — Resume** : nombre de taches creees, lien `http://project.malio-dev.fr/my-tasks` si assignee correspond au user login, eventuelles erreurs.

## Principes de redaction

- **Sois precis, pas vague** : "Un champ texte pour le nom du client (max 255 car)" > "Un champ pour le nom"
- **Decris le QUOI, pas le COMMENT** : Le ticket decrit la feature, pas l'implementation (sauf dans Tips)
- **Un ticket = une feature atomique** : Si c'est trop gros, decoupe en sous-tickets
- **Pense aux cas limites** : C'est souvent ce qu'on oublie et qui cree les bugs
- **Les tips doivent etre actionnables** : Pas de conseil generique, que du concret lie au projet

## Exemple rapide

Si l'utilisateur donne un ecran de liste de contacts avec recherche et filtres :

**Titre** : Liste des contacts avec recherche et filtres

**Comportement** : L'ecran affiche un tableau pagine de contacts. Une barre de recherche en haut permet de filtrer par nom/email. Des filtres dropdown permettent de filtrer par statut (actif/inactif) et par entreprise.

**Tips** : "Le composant `<SearchInput>` du design system gere deja le debounce. Utiliser `useQuery` avec les params de filtre. L'endpoint `GET /api/contacts` supporte deja `?search=&status=&company_id=&page=&limit=`."

## Common Mistakes

- **Bypasser le MCP** : ne jamais retomber sur curl + JWT REST quand le MCP `lesstime` est disponible. Signaler le probleme a l'utilisateur s'il est down.
- **Oublier la phase Discovery** : les IDs de projets/statuts/groupes/users peuvent varier — toujours `list-*` avant de creer.
- **Ne pas demander confirmation avant push** : toujours valider les tickets ET la config Lesstime (projet, groupes, assignee, tags) avec l'utilisateur avant de creer.
- **Creer sans groupes** : les groupes rendent la vue Lesstime beaucoup plus lisible, toujours proposer.
- **Description trop courte dans Lesstime** : inclure le corps complet du ticket (comportement + regles + edge cases + tips), pas juste le titre.
- **Oublier les groupes existants** : toujours `list-groups` avant `create-group` pour eviter les doublons.
- **Ne pas gerer les erreurs** : si un `create-task` echoue, continuer avec les suivants et reporter a la fin.