Aller au contenu

ADR 0010 — Schéma frontmatter pour la métacognition gate-aware

Contexte

Le coach sdeg (coach-emergent.agent.md) est aujourd'hui monolithique : un seul prompt, une seule posture, identique quel que soit le grain (BE en pré-G1, FE en G3, US en G4). Or chaque porte est un domaine épistémique différent :

  • G1 = cadrage flou, peu de certitudes → posture hermeneutic / socratic
  • G2 / G3 = ingénierie planifiée, contraintes fortes → posture analytical / strategic
  • G4 = exécution, boucles courtes → posture executional / experimental
  • Re-G1 = retour d'expérience → posture hermeneutic / analytical

La trajectoire long terme (memo coach métacognitif) est de transformer le coach en dispatcher : à chaque transition, un préambule déterministe lit l'état SDLC + DDD stratégique + (in)certitudes du moment, puis assemble un contexte {skills autorisées, skills prohibées, posture cognitive} adapté au domaine de la porte. Le coach n'est alors plus un prompt mais une instance paramétrée.

Pour que cette couche métacognitive soit codable, chaque skill doit déclarer son domaine d'application dans son frontmatter — où elle est pertinente, quelle posture elle suppose, quelles autres skills elle exclut, quelles préconditions logiques elle exige.

Cette ADR fixe le schéma de ce frontmatter. Elle est préparatoire (le dispatcher n'est pas codé ici) — mais le schéma doit être stable avant qu'on backfille les 21 skills existantes.

Options envisagées

Sur la forme du schéma

  • A. Préfixe plat (sdeg_applies_at:, sdeg_posture:...) — facile à parser, pollution visible du frontmatter top-level.
  • B. Namespace YAML (sdeg: { applies_at: [...], posture: [...] }) — un seul bloc, isolation claire, transparent pour Copilot et Claude (qui ignorent les champs inconnus).
  • C. Fichier externe (<skill>.sdeg.yml à côté de <skill>.prompt.md) — pas de pollution mais double source de vérité, oubli garanti.

Sur la rigueur de prerequisites

  • i. Typé strict dès maintenant (JSON-Schema, validation au commit) — investissement fort sur un dispatcher pas encore écrit.
  • ii. Free-form string list maintenant, le dispatcher interprète librement — léger, le typage viendra quand on aura besoin.

Sur le timing du backfill

  • α. Progressif — chaque skill gagne le bloc sdeg: quand on la touche pour autre chose.
  • β. En bloc — backfill des 21 skills existantes immédiatement, cohérence garantie, base saine pour la suite.

Décision

Schéma B (namespace) + ii (free-form) + β (backfill en bloc).

Schéma

Chaque skill (Copilot .prompt.md ou Claude SKILL.md) gagne un bloc sdeg: dans son frontmatter, à côté des champs natifs (name, description, mode, tools, version) qui restent inchangés.

---
# Champs natifs (Copilot et/ou Claude) inchangés
name: prd-architect
description: "..."
mode: agent
tools: [editFiles, readFiles, codebase]
version: 1.0.0

# Bloc sdeg : transparent pour Copilot et Claude, consommé par le futur dispatcher
sdeg:
  applies_at: [g3]
  also_useful_at: [g4]
  posture: [analytical, executional]
  prohibits: [tdd-dev]
  prerequisites:
    - "fe.status in [PRD_EN_COURS, FAB_PLAN_EN_COURS]"
    - "artefact: spec.md"
  produces: [prd.md]
---

Sémantique des champs

champ type obligatoire utilité métacognitive
applies_at [gate] ✓ Portes où ce skill est pertinent en premier choix
also_useful_at [gate] — Portes secondaires (skills polyvalents)
posture [posture] ✓ Le dispatcher choisit une posture par porte ; les skills doivent matcher
prohibits [skill_name] — Skills incompatibles à activer simultanément (conflits cognitifs)
prerequisites [string] (free-form) — Le dispatcher peut filtrer si l'état SDLC ne satisfait pas
produces [artefact] — Trace skill → artefact (utile pour future observabilité / knowledge graph)

Vocabulaires contrôlés

Portes (applies_at, also_useful_at) :

  • pre-g1 — cadrage initial, vision floue, EO non encore transcrite
  • g1 — porte G1 (BE : VISION_EN_COURS → ENGAGE)
  • g2 — porte G2 (BE : DEV_PLAN_EN_COURS → DEV_PLAN_ARRETE)
  • g3 — porte G3 (FE : PRD_EN_COURS / FAB_PLAN_EN_COURS → FAB_PLAN_ARRETE)
  • g4 — porte G4 (US : DEV → LIVRE)
  • re-g1 — boucle retour (BE : PERSEVERE → VISION_EN_COURS)
  • cross — skill traversal sans porte privilégiée (ex. ubiquitous-language)

Postures cognitives (posture) :

  • hermeneutic — interprétation, sens-making, navigation dans le flou
  • analytical — décomposition logique, modélisation, structuration
  • experimental — fast & dirty, prototypage, apprentissage par l'essai
  • socratic — questionnement, pédagogie, accouchement
  • strategic — DDD strategic, cartographie haut niveau (Wardley, BC, options)
  • executional — mise en œuvre concrète, production d'artefacts livrables

Backfill

Les 21 skills .prompt.md existantes et les 3 SKILL.md du plugin sdeg-task-level/ sont backfillées dans le même commit que cette ADR. Le mapping skill → bloc sdeg: provient de l'inventaire de cartographie (cf. journal v6 et étape 1 du refactor feature/full-claude-code).

Conséquences

  • Positives
  • Le schéma est stable avant qu'on porte les skills en plugins Claude Code (un plugin par porte) — chaque port hérite naturellement du bloc sdeg:.
  • Copilot et Claude ignorent silencieusement le bloc sdeg: (champs inconnus dans frontmatter YAML) — pas de régression sur les usages actuels.
  • Le futur dispatcher métacognitif lit directement les frontmatter (pas de table d'enregistrement à maintenir séparément).

  • produces: ouvre la voie à un knowledge graph dérivé (cf. memo observabilité knowledge graph) sans coût aujourd'hui.

  • Négatives

  • Frontmatter alourdi (10–15 lignes supplémentaires par skill). Lisibilité OK tant que sdeg: reste un bloc isolé en bas.
  • prerequisites free-form = chaque skill peut écrire ses préconditions différemment ; on harmonisera quand le dispatcher tournera. Risque assumé.

  • Les skills générées en docs/skills/*.md ne rendent pas (encore) le bloc sdeg: — le générateur (tools/docs/gen-skills.js) n'extrait que description aujourd'hui. Ajouter le rendu plus tard, non bloquant.

  • Neutres

  • Le bloc sdeg: n'est consommé par aucun code au moment de cette ADR — il est une déclaration en attente d'usage. C'est volontaire : on documente le contrat avant de le coder.

Références

  • Branche feature/full-claude-code — refactor préparatoire qui consomme ce schéma.
  • ADR-0009 § D3 — premier port Claude Code (sdeg-task-level), trois skills à backfiller.
  • ADR-0004 — schema.js source de vérité pour les états ; le bloc sdeg.prerequisites peut référencer des statuts définis là-bas.
  • Memos coach métacognitif et observabilité knowledge graph (roadmap utilisateur).