Progressive Disclosure

Le framework utilise un système de chargement progressif inspiré de Claude Skills pour optimiser l'utilisation du contexte.

Le problème

Les AI coding agents ont une fenêtre de contexte limitée. Charger toute la documentation d'un coup :

• Sature le contexte inutilement
• Dégrade la qualité des réponses
• Gaspille des tokens

La solution : 3 niveaux

Niveau 1 — Découverte

---
name: kensho
description: |
  Pipeline principal Kensho — méthodologie APEX (Analyze, Spec, Plan, Execute, Validate, eXamine).
  Utilise analyst → architect → executor → code-reviewer.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

L'IA lit le frontmatter YAML et sait :

• Quand utiliser ce skill (description)
• Quels outils sont autorisés
• Comment l'invoquer (nom)

Coût : ~50 tokens par skill

Avec 19 skills, le niveau 1 consomme ~950 tokens — négligeable.

Niveau 2 — Activation

Quand l'utilisateur invoque /kensho, l'IA charge le corps du SKILL.md :

• Instructions étape par étape
• Flags disponibles
• Commandes rapides
• Pipeline de steps

Coût : ~500-2000 tokens par skill activé

Seul le skill invoqué est chargé.

Niveau 3 — Détails

Si un step nécessite plus de contexte, l'IA charge :

• REFERENCE.md — détails supplémentaires, edge cases, exemples
• steps/ — fichiers individuels par étape, nommés step-{NN}-{name}.md, contenant des sections XML chargées à la demande
• resources/ — assets, templates, données

Coût : variable, chargé à la demande

Seules les ressources nécessaires sont lues.

Comparaison

Approche traditionnelle :
┌────────────────────────────────────┐
│  TOUT le contexte chargé d'un coup │  ← 50K+ tokens
└────────────────────────────────────┘

Progressive Disclosure :
┌──────────┐
│ Niveau 1 │ ← ~950 tokens (tous les skills)
├──────────┤
│ Niveau 2 │ ← ~1500 tokens (skill actif)
├──────────┤
│ Niveau 3 │ ← variable (à la demande)
└──────────┘

Structure type d'un skill

skills/
└── kensho/
    ├── SKILL.md                  ← Niveaux 1 + 2
    ├── REFERENCE.md              ← Niveau 3
    ├── steps/
    │   ├── step-00-init.md       ← Niveau 3 (step 0)
    │   ├── step-01-analyze.md
    │   ├── step-01b-spec.md
    │   ├── step-02-plan.md
    │   ├── step-03-execute.md
    │   ├── step-04-validate.md
    │   ├── step-05-examine.md
    │   ├── step-06-resolve.md
    │   ├── step-07-tests.md
    │   ├── step-08-run-tests.md
    │   └── step-09-finish.md
    └── resources/
        └── examples.md           ← Niveau 3 (optionnel)

Anatomie d'un fichier step

Chaque fichier step suit une structure XML standardisée :

Sections disponibles

Section	Requis	Rôle
<objective>	oui	Ce que le step accomplit
<delegation>	si agent	Agent à qui déléguer, modèle, mode
<process>	oui	Liste numérotée des actions à effectuer
<rules>	non	Contraintes spécifiques au step
<output_template>	non	Template exact de l'output attendu
<save>	non	Chemin de sauvegarde si flag -s actif
<next>	oui	Step suivant (peut être conditionnel)

Exemple (step-01-analyze.md)

# Step 01 — Analyze

<objective>
Explorer le codebase pour comprendre la structure, les patterns
existants et les fichiers impactés par la tâche.
</objective>

<delegation>
agent: architect
tier: opus
mode: mandatory
exception: economy mode (`-e`) → work inline, no subagents
</delegation>

<process>
1. Lire le contexte dans 00-context.md
2. Explorer les fichiers pertinents
3. Identifier les patterns existants
4. Documenter les dépendances
</process>

<rules>
- Lecture seule — aucune modification de fichier
- Ne proposer aucune solution à ce stade
</rules>

<output_template>
## Analysis Report
...
</output_template>

<save>docs/kensho/{task-id}/01-analyze.md</save>

<next>step-01b-spec</next>