Gestion des Tracks

Guide pour créer, gérer et compléter les tracks Conductor - les unités de travail logiques qui organisent les fonctionnalités, les bugs et les refactorisations à travers les phases de spécification, planification et implémentation.

Quand utiliser cette compétence

Créer des tracks de fonctionnalité, bug ou refactorisation
Écrire ou réviser les fichiers spec.md
Créer ou mettre à jour les fichiers plan.md
Gérer le cycle de vie des tracks de la création à l'achèvement
Comprendre les marqueurs et conventions d'état des tracks
Travailler avec le registre tracks.md
Interpréter ou mettre à jour les métadonnées des tracks

Concept de Track

Un track est une unité de travail logique qui encapsule une pièce de travail complète. Chaque track possède :

Un identifiant unique
Une spécification définissant les exigences
Un plan phasé décomposant le travail en tâches
Des métadonnées suivi l'état et la progression

Les tracks fournissent une organisation sémantique du travail, permettant :

Des limites de portée claires
Le suivi de la progression
Des opérations sensibilisées à Git (revenir en arrière par track)
La coordination d'équipe

Types de Tracks

feature

Nouvelles fonctionnalités ou capacités. À utiliser pour :

Nouvelles fonctionnalités visibles pour l'utilisateur
Nouveaux points de terminaison API
Nouvelles intégrations
Améliorations significatives

bug

Correctifs de défauts. À utiliser pour :

Comportement incorrect
Conditions d'erreur
Régressions de performance
Vulnérabilités de sécurité

chore

Maintenance et tâches courantes. À utiliser pour :

Mises à jour de dépendances
Changements de configuration
Mises à jour de documentation
Tâches de nettoyage

refactor

Amélioration du code sans changement de comportement. À utiliser pour :

Restructuration du code
Adoption de patterns
Réduction de la dette technique
Optimisation de performance (même comportement, meilleure performance)

Format d'ID de Track

Les IDs de track suivent le pattern : {shortname}_{YYYYMMDD}

shortname: Description en kebab-case de 2-4 mots (ex. user-auth, api-rate-limit)
YYYYMMDD: Date de création au format ISO

Exemples :

user-auth_20250115
fix-login-error_20250115
upgrade-deps_20250115
refactor-api-client_20250115

Cycle de vie d'un Track

1. Création (newTrack)

Définir les exigences

Recueillir les exigences par Q&A interactif
Identifier les critères d'acceptation
Déterminer les limites de portée
Identifier les dépendances

Générer la spécification

Créer spec.md avec les exigences structurées
Documenter les exigences fonctionnelles et non-fonctionnelles
Définir les critères d'acceptation
Lister les dépendances et contraintes

Générer le plan

Créer plan.md avec la décomposition des tâches par phase
Organiser les tâches en phases logiques
Ajouter les tâches de vérification après les phases
Estimer l'effort et la complexité

Enregistrer le track

Ajouter une entrée au registre tracks.md
Créer la structure du répertoire du track
Générer metadata.json
Créer le index.md du track

2. Implémentation

Exécuter les tâches

Sélectionner la tâche suivante en attente dans le plan
Marquer la tâche comme en cours
Implémenter en suivant le workflow (TDD)
Marquer la tâche complète avec le SHA du commit

Mettre à jour le statut

Mettre à jour les marqueurs de tâche dans plan.md
Enregistrer les SHAs de commit pour la traçabilité
Mettre à jour la progression de phase
Mettre à jour le statut du track dans tracks.md

Vérifier la progression

Compléter les tâches de vérification
Attendre l'approbation du checkpoint
Enregistrer les commits de checkpoint

3. Achèvement

Synchroniser la documentation

Mettre à jour product.md si des fonctionnalités ont été ajoutées
Mettre à jour tech-stack.md si les dépendances ont changé
Vérifier que tous les critères d'acceptation sont satisfaits

Archiver ou supprimer

Marquer le track comme complété dans tracks.md
Enregistrer la date d'achèvement
Archiver ou conserver le répertoire du track

Structure de la Spécification (spec.md)

# {Track Title}

## Overview

Brève description de ce que ce track accomplit et pourquoi.

## Functional Requirements

### FR-1: {Requirement Name}

Description de l'exigence fonctionnelle.

- Acceptance: Comment vérifier que cette exigence est satisfaite

### FR-2: {Requirement Name}

...

## Non-Functional Requirements

### NFR-1: {Requirement Name}

Description de l'exigence non-fonctionnelle (performance, sécurité, etc.)

- Target: Cible mesurable spécifique
- Verification: Comment tester

## Acceptance Criteria

- [ ] Criterion 1: Condition spécifique et testable
- [ ] Criterion 2: Condition spécifique et testable
- [ ] Criterion 3: Condition spécifique et testable

## Scope

### In Scope

- Éléments explicitement inclus
- Fonctionnalités à implémenter
- Composants à modifier

### Out of Scope

- Éléments explicitement exclus
- Considérations futures
- Travail connexe mais séparé

## Dependencies

### Internal

- Autres tracks ou composants dont dépend celui-ci
- Artefacts de contexte requis

### External

- Services ou APIs tiers
- Dépendances externes

## Risks and Mitigations

| Risk             | Impact          | Mitigation          |
| ---------------- | --------------- | ------------------- |
| Description du risque | High/Medium/Low | Stratégie d'atténuation |

## Open Questions

- [ ] Question qui a besoin de résolution
- [x] Question résolue - Réponse

Structure du Plan (plan.md)

# Implementation Plan: {Track Title}

Track ID: `{track-id}`
Created: YYYY-MM-DD
Status: pending | in-progress | completed

## Overview

Brève description de l'approche d'implémentation.

## Phase 1: {Phase Name}

### Tasks

- [ ] **Task 1.1**: Description de la tâche
  - Sous-tâche ou détail
  - Sous-tâche ou détail
- [ ] **Task 1.2**: Description de la tâche
- [ ] **Task 1.3**: Description de la tâche

### Verification

- [ ] **Verify 1.1**: Étape de vérification pour la phase

## Phase 2: {Phase Name}

### Tasks

- [ ] **Task 2.1**: Description de la tâche
- [ ] **Task 2.2**: Description de la tâche

### Verification

- [ ] **Verify 2.1**: Étape de vérification pour la phase

## Phase 3: Finalization

### Tasks

- [ ] **Task 3.1**: Update documentation
- [ ] **Task 3.2**: Final integration test

### Verification

- [ ] **Verify 3.1**: All acceptance criteria met

## Checkpoints

| Phase   | Checkpoint SHA | Date | Status  |
| ------- | -------------- | ---- | ------- |
| Phase 1 |                |      | pending |
| Phase 2 |                |      | pending |
| Phase 3 |                |      | pending |

Conventions de marqueurs d'état

Utiliser des marqueurs cohérents dans plan.md :

Marker	Meaning	Usage
`[ ]`	En attente	Tâche non commencée
`[~]`	En cours	Actuellement en cours
`[x]`	Complète	Tâche terminée (inclure SHA)
`[-]`	Ignorée	Intentionnellement non faite
`[!]`	Bloquée	En attente de dépendance

Exemple :

- [x] **Task 1.1**: Set up database schema `abc1234`
- [~] **Task 1.2**: Implement user model
- [ ] **Task 1.3**: Add validation logic
- [!] **Task 1.4**: Integrate auth service (blocked: waiting for API key)
- [-] **Task 1.5**: Legacy migration (skipped: not needed)

Format du Registre de Tracks (tracks.md)

# Track Registry

## Active Tracks

| Track ID                                         | Type    | Status      | Phase | Started    | Assignee   |
| ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- |
| [user-auth_20250115](tracks/user-auth_20250115/) | feature | in-progress | 2/3   | 2025-01-15 | @developer |
| [fix-login_20250114](tracks/fix-login_20250114/) | bug     | pending     | 0/2   | 2025-01-14 | -          |

## Completed Tracks

| Track ID                                       | Type  | Completed  | Duration |
| ---------------------------------------------- | ----- | ---------- | -------- |
| [setup-ci_20250110](tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days   |

## Archived Tracks

| Track ID                                             | Reason     | Archived   |
| ---------------------------------------------------- | ---------- | ---------- |
| [old-feature_20241201](tracks/old-feature_20241201/) | Superseded | 2025-01-05 |

Champs de métadonnées (metadata.json)

{
  "id": "user-auth_20250115",
  "title": "User Authentication System",
  "type": "feature",
  "status": "in-progress",
  "priority": "high",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T14:45:00Z",
  "started": "2025-01-15T11:00:00Z",
  "completed": null,
  "assignee": "@developer",
  "phases": {
    "total": 3,
    "current": 2,
    "completed": 1
  },
  "tasks": {
    "total": 12,
    "completed": 5,
    "in_progress": 1,
    "pending": 6
  },
  "checkpoints": [
    {
      "phase": 1,
      "sha": "abc1234",
      "date": "2025-01-15T13:00:00Z"
    }
  ],
  "dependencies": [],
  "tags": ["auth", "security"]
}

Opérations sur les Tracks

Créer un track

Exécuter /conductor:new-track
Répondre aux questions interactives
Réviser le spec.md généré
Réviser le plan.md généré
Confirmer la création du track

Démarrer l'implémentation

Lire spec.md et plan.md
Vérifier que les artefacts de contexte sont actuels
Marquer la première tâche comme [~]
Commencer le workflow TDD

Compléter une phase

S'assurer que toutes les tâches de la phase sont [x]
Compléter les tâches de vérification
Attendre l'approbation du checkpoint
Enregistrer le SHA du checkpoint
Procéder à la phase suivante

Compléter un track

Vérifier que toutes les phases sont complètes
Vérifier que tous les critères d'acceptation sont satisfaits
Mettre à jour product.md si nécessaire
Marquer le track complété dans tracks.md
Mettre à jour metadata.json

Revenir en arrière sur un track

Exécuter /conductor:revert
Sélectionner le track à revenir en arrière
Choisir la granularité (track/phase/task)
Confirmer l'opération de retour en arrière
Mettre à jour les marqueurs d'état

Gérer les dépendances de tracks

Identifier les dépendances

Lors de la création d'un track, identifier :

Dépendances strictes : Doit être complété avant que ce track puisse commencer
Dépendances faibles : Peut procéder en parallèle mais peut affecter l'intégration
Dépendances externes : Services tiers, APIs ou décisions d'équipe

Documenter les dépendances

Dans spec.md, lister les dépendances avec :

Type de dépendance (stricte/faible/externe)
État actuel (disponible/en attente/bloqué)
Chemin de résolution (ce qui doit se passer)

Gérer les tracks bloqués

Quand un track est bloqué :

Marquer les tâches bloquées avec [!] et raison
Mettre à jour le statut dans tracks.md
Documenter le blocage dans metadata.json
Considérer créer un track de dépendance si nécessaire

Directives de dimensionnement des tracks

Tracks de bonne taille

Viser des tracks qui :

Se complètent en 1-5 jours de travail
Ont 2-4 phases
Contiennent 8-20 tâches au total
Livrent une unité cohérente et testable

Trop grands

Signes qu'un track est trop grand :

Plus de 5 phases
Plus de 25 tâches
Plusieurs fonctionnalités non liées
Durée estimée > 1 semaine

Solution : Diviser en plusieurs tracks avec des limites claires.

Trop petits

Signes qu'un track est trop petit :

Phase unique avec 1-2 tâches
Aucune vérification significative requise
Pourrait être une sous-tâche d'un autre track
Moins que quelques heures de travail

Solution : Combiner avec un travail connexe ou gérer comme partie d'un track existant.

Liste de vérification de la qualité de la spécification

Avant de finaliser spec.md, vérifier :

Qualité des exigences

[ ] Chaque exigence a des critères d'acceptation clairs
[ ] Les exigences sont testables
[ ] Les exigences sont indépendantes (vérifiables séparément)
[ ] Pas de langage ambigu ("should be fast" → "response < 200ms")

Clarté de la portée

[ ] Les éléments in-scope sont spécifiques
[ ] Les éléments out-of-scope préviennent l'expansion de portée
[ ] Les limites sont claires pour l'implémentateur

Dépendances identifiées

[ ] Toutes les dépendances internes sont listées
[ ] Les dépendances externes ont des propriétaires/contacts
[ ] L'état de dépendance est actuel

Risques traités

[ ] Les risques majeurs sont identifiés
[ ] L'évaluation d'impact est réaliste
[ ] Les atténuations sont actionnables

Liste de vérification de la qualité du plan

Avant de commencer l'implémentation, vérifier plan.md :

Qualité des tâches

[ ] Les tâches sont atomiques (une action logique)
[ ] Les tâches sont indépendamment vérifiables
[ ] Les descriptions de tâches sont claires
[ ] Les sous-tâches fournissent des détails utiles

Organisation des phases

[ ] Les phases groupent les tâches connexes
[ ] Chaque phase livre quelque chose de testable
[ ] Tâches de vérification après chaque phase
[ ] Les phases se construisent logiquement l'une sur l'autre

Complétude

[ ] Toutes les exigences de spec ont des tâches correspondantes
[ ] Les tâches de documentation sont incluses
[ ] Les tâches de test sont incluses
[ ] Les tâches d'intégration sont incluses

Patterns de tracks courants

Pattern de track de fonctionnalité

Phase 1: Foundation
- Data models
- Database migrations
- Basic API structure

Phase 2: Core Logic
- Business logic implementation
- Input validation
- Error handling

Phase 3: Integration
- UI integration
- API documentation
- End-to-end tests

Pattern de track de correctif de bug

Phase 1: Reproduction
- Write failing test capturing bug
- Document reproduction steps

Phase 2: Fix
- Implement fix
- Verify test passes
- Check for regressions

Phase 3: Verification
- Manual verification
- Update documentation if needed

Pattern de track de refactorisation

Phase 1: Preparation
- Add characterization tests
- Document current behavior

Phase 2: Refactoring
- Apply changes incrementally
- Maintain green tests throughout

Phase 3: Cleanup
- Remove dead code
- Update documentation

Bonnes pratiques

Un track, une préoccupation : Garder les tracks focalisés sur un seul changement logique
Petites phases : Décomposer le travail en phases de 3-5 tâches maximum
Vérification après les phases : Toujours inclure les tâches de vérification
Mettre à jour les marqueurs immédiatement : Marquer le statut de tâche pendant que vous travaillez
Enregistrer les SHAs : Toujours noter les SHAs de commit pour les tâches complétées
Réviser les specs avant la planification : S'assurer que la spec est complète avant de créer le plan
Lier les dépendances : Noter explicitement les dépendances de tracks
Archiver, ne pas supprimer : Préserver les tracks complétés pour référence
Dimensionner appropriément : Garder les tracks entre 1-5 jours de travail
Critères d'acceptation clairs : Chaque exigence doit être testable