Checklist OKF : vérifier qu'un bundle est prêt à être testé par un agent

À quoi sert cette checklist ?

Le piège d'un premier bundle OKF est de croire qu'il suffit d'avoir des fichiers Markdown. C'est un bon début, mais ce n'est pas encore un contexte exploitable. Un agent doit pouvoir comprendre où commencer, quels concepts sont fiables, quelles sources soutiennent les affirmations et quand il doit reconnaître ses limites.

Cette page propose une grille d'exécution en six niveaux: conformité minimale, navigation, qualité des concepts, preuves, test agent et maintenance. Le niveau attendu n'est pas la perfection. L'objectif est d'obtenir un bundle prêt à tester, pas un système autonome sans supervision humaine.

La bonne question n'est donc pas: est-ce que le bundle est terminé ? La bonne question est: est-ce qu'il est assez clair, sourcé et maintenable pour produire un test agent utile ?

Niveau 1 : vérifier la conformité minimale

Le premier niveau reprend la base de la spec OKF v0.1. Un concept file doit être un fichier Markdown, contenir un frontmatter YAML parseable et exposer un champ `type` présent et non vide.

Cette étape ne juge pas encore la qualité du contenu. Elle répond seulement à une question d'interopérabilité: un consommateur OKF peut-il ouvrir le fichier, lire ses métadonnées et comprendre la catégorie générale du concept ?

Il faut aussi éviter de traiter `index.md` ou `log.md` comme des concepts métier. Ces fichiers peuvent exister dans le bundle, mais ils ont un rôle particulier: navigation et historique.

Niveau 2 : rendre le bundle navigable

Un bundle conforme peut encore être difficile à utiliser. La navigation sert à éviter l'effet dossier partagé: des fichiers existent, mais personne ne sait par où commencer.

`index.md` doit donner une carte d'entrée simple: périmètre du bundle, concepts prioritaires, dossiers importants, limites connues et ordre de lecture conseillé. Les noms de fichiers doivent rester explicites, stables et proches du vocabulaire métier.

Les liens internes sont aussi un critère de navigation. Un agent doit pouvoir passer d'une métrique à sa table source, d'un playbook à une policy, ou d'une objection sales à une preuve client sans deviner la relation.

Niveau 3 : rendre les concepts utiles

Un concept utile répond à une question précise. Il ne doit pas être un simple copier-coller de wiki, ni un fourre-tout avec plusieurs sujets mélangés.

Le frontmatter aide l'agent à filtrer et router le concept. Le body Markdown aide l'humain à vérifier: définition, contexte, règles, exemples, limites, relations et éventuelles instructions d'usage.

Pour un concept `Metric`, cela peut vouloir dire formule, grain, exclusions et dashboard officiel. Pour un `Playbook`, cela peut vouloir dire déclencheur, étapes, actions autorisées, cas d'escalade et template de réponse.

Niveau 4 : relier et citer les sources

Les citations sont ce qui transforme un bundle de contexte en support de confiance. Sans source, un concept peut être propre mais invérifiable. Avec une source, un humain peut auditer et un agent peut expliquer d'où vient une affirmation.

Toutes les phrases n'ont pas besoin d'une citation. Les affirmations importantes, les règles métier, les chiffres, les décisions, les policies et les contraintes opérationnelles doivent en revanche pointer vers une source de vérité.

`resource` peut pointer vers une ressource principale: dashboard, API doc, table, page help center, ticket, décision, CRM ou document source. Les citations dans le body complètent ce lien quand plusieurs preuves sont nécessaires.

Niveau 5 : tester avec un agent réel

La revue humaine vérifie la clarté. Le test agent vérifie l'utilité. Un bundle OKF doit être confronté à des questions réelles: expliquer une métrique, répondre à un ticket, préparer un brief, comparer deux règles ou déclencher une action documentée.

Le test ne doit pas seulement chercher une bonne réponse. Il doit observer le comportement: l'agent cite-t-il les bonnes sources ? sait-il dire quand l'information manque ? navigue-t-il entre concepts ? confond-il une policy et un exemple ? invente-t-il des règles absentes du bundle ?

Les erreurs du test deviennent le backlog de correction du bundle. C'est souvent là que l'on découvre les concepts manquants, les liens faibles, les définitions trop floues et les sources insuffisantes.

Niveau 6 : organiser la maintenance

Un bundle OKF prêt à tester n'est pas un livrable figé. Sa valeur dépend de sa capacité à suivre les changements: nouvelle policy, nouvelle métrique, décision de pricing, mise à jour d'API, suppression d'un playbook ou correction d'une source.

`log.md` permet de garder une trace des changements importants. Il n'a pas besoin d'être complexe: date, changement, raison, owner et concepts impactés suffisent souvent pour une V1.

La maintenance doit aussi définir un rythme de revue. Les concepts critiques pour les réponses client, la data, le légal, le pricing ou les actions agents doivent avoir un owner et un critère de fraîcheur.

Exemple concret : checklist d'un bundle support

Imaginons un bundle support sur les demandes de remboursement. La V1 contient `index.md`, `log.md`, `policies/refund-policy.md`, `playbooks/refund-request.md`, `faqs/refund-exceptions.md`, `apis/create-ticket.md`, `templates/refund-response.md` et `sources/help-center-refunds.md`.

La conformité minimale vérifie que chaque fichier concept possède un `type`. La navigation vérifie que `index.md` indique par où commencer. La qualité vérifie que le playbook distingue les demandes éligibles, non éligibles et ambiguës.

Le test agent peut être très simple: donner trois tickets réels ou anonymisés et demander à l'agent de répondre, citer la règle, créer un ticket si nécessaire et escalader les cas ambigus. Si l'agent sur-promet ou cite mal, le bundle n'est pas encore prêt.

Score de maturité : bronze, argent, or

Pour éviter un débat abstrait sur la qualité, vous pouvez classer un bundle en trois niveaux. Bronze signifie conforme et lisible. Argent signifie navigable, sourcé et testé sur quelques cas. Or signifie maintenu, revu et intégré à un workflow réel.

Un premier bundle n'a pas besoin d'être Or. Pour une V1, viser Bronze plus quelques critères Argent est souvent le meilleur compromis: assez solide pour apprendre, pas assez lourd pour bloquer l'équipe.

Le passage à Or devrait venir après des usages répétés: support, data, sales, marketing ou ops. C'est le terrain qui indique quelles parties du bundle méritent davantage de gouvernance.

Erreurs fréquentes à éviter

La première erreur consiste à confondre checklist et bureaucratie. Si la checklist empêche de tester rapidement, elle est trop lourde. Elle doit réduire le risque, pas transformer OKF en comité de validation infini.

La deuxième erreur consiste à valider uniquement la syntaxe. Un bundle peut être conforme et inutile s'il ne contient pas les bonnes sources, s'il ne répond à aucune question métier ou s'il ne dit pas quand l'agent doit s'arrêter.

La troisième erreur consiste à oublier la maintenance. Le test initial est important, mais le vrai risque arrive plus tard: policy changée, métrique corrigée, décision obsolète, owner parti, source déplacée. Sans log et revue humaine, le contexte dérive.

Lire ensuite

Après cette checklist, vous pouvez revenir aux règles de conformité, reprendre le workflow complet ou passer aux prochaines étapes pour transformer un bundle testable en plan d'action.

Sources officielles et lectures utiles