Mettre SAW en pratique

Étape 1

Préparer votre point de départ

Partez d’un besoin concret. Un projet SAW peut couvrir une application entière, une fonctionnalité ou un autre périmètre identifiable.

Récupérez la spécification exécutable et fournissez-la au LLM avant de lui demander de préparer les documents. La version Markdown distribuée avec SAW porte le nom SAW-3.2-SPECIFICATION-EXEC.md ; la version texte téléchargeable contient le même Markdown et peut être enregistrée sous ce nom.

1. Choisissez un dossier accessible aux personnes et au LLM qui interviendront.
2. Rassemblez vos spécifications, maquettes et contraintes connues. Signalez les questions ouvertes.
3. Identifiez la personne qui décide et accepte le résultat. Aucun compte ni système de signature particulier n’est imposé.
4. Choisissez vos outils habituels. SAW repose sur des fichiers Markdown sans imposer Git, un IDE ou un fournisseur de LLM.

Étape 2

Décrire le produit et ses contraintes

PROJECT.md décrit le produit et sa raison d’être. RULES.md contient les contraintes actives.

1. Écrivez le problème, les utilisateurs, le périmètre et le hors périmètre.
2. Décrivez les caractéristiques fonctionnelles stables et les termes utiles.
3. Précisez les contraintes réelles : plateforme, architecture, stockage, sécurité, tests et conventions. N’inventez pas une contrainte pour remplir un modèle.
4. Relisez les propositions du LLM et corrigez-les avant de les utiliser comme cadre du projet.

Les règles initiales n’exigent pas de décision au ledger. Après initialisation, leur ajout ou leur modification demande une décision humaine consignée, avec sa portée et ses conséquences.

À partir de mes spécifications, prépare PROJECT.md et les règles initiales de RULES.md selon SAW 3.2. Sépare le périmètre du produit des contraintes techniques. Signale tes hypothèses et les questions nécessitant ma décision. Ne commence pas la réalisation.

Étape 3

Installer le cadre documentaire

Copiez à la racine documentaire la spécification exécutable de SAW 3.2, dans la langue choisie. Le README doit identifier son fichier, sa version et sa révision, avec un lien direct.

Créez les six fichiers globaux requis. Les noms normatifs restent en anglais. HISTORY.md est obligatoire dans cette version exécutable, même pour un petit projet.

my-project/
  SAW-3.2-SPECIFICATION-EXEC.md
  README.md
  PROJECT.md
  RULES.md
  STATUS.md
  LEDGER.md
  HISTORY.md
  Specs/
    001-create-list/
      SPEC-001.md
      FINDINGS-001.md
      GATES-001.md
      CONVERGENCE-001.md  ← préparé à la fermeture

README est le point d’entrée universel. STATUS fait autorité sur l’état courant. LEDGER conserve les décisions durables ; HISTORY retrace les opérations significatives. Une conversation seule ne conserve pas les règles indispensables.

Lis la spécification exécutable SAW 3.2 fournie. Prépare les six documents globaux requis et le protocole de lecture, à partir du cadre produit approuvé. Préserve les fichiers existants et signale les incohérences. Référence directement la copie locale de la méthode, sa version et sa révision dans README.md. N’invente aucune décision ou validation humaine et ne lance aucun lot.

Étape 4 · Assistance du LLM optionnelle

Découper le travail en lots

Un lot porte un objectif cohérent, un résultat identifiable et des conditions de validation. Son identifiant, par exemple LOT-001, est unique et ne sera jamais réutilisé.

1. Listez les résultats successifs qui feront progresser le produit.
2. Définissez l’objectif, le périmètre, les exclusions et les dépendances de chaque lot.
3. Vérifiez que chaque résultat pourra être évalué clairement.
4. Améliorez le découpage avant de préparer les lots reconnus. Tous les détails n’ont pas besoin d’être inventés immédiatement.

Voici les spécifications du produit et la méthode SAW 3.2. Propose un découpage complet en lots : objectifs, périmètres, dépendances et validations envisagées. Si plusieurs projets sont utiles, propose leur regroupement dans une Application. Tu peux préparer les fichiers en brouillon ; signale les hypothèses et attends ma revue avant de retenir le découpage comme base approuvée. Ne démarre aucun lot.

Étape 5

Préparer le premier lot

Créez SPEC-001.md, FINDINGS-001.md et GATES-001.md. Chaque fichier de lot commence par un renvoi au README racine.

1. Dans SPEC, décrivez objectif et exigences identifiées, par exemple REQ-001-001. Ajoutez cas importants et dépendances.
2. Préparez FINDINGS pour les connaissances qui apparaîtront ; n’inventez aucune découverte.
3. Définissez les gates et leur condition de réussite avant Planned. Pour AUTO, définissez aussi la méthode déterministe de contrôle.
4. Avec un identifiant attribué, une spec suffisamment définie et des gates définies, inscrivez le lot Planned dans STATUS et l’opération significative dans HISTORY.

Avant cela, les fichiers restent un brouillon Draft. Le lot n’occupe pas encore le créneau actif.

Une validation métier est HUMAN, sauf décision humaine démontrant l’absence d’impact métier. Verdicts : TO TEST, PASS, FAIL et N/A. N/A exige une décision humaine au ledger, avec raison et conditions de non-applicabilité.

Prépare LOT-001 selon le découpage approuvé : SPEC, FINDINGS et GATES. Définis exigences, cas importants et conditions de validation avant de proposer Planned. Garde les gates à TO TEST. Fais préciser les décisions ou informations manquantes ; ne démarre pas le lot.

Étape 6

Autoriser le démarrage et réaliser le lot

L’humain décide le démarrage. Le LLM vérifie les dépendances et le créneau actif. Si le choix entre plusieurs lots possibles est ambigu, il le fait trancher.

Lire avant toute intervention sur un lot

README → PROJECT → RULES → décisions actives de LEDGER
→ décisions obsolètes explicitement référencées → STATUS
→ SPEC → FINDINGS → GATES → CONVERGENCE si présente

Consultez HISTORY lorsque la chronologie aide la reprise ou la réconciliation. Résolvez les incohérences touchant l’intention, les validations ou l’état avant de travailler.

1. Après autorisation et vérifications, passez à In-progress.
2. Réalisez les exigences actives et consignez les nouvelles connaissances dans FINDINGS.
3. Tenez à jour les informations de reprise : résultat disponible, travail restant, blocages et prochaine action.
4. Consignez les opérations documentaires significatives dans HISTORY.

Un seul lot parmi In-progress, Blocked et Ready-to-close occupe le créneau d’un projet. Après démarrage, changer le sens d’une exigence ou d’une gate demande une décision humaine au ledger et la conservation du contenu remplacé.

Lis README.md et suis le bootstrap obligatoire. Je t’autorise à démarrer LOT-001 si les dépendances sont satisfaites et le créneau disponible. Réalise les exigences actives et tiens à jour les documents et informations de reprise. Demande les décisions humaines réservées par SAW ; ne démarre aucun autre lot et ne ferme pas celui-ci sans mon acceptation.

Étape 7

Évaluer les gates sur le résultat

Identifiez le résultat examiné : livraison nommée, version de document, copie conservée ou révision de gestionnaire de versions. Un chemin vers un contenu qui change ne suffit pas, seul, à distinguer deux résultats. Git n’est pas imposé.

1. AUTO : conservez date, résultat évalué, verdict, résultat du contrôle et preuves.
2. LLM : conservez date, résultat évalué, évaluateur et justification concise ; identifiez le modèle lorsqu’il est disponible.
3. HUMAN : faites réellement examiner le résultat par la personne. PASS exige son nom et un horodatage ; le LLM ne peut pas l’accorder.
4. Après un échec, corrigez et réévaluez. Avant toute nouvelle évaluation ou remise à zéro, préservez l’ancien verdict et ses détails dans Test history.

Évalue les gates AUTO et LLM de LOT-001 sur un résultat identifié. Préserve les évaluations précédentes et documente preuves et justifications. Présente-moi les contrôles HUMAN sans leur attribuer de PASS. Signale échecs et validations devenues invalides.

Étape 8

Préparer, accepter et fermer le lot

La fermeture compare l’intention et le résultat réel. Des tests réussis ne suffisent pas.

1. Vérifiez la validité des gates actives et les conditions des N/A. Refusez la fermeture si une gate reste FAIL ou TO TEST.
2. Examinez chaque exigence active : satisfaction ou écart précis à faire accepter. Vérifiez remplacements et obsolètes pertinents.
3. Traitez chaque finding : résolution locale expliquée, promotion, report dans un lot au moins Planned ou rejet motivé. Aucun OPEN ne doit rester à la fermeture.
4. Préparez CONVERGENCE : résultat identifié, écarts, gates essentielles, traitement des findings et travail résiduel.
5. Obtenez et consignez les décisions humaines requises, appliquez leurs conséquences et réexaminez les validations affectées.
6. Vérifiez l’absence de cause de refus et passez à Ready-to-close si nécessaire.
7. Présentez résultat et convergence à l’humain pour acceptation explicite.
8. Finalisez convergence et mises à jour approuvées, contrôlez leur cohérence, puis inscrivez Closed dans STATUS en dernier parmi les documents de contenu et d’état. Consignez ensuite l’opération dans HISTORY.

TOTAL signifie que toutes les exigences actives sont satisfaites. PARTIAL signifie qu’au moins un écart a été accepté par décision humaine au ledger. Un écart accepté ne neutralise jamais une gate FAIL ou TO TEST. Une fermeture totale ordinaire n’exige pas d’entrée au ledger ; l’acceptation humaine reste obligatoire.

Je te demande de préparer la fermeture de LOT-001 selon SAW. Vérifie gates, exigences, findings, décisions et cohérence documentaire. Prépare la convergence et présente le résultat identifié, les écarts et les décisions nécessaires. Attends mon acceptation avant de finaliser la fermeture et de passer STATUS à Closed.

Étape 9

Reprendre sans dépendre de la conversation

Avant une interruption ou une transmission, préparez les documents pour la reprise :

• Le résultat disponible et son emplacement, ou son absence.
• Le travail restant connu.
• Les blocages et leurs conditions de levée.
• La prochaine action ou décision attendue.

STATUS donne un résumé courant ou des références : causes dans FINDINGS, validations dans GATES, intention dans SPEC. Une transmission autonome inclut la spécification exécutable et les documents du bootstrap.

Si une opération documentaire a été interrompue, comparez les fichiers à la décision enregistrée. Achevez les écritures manquantes si elle règle clairement la suite, sans redemander une acceptation déjà documentée. Si une décision nécessaire manque ou reste ambiguë, demandez une clarification avant le travail dépendant. Préservez les traces et consignez la réconciliation dans HISTORY.

Lis README.md et reconstruis le contexte selon le bootstrap. Compare STATUS et les fichiers du lot, consulte les informations de reprise et HISTORY si utile. Signale les incohérences et réconcilie les écritures interrompues selon les décisions enregistrées. Reprends le travail autorisé ; demande seulement les décisions nécessaires encore absentes ou ambiguës.

Étape 10

Passer au lot suivant

Après fermeture, répétez le cycle pour le prochain lot planifié. Vérifiez ses dépendances, actualisez sa préparation avec les connaissances acquises et faites autoriser le démarrage.

Planned → In-progress → Ready-to-close → Closed

Les lots décidés depuis les findings doivent être préparés et référencés. Une évolution du périmètre ne doit pas effacer les documents précédents ; les identifiants retirés ne sont pas réutilisés.

Lis README.md et propose le prochain lot Planned dont les dépendances sont satisfaites. Explique tout choix ambigu et les ajustements de préparation nécessaires. Attends mon choix et mon autorisation avant le démarrage.

Quand le parcours change

Utilisation avancée

Organiser une Application avec plusieurs projets

Pour un ensemble plus important, une Application regroupe plusieurs projets SAW. Elle porte la coordination et les règles communes au-dessus des projets ; elle ne possède pas de lots.

À partir des spécifications et de la méthode, vous pouvez demander au LLM de proposer cette organisation, puis faire revoir responsabilités, dépendances et découpage par les humains.

task-application/
  README.md  PROJECT.md  RULES.md  LEDGER.md  STATUS.md
  user-interface/  ← projet SAW et ses lots
  task-service/    ← projet SAW et ses lots
  integration/     ← projet SAW pour le résultat transversal

1. Définissez le périmètre de l’Application et inventoriez exhaustivement les projets, leur racine documentaire et leurs responsabilités.
2. Créez son README, PROJECT, RULES, LEDGER et STATUS. Son README référence directement la méthode exécutable applicable. Chaque projet conserve ses six fichiers globaux et sa référence locale.
3. Chaque projet fait lire le README de l’Application puis son README local. Son RULES demande d’appliquer les règles globales sans les recopier. Ses SPEC renvoient aux deux README.
4. Découpez chaque projet en lots et définissez les dépendances entre projets. Nommez les projets dans les références interprojets : les identifiants sont uniques localement.
5. Pour avancer en parallèle, obtenez avant l’exécution une décision d’une autorité architecturale identifiée dans le LEDGER de l’Application.

Chaque projet garde un seul lot actif. Le blocage d’un projet ne bloque pas automatiquement les autres : examinez leurs dépendances. Le STATUS d’Application est une vue de coordination datée ou indiquant son origine ; le STATUS de chaque projet reste l’autorité pour ses lots.

Aide-mémoire, consignes et modèles

Checklist du cycle

• Cadre produit, règles et référence exécutable explicites.
• Six documents globaux présents, dont HISTORY.
• SPEC, FINDINGS et GATES préparés ; gates définies avant Planned.
• Démarrage autorisé ; un seul lot dans le créneau actif.
• Découvertes, décisions et informations de reprise conservées.
• PASS valables ou N/A humains encore applicables.
• Chaque exigence et chaque finding examinés et traités.
• Résultat identifié et écarts présentés acceptés par l’humain.
• Convergence et mises à jour finalisées avant Closed dans STATUS.

Quelle information va dans quel fichier ?

Modèles à copier et à adapter

Les modèles utilisent des titres anglais comme les fichiers normatifs. Adaptez leur contenu au projet et à ses conventions. Remplacez les champs entre chevrons par des informations réelles et retirez les indications pédagogiques. Ces exemples ne constituent pas une validation.

# S.A.W. project protocol
## Purpose of this file
Universal entry point for this project.
## Protocol reference
This project follows S.A.W. 3.2, revision 3.2.0-2026-09-27:
[local executable specification](SAW-3.2-SPECIFICATION-EXEC.md).
HISTORY.md is required and uses dated, append-only entries.
## Mandatory bootstrap
Read README, PROJECT, RULES, all active LEDGER decisions, explicitly
referenced obsolete decisions, STATUS, then SPEC, FINDINGS, GATES,
and CONVERGENCE if present, in that order.
Consult HISTORY when chronology helps resumption or reconciliation.
## Starting a lot
Check dependencies and the active slot. Obtain human authorization.
Resolve ambiguous choices with the human. Update STATUS and HISTORY.
## Working on a lot
Implement active requirements. Record knowledge in FINDINGS.
Keep resumption information current. Follow the executable specification.
## Validating a lot
Evaluate active gates on an identifiable result. Preserve previous evaluations.
Only a named human can grant HUMAN PASS, with a timestamp.
## Closing a lot
Follow the executable specification's closure procedure. Review every
requirement and finding, prepare convergence, obtain human acceptance,
finalize approved documents, then record Closed in STATUS last among
content/state documents. Record the operation in HISTORY afterward.
## Mutation rules
Preserve obsolete content and replacement references. Never reuse identifiers.
Meaning changes after starting require a human LEDGER decision.
Review affected validations after relevant changes.
## Human-only decisions
Significant product changes; rule evolution; meaning changes after starting;
HUMAN verdicts; N/A; accepted differences; lots created from findings;
closure; cancellation; replacement; abandonment; reopening; reactivation.

# Project
## Purpose
Provide a small task list for personal use.
## Problem
Users need to retain tasks and see which remain unfinished.
## Users and actors
One user; a human project owner accepting the result.
## Scope
Create, list and complete tasks; retain tasks between sessions.
## Out of scope
Accounts, sharing, cloud synchronization and notifications.
## Stable functional characteristics
A task has a title and a completion state.
## Glossary
Task: an item of work entered by the user.

## R-001 — Local storage
Status: ACTIVE
Source: Initial project rule
Rule: Keep task data on the user's device; do not send it to a server.
Replaces: None
Replaced by: None

## R-002 — Timestamp format
Status: ACTIVE
Source: Initial project rule
Rule: Use YYYY-MM-DDTHH:mm:ss±HH:mm for documentary timestamps.
Replaces: None
Replaced by: None

# Lot status
| Lot reference | Parent | Title | Status | Replaced by | Comment |
|---|---|---|---|---|---|
| LOT-001 | None | Create and list tasks | Planned | None | Spec and gates defined; awaiting human start. |

## Resumption — LOT-001
Available result: planning files in Specs/001-create-list/; no implementation.
Remaining work: implement and validate the lot.
Blockers: none known.
Next action: human authorizes starting LOT-001.

# Decision ledger

No durable decision has been recorded yet.

<!-- For a real approved decision, replace this comment with:
## D-001 — <Decision title>
Date: <actual timestamp>
Decided by: <human name>
Decision: <approved decision>
Reason: <reason>
Source: <finding identifier or None>
Related: <affected identifiers>
Consequences: <scope and required actions>
Do not record a proposed decision as approved.
-->

# Project history

<!-- After actual initialization, append a real entry:
## <actual timestamp> — Project initialized
Actor: <person or LLM performing the operation>
Operation: Created project documents and planned LOT-001.
Documents: README.md, PROJECT.md, RULES.md, STATUS.md, LEDGER.md,
HISTORY.md, Specs/001-create-list/
Outcome: Applied
Summary: LOT-001 awaits human start; no implementation has started.
Do not invent historical dates, actors or operations.
-->

# LOT-001 — Create and list tasks
> Before working on this lot, read the repository root README.md.
## Objective
Let a user create tasks and see the current list.
## Context
First lot of the personal task-list project.
## In scope
Title entry, task creation and current-session list display.
## Out of scope
Completion state and persistence, assigned to later planned lots.
## Requirements
### REQ-001-001 — Create a task
A non-empty title creates exactly one task visible in the current list.
### REQ-001-002 — Reject an empty title
An empty or whitespace-only title creates no task and shows a clear explanation.
## Important cases
Empty title; whitespace-only title; successive additions; initially empty list.
## Dependencies
None.
## Known constraints
Apply every active RULES.md rule.

# Findings — LOT-001
> Before working on this lot, read the repository root README.md.

No finding has been recorded yet.

<!-- For a real finding, replace this comment with:
## F-001-001 — <Finding title>
Status: OPEN
Found at: <actual timestamp>
Finding: <observed knowledge>
Destinations: <identified destination, e.g. Local>
Evidence: <evidence if useful>
Impact: <impact if useful>
Before closure, explain final treatment and assign a consistent terminal status.
-->

# Gates — LOT-001
> Before working on this lot, read the repository root README.md.

## G-001-001 — Creation and empty-title tests
Type: AUTO
Status: TO TEST
Defined at: <actual timestamp>
Condition: Automated tests for REQ-001-001 and REQ-001-002 pass.
Method: <exact test command and pass criterion, defined before Planned>

## G-001-002 — Requirement and rule consistency
Type: LLM
Status: TO TEST
Defined at: <actual timestamp>
Condition: Implementation satisfies REQ-001-001 and REQ-001-002
and applicable active rules without an unexplained discrepancy.

## G-001-003 — User journey acceptance
Type: HUMAN
Status: TO TEST
Defined at: <actual timestamp>
Condition: The human confirms that adding tasks, reading the list and
understanding the empty-title explanation meet the intended use.

<!-- Record actual evaluations with these type-specific fields:
AUTO: Tested at, Evaluated result, Result, Evidence.
LLM: Evaluated at, Evaluated result, Evaluator, Rationale (model if available).
HUMAN: Validated at, Validated by, Evaluated result, Comment.
Preserve previous verdicts and evaluation details in Test history
before every new evaluation or reset. Do not assume PASS.
-->

# Convergence — LOT-001
> Before working on this lot, read the repository root README.md.
Closed at: <complete after actual acceptance>
Closed by: <human accepting closure>
Decision: <required ledger decision, or None for ordinary total closure>
Convergence: <TOTAL or PARTIAL based on the actual result>
## Result obtained
<Identify the accepted result and relate it to results evaluated in GATES.>
## Differences from active requirements
<For every active requirement, state satisfaction or the precise accepted
difference and its human ledger decision. Do not assume satisfaction.>
## Essential gate results
<Summarize valid PASS verdicts and authorized, still-applicable N/A.>
## Findings disposition
<Explain final treatment of each finding and reference its destinations.>
## Residual work
<Reference decided/planned future lots or state that none remains.>
## Closure decision
<Record actual human acceptance of the identified result and differences.>
## Historical convergences
<Preserve previous convergences here when reopening under the method.>

Référence : Spécification exécutable 3.2 · Spécification normative complète.

Questions fréquentes

Retour au sommaire