Thore CimbalandClaude Fable 5
e36ed337a7
Tracer bullet of the migration design (Gate 4, slice 1): pinned v0.1.1 baseline under docs/sources/upstream/ with provenance note, the Karpathy block moved verbatim to docs/sources/regelwerk/ (standing rule mapped onto the sources read-only mechanism), AGENTS.md assembled from the byte-true upstream sections plus the project section 6 (group rules condensed from the old CLAUDE.md), CLAUDE.md reduced to the upstream pointer, WORKFLOW.md and all four templates copied, schema.yaml extended (issue milestone/priority/status columns, component type, wiki area vision - all flagged in the header), validate.py and gen_status.py forked with marked extensions, pruefe_upstream_drift.py added, STATUS.md generated, CI gains the offline validate job, README directory link defused. Verified: validate 0 errors 0 warnings (the three pre-existing directory-link errors are gone), gen_status --check current, drift check 0 findings, baseline byte-identical to the reference checkout (10/10 files), four negative tests fire (WIP limit 3x in-progress, waiting without wartegrund, component slug mismatch, single-byte drift in WORKFLOW.md). gen_status needs Python >= 3.10 locally (write_text newline) - noted for the design AAR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
---
|
||
type: design
|
||
status: gate-1 # gate-1 | gate-2 | gate-3 | gate-4 | gate-5 | done
|
||
date: YYYY-MM-DD
|
||
size: L # this template is for size L
|
||
related: [] # issues, ADRs spawned or read
|
||
---
|
||
|
||
<!-- Copy to docs/design/YYYY-MM-DD-slug.md. Delete comments when filling in.
|
||
Fill ONE gate at a time; each gate ends with STOP — do not pre-fill
|
||
later gates. Advance `status` only after human approval. -->
|
||
|
||
# Design: Title
|
||
|
||
## Gate 1 — Product
|
||
|
||
**Problem.** <!-- What user problem, for whom. -->
|
||
|
||
**Acceptance criterion.** <!-- Verifiable. A real number where one
|
||
exists; otherwise a concretely checkable outcome. "Works" is not one. -->
|
||
|
||
**Non-goals.** <!-- What this deliberately does NOT do. The cheapest
|
||
scope-creep brake there is. -->
|
||
|
||
**Announcement.** <!-- 3–5 sentences: what it is, who it's for, why
|
||
it's good. Can't write it? The product isn't understood yet. -->
|
||
|
||
**Mockups.** <!-- Only if UI is involved: plain-HTML mockups, linked. -->
|
||
|
||
> **STOP — awaiting Gate 1 approval.**
|
||
|
||
## Gate 2 — Architecture
|
||
|
||
**Inputs read.** <!-- Which ADRs and AARs were read; one line each on
|
||
why they matter here. -->
|
||
|
||
**System fit.** <!-- Endpoints, tables/schemas, query outlines,
|
||
end-to-end flow as Mermaid. Against the actual codebase. -->
|
||
|
||
**Constraints.** <!-- Non-functional, proportional to the project:
|
||
performance, security, operations, compatibility. "None relevant"
|
||
is a valid answer — but say it. -->
|
||
|
||
**Options & trade-offs.** <!-- Where more than one viable way exists:
|
||
name the options, pro/contra each, state the chosen one and WHY.
|
||
This is the feature-local decision record. Only lasting, binding
|
||
decisions graduate to an ADR below. -->
|
||
|
||
**New ADRs.** <!-- Lasting decisions discovered here → one ADR each,
|
||
linked. None is a valid answer. -->
|
||
|
||
> **STOP — awaiting Gate 2 approval.**
|
||
|
||
## Gate 3 — Program Design
|
||
|
||
**Files.** <!-- Exact paths, new and touched. -->
|
||
|
||
**Signatures.** <!-- Types and method signatures, no bodies. -->
|
||
|
||
**Call stack.** <!-- For the main flow(s). -->
|
||
|
||
**Test assertions.** <!-- What the tests will assert. -->
|
||
|
||
**Boundaries — DO NOT CHANGE.** <!-- Explicit list. -->
|
||
|
||
**Shakiest calls.** <!-- The decisions you are least confident about. -->
|
||
|
||
> **STOP — awaiting Gate 3 approval.**
|
||
|
||
## Gate 4 — Vertical Slices
|
||
|
||
<!-- Slice 1 is the tracer bullet: thin end-to-end, runs with mocks.
|
||
Then real logic, one testable slice at a time. Per task:
|
||
files / action / verify / done. After each slice: evidence,
|
||
status, STOP. -->
|
||
|
||
### Slice 1 — Tracer bullet
|
||
- [ ] Task: … — files: … — action: … — verify: … — done: …
|
||
|
||
**Evidence:** <!-- command output, test run, screenshot ref -->
|
||
**Status:** <!-- DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED -->
|
||
|
||
> **STOP — slice review.**
|
||
|
||
### Slice 2 — …
|
||
|
||
### Handoff
|
||
|
||
<!-- The single place session state lives. Overwrite on every handoff;
|
||
git keeps the history.
|
||
Done slices: …
|
||
Open decisions: …
|
||
Next step: … -->
|
||
|
||
## Gate 5 — Closeout (AAR)
|
||
|
||
**Planned vs. actual.** <!-- What was planned, what happened. -->
|
||
|
||
**Why the difference.** <!-- Root causes, honestly. -->
|
||
|
||
**Learnings.** <!-- What future-you should know. -->
|
||
|
||
**Harvested.** <!-- Wiki pages updated (FAQ, Stolpersteine, …) with
|
||
links; framework issues opened, if a rule was missing or wrong. -->
|
||
|
||
**Open uncertainties.** <!-- Session-handoff answers to: "Which choices
|
||
did I make that I'm least confident about?" -->
|
||
|
||
<!-- After approval: set status: done, move this file to
|
||
docs/design/done/, run gen_status.py. -->
|