management/WORKFLOW.md

WORKFLOW.md — Gates, Sizing, and Rituals

Read this when a task begins, not preemptively. AGENTS.md holds the always-on rules; this file holds the process.

Size Classes

Propose one at task start; the human confirms — individually, or batched at the next refinement session.

Class	Scope	Process
S	One file / one small change, no design decisions	Direct. AGENTS.md rules only. The one-line go-ahead before starting is the stop — waived only if PROJECT.md grants the size-S exception.
M	Few files, minor decisions, fits one session	Slice plan in chat, no file. STOP: plan approval before any code. Then implement; each slice reports evidence and status inline. Gate 5 is a short AAR note in chat, filed to the wiki only if it produced a real learning.
L	New feature, multiple files or sessions, real decisions	Full design doc in docs/design/ following Gates 1–5 below.

When in doubt between two classes, pick the larger.

Gate 0 — Project Initialization

Runs once per project, triggered by a missing PROJECT.md. Ask, never guess:

1. Response language? (e.g. de / en)
2. Size-S gate exception granted? (yes / no)
3. One-line project purpose?
4. Audience — who uses this besides the owner? (Drives which wiki areas become mandatory later; see docs/wiki/index.md.)

Write the answers to PROJECT.md (frontmatter per schema.yaml), run validate.py, and confirm the result with the human.

Gates 1–5 (size L)

Each gate is a section of the design doc. A gate ends with STOP: present the section, wait for explicit approval. Do not pre-fill later sections.

Gate 1 — Product

• Problem statement: what user problem, for whom.
• Verifiable acceptance criterion. A real number where one exists; otherwise a concretely checkable outcome. "Works" is not a criterion.
• Non-goals: what this deliberately does not do.
• Announcement paragraph (3–5 sentences): what it is, who it's for, why it's good. If you can't write it, the product isn't understood yet.
• UI involved? Plain-HTML mockups of the affected screens.

STOP.

Gate 2 — Architecture

• Read first: the actual codebase, relevant ADRs, relevant AARs. Past decisions and learnings are input, not trivia.
• How it fits the real system: endpoints, tables/schemas, query outlines, the end-to-end flow (Mermaid).
• Constraints: non-functional requirements, proportional to the project.
• Options & trade-offs where more than one viable way exists: pro/contra each, chosen option, and why. Feature-local decisions stay here.
• Lasting directional decisions discovered here become ADRs (one each), linked from the design doc.

STOP.

Gate 3 — Program Design

• File locations: exact paths, new and touched.
• Types and method signatures — no bodies.
• Call stack for the main flow(s).
• What the tests will assert.
• Boundaries: an explicit DO NOT CHANGE list.
• Shakiest calls: name the decisions you are least confident about.

STOP.

Gate 4 — Vertical Slices

• Slice 1 is the tracer bullet: a thin end-to-end path that runs (mocks and stubs allowed). Only then real logic, one testable slice at a time. Never build layer-by-layer horizontally.
• Every slice lists its tasks; every task names files, action, verify, done.
• Each slice ends with verification evidence, a status (DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED), and a STOP for human review before the next slice.
• A check owes proof that it can fail. A slice that introduces a gate, test or check shows it going red with a deliberate break, and quotes that run. A gate only ever seen green is a hypothesis, not a result — and a suite that only calls its own functions proves the functions, not the program, so break the wiring too. The proof has to come from where the check actually runs: a control that passes on a workstation says nothing about the environment it was wired into.
• A delivering artifact owes one real result. Where the artifact's output is the product — a dashboard, a report, a query — acceptance quotes one observation it actually returned, or states why it is legitimately empty. "It exists" is not delivery.

Gate 5 — Closeout

• AAR section in the design doc: planned / actual / why the difference / learnings.
• Harvest: learnings useful to future readers go to the wiki (FAQ, Stolpersteine) with source links. A missing or wrong framework rule becomes a framework issue or update — generalized first, per Harvesting to the Framework below.
• Good analyses produced along the way may be filed as wiki pages (with citations) instead of dying in chat history.
• Name what this work made false. Ask it explicitly — which existing statement, in which artifact, does this undertaking now contradict? — and record the answer in the closeout, including when it is "none". Appending is cheap and feels complete; revising an earlier claim costs attention, so it only happens when someone asks the question.
• Move the design doc to docs/design/done/. Run gen_status.py.

Debugging Path

For bugs and incidents, any size:

1. Reproduce first. No reproduction, no fix.
2. Hypothesize the root cause; verify the hypothesis with evidence before changing anything.
3. Route the failure before fixing (diagnostic failure routing):
   • Intent issue — we built toward the wrong goal → back to Gate 1.
   • Spec issue — the design/plan was wrong → fix the spec (Gate 2/3), then the code.
   • Code issue — plan right, code wrong → fix in place.
4. Fix, plus a test that would have caught it.
5. Incidents and major misdiagnoses get a standalone AAR in docs/aar/.

Session Handoff

• When a slice completes, or context quality degrades, write the current state into the design doc's Handoff block — done slices, open decisions, next step — then start a fresh session that resumes from the doc. The doc is the memory; the session is disposable.
• End every working session by answering: "Which choices did I make that I'm least confident about?" File the answer in the design doc.

The Run Ledger

A rule that leaves no trace cannot be checked by anyone — not a reviewer, not a script, not a later reader. Following it and ignoring it produce the same repository. Every rule therefore owes a trace, or it is decoration.

The trace of a run is one file in docs/ledger/, one per session, with a row per gate:

• gate — the gate number, or the slice for size M.
• commit — the commit that closed it. A commit, not a timestamp: a timestamp is written by the same hand as the claim, a commit is not.
• approval — who released the gate. Empty means the next gate began without a stop.
• status — one of DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
• note — one line, for a reader.

A second table records the ladder walk (AGENTS.md §1): what was searched, what was found, and an outcome that begins reused: or built:. The section is mandatory even when nothing new was built — a session that built nothing says so in a row, because an absent record and an ignored rule look identical.

scripts/judge.py reads the ledger against these rules and against git. scripts/judge.py --coverage reports which rules of this framework are observable at all; a rule at zero is either unobservable or inert, and both are worth knowing. That report is never a gate.

Judging a Run

Two judges, and they answer different questions.

The deterministic one is scripts/judge.py: gate order, gates owed by the declared size class, approvals, the status vocabulary, and the cross-checks against git — that every named commit exists, is reachable, and that the commits run in the same order as the gates claim. That last group is the only part measured against evidence the ledger's author did not write.

The inferential one is a ritual, not a script, because no script can tell a real design document from a plausible one. It is invoked as a skill or slash command, and its one binding condition is where it runs:

⚠️ Fresh context, and without the work transcript. An agent that judges its own session justifies rather than checks. The judge receives AGENTS.md, WORKFLOW.md, the diff and the ledger — and nothing else. This is a condition, not an optimisation; run in the same context the output is worthless.

Its rubric, five questions, each answered with a quotation from the diff or the ledger rather than an impression:

1. Scope. Does every changed file trace to the stated undertaking? Name any that does not.
2. Substance. Is the design document load-bearing — do its non-goals exclude something a reader would otherwise expect, and are the shakiest calls real risks rather than modesty?
3. Size. Was the declared class plausible for what the diff turned out to be? A size that fits only in hindsight is the finding.
4. Evidence. Where a slice claims a result, is a run quoted? Where a check was added, was it shown going red?
5. Silence. Which rule should have produced a trace here and did not?

The output is a verdict artifact under docs/verdict/, and every finding is classified into one of two buckets: model failure — a clear rule was not followed — or framework gap — the rule is missing, unenforceable, or invisible. Keeping those apart is the whole point; a finding in the wrong bucket either blames a person for a missing rule or writes a behavioural lapse into the rule set. Binding rule: ADR-0010.

⚠️ The ledger is written by the agent it describes and can be wrong. The threat model is drift, not sabotage — see the ADR.

Refinement Session

A recurring, human-triggered ritual. Agenda:

1. Batched confirmations: size classes and small approvals queued since last time.
2. Backlog triage over docs/issues/: close, reprioritize, split.
3. AAR harvest: walk recent AARs; update the wiki (FAQ, Stolpersteine); propose framework changes — generalized per Harvesting to the Framework below.
4. Wiki lint (content-level, beyond validate.py): contradictions between pages, claims superseded by newer sources, orphan pages, missing cross-references, gaps worth a new page or a web search.
5. STATUS review: anything stale or surprising in STATUS.md.

Harvesting to the Framework

A harvest is the one artifact that leaves the project: findings travel from an adopting repo back into the framework so the next version can cover them. It crosses a trust boundary, and it is written by the people least likely to notice what is specific about their own project.

• What travels: the failure class, its effect, its cause, and the framework change it argues for.
• What never travels: names of the adopter, its products, domains or customers; hostnames, URLs and paths; stack components; people; commit hashes; the adopter's own issue and ticket identifiers. Refer to evidence by an identifier that resolves only in the private record, and use roles instead of names — "a steering repo for a multi-component group", never the group.
• Before it leaves: run scripts/check_harvest.py over the range being handed over. It reads file contents, file names and commit messages, and fails closed: a missing term list or an unresolvable range is an error, never a pass.
• The term list belongs to the adopter and is never committed to the framework — the framework must not store the names it exists to keep out. A term the framework itself uses is shared vocabulary, not a secret; listing it only produces noise that teaches people to skip the check.

⚠️ The check supplements review, it never replaces it: a denylist finds only the nouns somebody thought of, and it deliberately does not look at commit identity. Read the diff as well.

Binding rule: ADR-0008.

Knowledge Handling (summary)

Full rules live in docs/wiki/index.md. The short version:

• Original sources live in docs/sources/, immutable — agents read them, never modify them. Wiki pages cite the sources they draw on.
• Contradictions are resolved or explicitly flagged — never left silently coexisting.
• If the wiki has no confident answer, say so. Never file a low-confidence synthesis back as knowledge.
• Git is the changelog. No separate log file.