Put SAW into practice

Step 1

Prepare your starting point

Start with a concrete need. A SAW project can cover an entire application, a feature or another identifiable scope.

Get the executable specification and provide it to the LLM before requesting document preparation. The Markdown version distributed with SAW is named SAW-3.2-SPECIFICATION-EXEC.md; the downloadable text version contains the same Markdown and can be saved under that name.

1. Choose a folder accessible to the people and LLM involved.
2. Gather specifications, mockups and known constraints. Identify unanswered questions.
3. Identify the person who decides and accepts the result. No particular account or signature system is required.
4. Use your usual tools. SAW relies on Markdown files without imposing Git, an IDE or an LLM provider.

Step 2

Describe the product and its constraints

PROJECT.md describes the product and why it exists. RULES.md contains active constraints.

1. Write down the problem, users, scope and exclusions.
2. Describe stable functional characteristics and useful terms.
3. State actual constraints: platform, architecture, storage, security, tests and conventions. Do not invent a constraint to fill a template.
4. Review the LLM’s proposals and correct them before using them as the project’s frame.

Initial rules do not require a ledger decision. After initialization, adding or changing them requires a recorded human decision with its scope and consequences.

Using my specifications, prepare PROJECT.md and the initial RULES.md rules according to SAW 3.2. Separate product scope from technical constraints. Identify assumptions and questions requiring my decision. Do not start implementation.

Step 3

Set up the documentary frame

Copy the SAW 3.2 executable specification to the documentary root in your chosen language. README must identify its file, version and revision, with a direct link.

Create the six required global files. Normative names remain in English. HISTORY.md is mandatory in this executable version, even for a small project.

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  ← prepared for closure

README is the universal entry point. STATUS is authoritative for current state. LEDGER records durable decisions; HISTORY records significant operations. A conversation alone does not preserve essential rules.

Read the supplied SAW 3.2 executable specification. Prepare the six required global documents and reading protocol using the approved product frame. Preserve existing files and report inconsistencies. Directly reference the local method copy, version and revision in README.md. Do not invent human decisions or validations, and do not start any lot.

Step 4 · Optional LLM assistance

Break the work into lots

A lot has a coherent objective, an identifiable result and validation conditions. Its identifier, such as LOT-001, is unique and must never be reused.

1. List successive outcomes that move the product forward.
2. Define each lot’s objective, scope, exclusions and dependencies.
3. Check that each result can be evaluated clearly.
4. Improve the breakdown before preparing recognized lots. You do not need to invent every detail immediately.

Here are the product specifications and SAW 3.2 method. Propose a complete lot breakdown: objectives, scope, dependencies and proposed validations. If several projects would help, propose their grouping in an Application. You may prepare draft files; identify assumptions and wait for my review before treating the breakdown as an approved baseline. Do not start any lot.

Step 5

Prepare the first lot

Create SPEC-001.md, FINDINGS-001.md and GATES-001.md. Every lot file starts with a reference to the root README.

1. In SPEC, describe the objective and identified requirements, such as REQ-001-001. Add important cases and dependencies.
2. Prepare FINDINGS for knowledge gained during work; do not invent discoveries.
3. Define gates and their success conditions before Planned. For AUTO, also define the deterministic evaluation method.
4. Once the identifier is assigned, spec sufficiently defined and gates defined, register the lot as Planned in STATUS and the significant operation in HISTORY.

Until then, the files remain a Draft. The lot does not yet occupy the active slot.

Business validation is HUMAN unless a human decision demonstrates no business impact. Verdicts: TO TEST, PASS, FAIL and N/A. N/A requires a human ledger decision with reason and non-applicability conditions.

Prepare LOT-001 from the approved breakdown: SPEC, FINDINGS and GATES. Define requirements, important cases and validation conditions before proposing Planned. Keep gates at TO TEST. Ask for missing decisions or information; do not start the lot.

Step 6

Authorize the start and implement the lot

The human decides when to start. The LLM checks dependencies and the active slot. If choosing between eligible lots is ambiguous, it asks for a decision.

Read before any work on a lot

README → PROJECT → RULES → active LEDGER decisions
→ explicitly referenced obsolete decisions → STATUS
→ SPEC → FINDINGS → GATES → CONVERGENCE if present

Consult HISTORY when chronology helps resumption or reconciliation. Resolve inconsistencies affecting intent, validations or state before working.

1. After authorization and checks, move to In-progress.
2. Implement active requirements and record new knowledge in FINDINGS.
3. Keep resumption information current: available result, remaining work, blockers and next action.
4. Record significant documentary operations in HISTORY.

Only one lot among In-progress, Blocked and Ready-to-close occupies a project’s slot. After starting, a change in requirement or gate meaning requires a human ledger decision and preservation of replaced content.

Read README.md and follow the mandatory bootstrap. I authorize you to start LOT-001 if dependencies are satisfied and the slot is available. Implement active requirements and maintain documents and resumption information. Request human-only decisions required by SAW; do not start another lot or close this one without my acceptance.

Step 7

Evaluate gates on the result

Identify the evaluated result: named delivery, document version, preserved copy or version-control revision. A path to changing content alone does not distinguish two results. Git is not required.

1. AUTO: retain timestamp, evaluated result, verdict, check result and evidence.
2. LLM: retain timestamp, evaluated result, evaluator and concise rationale; identify the model when available.
3. HUMAN: have the person actually examine the result. PASS requires their name and timestamp; the LLM cannot grant it.
4. After failure, correct and evaluate again. Before every new evaluation or reset, preserve the previous verdict and details in Test history.

Evaluate LOT-001 AUTO and LLM gates on an identified result. Preserve prior evaluations and document evidence and rationale. Present HUMAN checks to me without assigning them PASS. Report failures and invalidated validations.

Step 8

Prepare, accept and close the lot

Closure compares intent with the actual result. Passing tests alone is insufficient.

1. Check active gate validity and N/A conditions. Refuse closure if any gate remains FAIL or TO TEST.
2. Review each active requirement: satisfaction or a precise difference requiring acceptance. Check relevant replacements and obsolete items.
3. Resolve each finding: explained local resolution, promotion, deferral to a lot that is at least Planned, or reasoned rejection. No OPEN finding may remain at closure.
4. Prepare CONVERGENCE: identified result, differences, essential gates, findings disposition and residual work.
5. Obtain and record required human decisions, apply their consequences and review affected validations again.
6. Check that no reason for refusal remains and move to Ready-to-close if needed.
7. Present result and convergence to the human for explicit acceptance.
8. Finalize convergence and approved updates, check consistency, then record Closed in STATUS last among content and state documents. Record the operation in HISTORY afterward.

TOTAL means all active requirements are satisfied. PARTIAL means at least one difference has been accepted by a human ledger decision. An accepted difference never overrides FAIL or TO TEST. Ordinary total closure needs no ledger entry; human acceptance remains mandatory.

I request preparation of LOT-001 closure under SAW. Check gates, requirements, findings, decisions and documentary consistency. Prepare convergence and present the identified result, differences and necessary decisions. Wait for my acceptance before finalizing closure and moving STATUS to Closed.

Step 9

Resume without relying on the conversation

Before an interruption or handoff, prepare documents for resumption:

• Available result and location, or its absence.
• Known remaining work.
• Blockers and conditions for removal.
• Next action or decision needed.

STATUS provides a current summary or references: causes in FINDINGS, validations in GATES, intent in SPEC. A self-contained handoff includes the executable specification and bootstrap documents.

If a documentary operation was interrupted, compare files with the recorded decision. Complete missing writes if it clearly determines next steps without requesting documented acceptance again. If a necessary decision is absent or ambiguous, ask before dependent work. Preserve traces and record reconciliation in HISTORY.

Read README.md and reconstruct context through bootstrap. Compare STATUS and lot files, consult resumption information and HISTORY if useful. Report inconsistencies and reconcile interrupted writes under recorded decisions. Resume authorized work; request only necessary decisions still absent or ambiguous.

Step 10

Move to the next lot

After closure, repeat the cycle for the next planned lot. Check dependencies, update preparation using acquired knowledge and obtain authorization to start.

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

Lots decided from findings must be prepared and referenced. Scope evolution must not erase previous documents; retired identifiers are not reused.

Read README.md and propose the next Planned lot whose dependencies are satisfied. Explain any ambiguous choice and necessary preparation adjustments. Wait for my choice and authorization before starting.

When the route changes

Advanced use

Organize an Application with several projects

For a larger scope, an Application groups several SAW projects. It carries coordination and common rules above projects and does not own lots.

Using specifications and the method, you can ask an LLM to propose this organization, then have humans review responsibilities, dependencies and breakdown.

task-application/
  README.md  PROJECT.md  RULES.md  LEDGER.md  STATUS.md
  user-interface/  ← SAW project and its lots
  task-service/    ← SAW project and its lots
  integration/     ← SAW project for the cross-project result

1. Define Application scope and exhaustively list projects, their documentary roots and responsibilities.
2. Create its README, PROJECT, RULES, LEDGER and STATUS. Its README directly references the applicable executable method. Each project retains its six global files and local reference.
3. Each project requires reading the Application README followed by its local README. Its RULES requires applying global rules without copying them. Its SPEC files reference both READMEs.
4. Break each project into lots and define cross-project dependencies. Name projects in cross-project references: identifiers are unique locally.
5. For parallel progress, obtain a decision from an identified architectural authority in the Application LEDGER before execution.

Each project retains one active lot. Blocking a project does not automatically block others: examine dependencies. Application STATUS is a coordination view with a timestamp or update origin; each project’s STATUS remains authoritative for its lots.

Quick reference, prompts and templates

Cycle checklist

• Explicit product frame, rules and executable reference.
• Six global documents present, including HISTORY.
• SPEC, FINDINGS and GATES prepared; gates defined before Planned.
• Authorized start; only one lot in the active slot.
• Discoveries, decisions and resumption information preserved.
• Valid PASS or still-applicable human N/A decisions.
• Each requirement and finding reviewed and resolved.
• Identified result and presented differences accepted by the human.
• Convergence and updates finalized before Closed in STATUS.

Which information belongs in which file?

Templates to copy and adapt

Templates use English headings like normative files. Adapt content to your project and conventions. Replace angle-bracket placeholders with actual information and remove instructional notes. These examples do not constitute 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.>

Reference: Executable specification 3.2 · Full normative specification.

Frequently asked questions

Back to contents