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.

### 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.
- Good analyses produced along the way may be filed as wiki pages
  (with citations) instead of dying in chat history.
- 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.

## 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.
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`.

## 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.