Optimization: Ce skill utilise du chargement à la demande. Les contenus lourds vivent dans references/ et sont lus à la demande.

Language rule: Les instructions du skill sont en français (le catalogue lui-même). Pour les artefacts générés (rapports, benches, scripts), détecte la langue du projet (README, commentaires, docs, commits) et produis dans cette langue. Si le projet est bilingue, demande à l'utilisateur.

Gotchas: Lis ../gotchas.md AVANT de produire un livrable.

Perf Optimization

Catalogue ordonné des techniques d'optimisation, du plus rentable au moins rentable. L'objectif : donner le bon réflexe au bon niveau, et empêcher de micro-optimiser avant d'avoir réglé l'algo et l'I/O.

Règle d'or : MESURE avant d'optimiser

"Premature optimization is the root of all evil." — Knuth

On n'optimise jamais à l'intuition. 90 % du temps est passé dans 10 % du code (le hot path). Optimiser le reste = effort gaspillé + complexité ajoutée pour rien. Méthode en boucle :

1. Mesure — profile/trace pour trouver le vrai bottleneck (pas celui qu'on

imagine). Établis une baseline chiffrée. Ne suppose jamais quel langage/lib est plus rapide : instrumente. Méthodo détaillée : `references/profiling.md`.

1. Localise & classe — identifie LE point chaud ET sa nature : CPU-bound,

memory-bound, bandwidth-bound, I/O-bound, lock-bound ou syscall-bound ? Cette classification (roofline) dicte quel niveau de la hiérarchie attaquer. Loi d'Amdahl : accélérer ×10 un bloc qui pèse 5 % du temps total ne gagne que ~4,5 %. Inutile.

1. Optimise — applique la technique du bon niveau (voir hiérarchie ci-dessous).
2. Re-mesure — confirme le gain réel. Si nul ou négatif, reviens en arrière.

Garde le code lisible si le gain n'est pas significatif.

Reproductibilité — un bench n'a de valeur que s'il est rejouable à l'identique : seed, horloge, environnement, ordre, locale. Le toolkit canonique est partagé : ../shared/determinism.md. Sans ces pins, deux exécutions consécutives produisent des chiffres différents et l'A/B devient impossible à départager.

Le GATE — definition-of-done (ne pas sauter)

Trois portes obligatoires. Tant qu'une case n'est pas cochée, on ne passe pas. La structure 3-phases (pré → pendant → post) est canonique dans ../shared/done-gate.md — ce GATE en est la spécialisation perf (distribution + permutation + anti-DCE en post). Les autres forge-* skills (resilience, pipeline, oci-rootless, demo, chef) instancient le même squelette pour leur domaine.

Avant de toucher au code :

• [ ] baseline chiffrée et reproductible (même entrée, même environnement).
• [ ] bottleneck localisé ET classé (CPU/mem/bande passante/I/O/lock/syscall) —

sinon references/profiling.md.

• [ ] borne max du gain estimée (Amdahl/roofline). Si le plafond est faible

→ stop, change de cible.

Pendant :

• [ ] une seule variable à la fois (sinon tu ne sauras pas qui a causé quoi).

Avant de CLAIMER un gain :

• [ ] distribution rapportée (médiane + p95/p99), jamais une moyenne seule.
• [ ] Δ supérieur au bruit de mesure (test de permutation, cf. le harnais)

— sinon il n'y a pas de gain.

• [ ] aucun piège de mesure : le compilo n'a pas supprimé le bench, warmup

fait, runs A/B interleavés. Détail : references/benchmarking-traps.md.

• [ ] gain réel non significatif → revert et garde la lisibilité.

Position sur le gate-ladder partagé (../shared/gate-ladder.md) — le GATE de perf est un T1-T4 spécialisé : le bench in-process est T1 (composant), la baseline reproductible est T2 (environnement maîtrisé), l'A/B sous charge est T4 (stress). Une régression de perf observée en prod sans test T4 = "false green" — exactement le défaut que le ladder existe pour rattraper.

Harnais natif (langue-agnostique)

Le protocole (warmup, N échantillons, distribution + p95/p99 + σ, A/B interleavé, test de permutation, anti-DCE) s'implémente dans n'importe quel langage. L'actif réutilisable n'est pas un script — c'est la méthode de mesure et la règle de verdict. references/bench-protocol.md formalise ce protocole et route vers l'outil natif mûr selon le langage :

Préfère TOUJOURS un framework natif mûr à une boucle maison : ils gèrent warmup, outliers et stats bien mieux qu'un harnais ad-hoc. Pour le sub-ms et l'in-process, c'est obligatoire — l'overhead d'un sous-process domine la mesure.

Squelettes prêts à copier (Rust/Criterion, Rust std seul pour l'air-gap, Go/benchstat, C, hyperfine) + règle de routage détaillée : references/bench-protocol.md §Squelettes.

Modes opératoires courants (à implémenter dans le langage cible — patterns, pas scripts) :

• A/B avec significativité : interleaver A,B,A,B…, comparer médianes, test de permutation (ou Mann-Whitney). Δ dans le bruit ⇒ pas de gain prouvé.
• Ablation / autotune : bencher N variantes, classer par médiane, tester chacune vs la meilleure. « ≈ dans le bruit » des suivantes = égalité, pas victoire.
• Sweep paramétrique : balayer (threads, batch size, cache size…), sortir la courbe + l'optimum. L'optimum est rarement à un extrême — élargir si c'en est un.
• Chiffrage €/kWh/CO₂ d'une optim : modèle + garde-fous (latence ≠ énergie, carbone embarqué, effet rebond) dans references/cost-accounting.md.

Traces complètes (symptôme → fix → chiffres) : references/worked-examples.md.

Pourquoi pas de script générique fourni ? Le langage d'un runner est accessoire (il dort en attendant le sous-process), mais aucun langage n'est portable partout : Python n'existe pas dans un conteneur FROM scratch ni en embarqué ; un binaire Rust ne tourne pas sur la JVM. La portabilité réelle vient du protocole et de son implémentation native dans la cible — pas d'un script à packager.

Mode recherche : quand la réponse n'est pas dans le catalogue

Le catalogue ci-dessous couvre le connu. Pour le reste — un goulot inédit, un résultat contre-intuitif, un domaine non couvert — on bascule en mode recherche : générer des idées (divergent), puis les valider par l'expérience (convergent). Ne mélange pas les deux phases.

• Générer des idées d'optimisation qu'on ne connaît pas encore (premiers

principes, inversion, analogie/biomimétisme, suppression, relâchement de contrainte, "et si 10× ?"). Réf : `references/idea-generation.md`

• Valider par l'expérience : hypothèse falsifiable, table de mixage

(ablation, une variable à la fois), contrôle de l'aléa, mesure multidimensionnelle, pièges statistiques (mêmes stats ≠ mêmes données). Réf : `references/experiment-method.md` — et les pièges de mesure (coordinated omission, DCE, warmup, A/B confondu) : references/benchmarking-traps.md.

• Dissoudre les contraintes quand on est coincé : réécrire à n'importe quel

niveau (Rust/C/asm/hexa/FPGA/DSL), détourner d'autres domaines ou équipements (le WiFi détecte une présence…), inversion radicale du problème lui-même. Réf : `references/lateral-thinking.md`

Outils de mesure par domaine

Hiérarchie des gains (ordre de priorité STRICT)

Attaque toujours dans cet ordre. Les gains du haut se comptent en ordres de grandeur ; ceux du bas en pourcents. Le niveau 0 (diagnostic) décide où dans cette liste se trouve réellement ton bottleneck.

1. Diagnostic du bottleneck → profiling + tracing + roofline. Détermine la

nature du goulot (CPU/mémoire/bande passante/I/O/lock/syscall) AVANT de choisir une optim. Réf : `references/profiling.md`

1. Algorithme & complexité → O(n²) → O(n log n) → O(n) → O(1). Le levier

le plus puissant de tous. Réf : `references/algorithmic.md`

1. Accès aux données (I/O, DB, réseau) → ne pas faire l'aller-retour est

toujours plus rapide que le faire vite. Réf : `references/database.md`

1. Mémoire & cache → RAM > disque, cache locality, mémoïsation, éviter de

recalculer. Réf : `references/memory-cache.md`

1. Async & parallélisme → recouvrir l'attente I/O, paralléliser le CPU,

ne pas bloquer. Réf : `references/async-concurrency.md`

1. Micro-optimisations CPU (math/physique, branchless, SIMD) → en DERNIER,

uniquement sur le hot path confirmé. Réf : `references/math-physics.md`

1. Frontend / web → axe transverse, piloté par Lighthouse / Core Web

Vitals. Réf : `references/frontend-web.md`

Au-delà de la hiérarchie (axes transverses & domaines — voir l'index pour router) :

• Systèmes & limites physiques → hardware : roofline, trade-offs

proc/RAM/disque (recompute vs transfert, compression), syscalls, instructions hardware (AES-NI, SIMD, GPU), NUMA, footprint, conso. `references/systems-hardware.md`

• Dépendances & footprint → empilement de libs : justifier chaque dep,

mutualiser les redondantes, libs « à leur maximum », aplatir les couches. `references/dependencies.md`

• Inférence LLM (tok/s) → quantization, KV cache, continuous batching,

speculative decoding ; le decode est memory-bandwidth-bound. `references/llm-inference.md`

• Crypto (ops/s) → choix d'algo (Ed25519, ChaCha20, BLAKE3), accélération

hardware, batch verification — sans casser le constant-time. `references/crypto-throughput.md`

• Biomimétisme (à cadrer) → utile pour l'optim combinatoire dure et la

coordination décentralisée ; folklore pour le reste. `references/bio-inspired.md`

Latency numbers — le modèle mental qui explique tout

Pourquoi "RAM plutôt que disque" et "ne fais pas de requête dans une boucle" : les ordres de grandeur. Mémorise-les, ils dictent 80 % des décisions.

Conséquences directes : un appel réseau coûte ~10 000× un accès RAM. Donc : batch les requêtes, cache en mémoire, et ne mets jamais une I/O dans une boucle serrée. C'est la base de la priorité #2 et #3.

Index rapide : "j'ai ce problème" → "va lire ça"

Anti-patterns universels (vrais quel que soit le langage)

• Optimiser sans profiler → tu optimises le mauvais endroit.
• I/O dans une boucle (requête DB, appel HTTP, lecture fichier par item) →

batch ou pré-charge. Le plus fréquent et le plus coûteux.

• Recalculer la même chose dans une boucle (invariant de boucle, len()

recalculé, propriété recalculée) → sors-le de la boucle, mémoïse.

• Recherche linéaire dans une grande collection alors qu'un Set/Map/index

donne du O(1) ou O(log n).

• Tout charger en mémoire quand un stream / une pagination suffit (et

l'inverse : relire le disque à chaque fois au lieu de cacher).

• Sérialiser ce qui peut être parallèle, ou paralléliser ce qui est borné

par autre chose (réseau saturé, contention de lock).

• Allouer dans le hot path (alloc/free répétés, copies, conversions de

type) → réutilise des buffers, pré-alloue.

• Abstractions à coût caché : ORM lazy qui déclenche du N+1, `.map().filter()

.reduce()` qui crée 3 collections intermédiaires sur des données massives.

Règle finale

La lisibilité est une feature. N'échange jamais de la clarté contre un gain de perf non mesuré et non significatif. Le code le plus rapide est souvent celui qui fait moins de travail, pas celui qui fait le même travail "plus vite".

Sortie machine-lisible (cli-cycle)

Quand ce skill tourne sous cli-cycle, émet une enveloppe .claude/cli-forge-perf.json au format ../shared/result-schema.md :

• score : « perf budget compliance » (% de cas hot-path qui passent le GATE) si la cible a un budget ; sinon null.
• findings[] : un par hotspot non traité ou par claim de gain non significatif (tier: 3 si bottleneck en prod, 2 si dégradation détectée, 1 si micro-optim spéculative).
• strengths[] : sections du catalogue déjà appliquées correctement (mesure avant optim, distribution rapportée, etc.).
• handoffs[] : voir Dynamic Handoffs ci-dessous.

Sans cli-cycle, le rapport prose reste primaire ; l'enveloppe est optionnelle.

Upstream inputs — ce qu'on tire d'AUTRES skills avant de mesurer

Avant de profiler/bencher, vérifie si ces skills ont déjà produit du matériel à réutiliser.

Integration with other cli-* skills

Dynamic Handoffs

Règle : recommande, n'exécute pas sans demande explicite.

Reference files