docs: restructure the README's how-it-works into Roles, Artefacts, Process#133
Merged
Conversation
…ocess The Artefacts section gains the brief's state-document contract in lay terms (everything it says reads true right now; ambition is visibly marked and rewritten to shipped reality in the shipping change) and the three-record division (intent = why, brief = what is, spec = how). The Process section closes the loop the old text left open: shipping updates both the intent (fidelity verdict) and the brief (marking comes off), the refine/grill step is explicit in the flow diagram with the not-yet-clear loop returning to it, and the capture hatch gets its own explanation with the triage routing. The reviewer's fail-honestly paragraph is retained. Assisted-by: Claude:claude-fable-5
Process gains two subsections (Capturing intents; Capturing issues & thoughts), the capture hatch gains the retention-vs-classification paragraph, and the header nav gains the Artefacts entry so all four top-level sections are linked. Verified: every nav anchor resolves to its heading slug, no reference to the removed how-abcd-works anchor exists anywhere, and both image assets resolve. Assisted-by: Claude:claude-fable-5
REPPL
enabled auto-merge
July 24, 2026 07:01
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructure the how-it-works section: Roles → Artefacts → Process
Replaces the
# How abcd workswrapper (Roles + Process) with four paralleltop-level sections — Roles, Artefacts, Process, Resources (the last already
existed) — and folds in the brief/intents mental model settled during the
brief-reconciliation work:
everything it says reads true right now; day-one ambition is visibly
marked and each marking comes off in the change that ships the capability.
The three-record division closes the item: the intent is the why, the
brief the what is, the spec the how.
the intent, marking off the brief); the refine/grill step is explicit in
the flow diagram, sitting after acceptance criteria with the
not-yet-clear loop returning into it; the capture hatch gets its own
explanation (one line, un-typed, facilitator triages later).
(delivered vs couldn't-tell is a distinction the framework insists on).
Prose-only; docs lint clean (0 blockers). No behaviour claims added beyond
what the shipped binary does (
abcd intent "<text>",abcd capture "<text>",ledger path, defaults — all verified this week during the currency work).