# Skill — Workflow de Développement TabataGo
> Lis ce skill en début de session ou quand tu commences une nouvelle feature.

## Principe fondamental
**Plan d'abord, code ensuite.** Pour toute feature non triviale :
1. Analyse les specs dans le PRD (`docs/PRD.md`)
2. Liste les edge cases et les dépendances
3. Propose l'architecture (types, hooks, composants)
4. Attends validation avant de générer du code

Ne jamais écrire de code avant d'avoir une architecture approuvée
sur les features cœur (timer, audio, exercices).

---

## Cycle de développement par feature

### Étape 1 — Lire les specs
Avant toute implémentation, lis la section PRD correspondante.
Identifie exactement :
- Les entrées/sorties du système
- Les états possibles
- Les cas limites (interruptions, background, erreurs)

### Étape 2 — Typer en premier
Commence TOUJOURS par le fichier `types.ts` de la feature.
Les types sont le contrat — ils précèdent l'implémentation.

```typescript
// Exemple pour le timer — types.ts
export type TimerPhase = 'IDLE' | 'GET_READY' | 'WORK' | 'REST' | 'COMPLETE'

export interface TimerState {
  phase: TimerPhase
  secondsLeft: number
  currentRound: number
  totalRounds: number
  isRunning: boolean
}

export interface TimerConfig {
  workDuration: number      // secondes, défaut 20
  restDuration: number      // secondes, défaut 10
  rounds: number            // défaut 8
  getReadyDuration: number  // secondes, défaut 10
}

export interface TimerActions {
  start: () => void
  pause: () => void
  resume: () => void
  stop: () => void
  skip: () => void
}
```

**Ne passe à l'étape 3 que si les types semblent corrects.**

### Étape 3 — Implémenter le hook (logique métier)
Implémenter le hook central de la feature.
Règles :
- Aucun import depuis React Native UI dans les hooks métier
- Chaque hook expose un état + des actions (pattern Zustand-like)
- Les side effects sont dans useEffect avec cleanup systématique
- Logger les transitions d'état en dev (`__DEV__ && console.log(...)`)

### Étape 4 — Implémenter les composants
Les composants reçoivent tout par props — ils ne fetchent rien,
ne font aucune logique métier.

```typescript
// ✅ Correct
function TimerDisplay({ phase, secondsLeft, currentRound }: TimerDisplayProps) {
  return <Text>{secondsLeft}</Text>
}

// ❌ Interdit
function TimerDisplay() {
  const timer = useTimerEngine() // logique dans le composant
  return <Text>{timer.secondsLeft}</Text>
}
```

### Étape 5 — Tester avant de continuer
Avant de passer à la feature suivante, écrire les tests minimaux :
- État initial correct
- Transitions de phase correctes
- Cleanup des side effects (pas de memory leak)

---

## Patterns obligatoires

### Gestion d'état avec state machine explicite
Toujours utiliser une state machine pour les flows complexes.
Jamais de booléens en cascade (`isRunning && !isPaused && !isComplete`).

```typescript
// ✅ State machine explicite
type TimerPhase = 'IDLE' | 'GET_READY' | 'WORK' | 'REST' | 'COMPLETE'

const VALID_TRANSITIONS: Record<TimerPhase, TimerPhase[]> = {
  IDLE:      ['GET_READY'],
  GET_READY: ['WORK', 'IDLE'],
  WORK:      ['REST', 'IDLE'],
  REST:      ['WORK', 'COMPLETE', 'IDLE'],
  COMPLETE:  ['IDLE'],
}

function canTransition(from: TimerPhase, to: TimerPhase): boolean {
  return VALID_TRANSITIONS[from].includes(to)
}
```

### Cleanup systématique des useEffect
```typescript
useEffect(() => {
  const subscription = AppState.addEventListener('change', handleAppState)
  return () => subscription.remove() // TOUJOURS un cleanup
}, [])
```

### AsyncStorage — wrapper typé uniquement
Ne jamais appeler AsyncStorage directement dans les composants.
Passer par un hook ou un service :

```typescript
// shared/utils/storage.ts
export async function saveTimerConfig(config: TimerConfig): Promise<void> {
  await AsyncStorage.setItem('timer_config', JSON.stringify(config))
}

export async function loadTimerConfig(): Promise<TimerConfig | null> {
  const raw = await AsyncStorage.getItem('timer_config')
  return raw ? JSON.parse(raw) : null
}
```

### Constantes centralisées
```typescript
// shared/constants/timer.ts
export const TIMER_DEFAULTS = {
  WORK_DURATION: 20,
  REST_DURATION: 10,
  ROUNDS: 8,
  GET_READY_DURATION: 10,
} as const

// shared/constants/colors.ts
export const PHASE_COLORS = {
  GET_READY: '#EAB308',  // Jaune
  WORK:      '#F97316',  // Orange
  REST:      '#3B82F6',  // Bleu
  COMPLETE:  '#22C55E',  // Vert
  IDLE:      '#1E1E2E',  // Dark
} as const
```

---

## Gestion des erreurs

### Pattern try/catch dans les hooks async
```typescript
const [error, setError] = useState<string | null>(null)
const [isLoading, setIsLoading] = useState(false)

async function loadData() {
  try {
    setIsLoading(true)
    setError(null)
    const data = await fetchSomething()
    setData(data)
  } catch (e) {
    setError(e instanceof Error ? e.message : 'Erreur inconnue')
  } finally {
    setIsLoading(false)
  }
}
```

### Fallback dans les composants
Tout composant qui charge des ressources (GIF, audio) doit avoir
un état de fallback visible et non-bloquant.

---

## Checklist avant de soumettre du code

Avant de considérer une feature terminée, vérifier :

- [ ] Les types sont définis dans `types.ts`
- [ ] La logique est dans des hooks, pas dans des composants
- [ ] Tous les `useEffect` ont un cleanup
- [ ] Aucun `console.log` en dehors de `if (__DEV__)`
- [ ] Les constantes sont dans `shared/constants/`
- [ ] Les fonctions async ont un try/catch
- [ ] Un test minimal existe pour les cas principaux
- [ ] Le barrel export `index.ts` est mis à jour

---

## Workflow de debugging avec les logs Expo

Pour surveiller les logs en temps réel et donner du contexte à Claude :

```bash
# Terminal 1 — démarrer expo avec logs dans un fichier
npx expo start 2>&1 | tee .expo-logs/dev.log

# Ensuite dans Claude Code
> Surveille .expo-logs/dev.log et identifie les warnings
  liés au module [nom du module en cours]
```

Ajouter des logs structurés dans les hooks critiques :
```typescript
if (__DEV__) {
  console.log('[TimerEngine]', { phase, secondsLeft, currentRound })
}
```

---

## Commandes Claude Code utiles

| Situation | Commande |
|---|---|
| Début de projet / onboarding | `/init` |
| Session longue (>45 min) | `/compact` — focus sur la feature en cours |
| Avant chaque commit | `/review` |
| Quand Claude part en vrille | Donner un fichier précis : `@src/features/timer/hooks/useTimerEngine.ts` |
| Architecture à valider | Demander explicitement "ne génère pas de code, propose seulement l'architecture" |
