Skip to content

docs: restructure the README's how-it-works into Roles, Artefacts, Process#133

Merged
REPPL merged 2 commits into
mainfrom
docs/readme-roles-artefacts-process
Jul 24, 2026
Merged

docs: restructure the README's how-it-works into Roles, Artefacts, Process#133
REPPL merged 2 commits into
mainfrom
docs/readme-roles-artefacts-process

Conversation

@REPPL

@REPPL REPPL commented Jul 24, 2026

Copy link
Copy Markdown
Owner

Restructure the how-it-works section: Roles → Artefacts → Process

Replaces the # How abcd works wrapper (Roles + Process) with four parallel
top-level sections — Roles, Artefacts, Process, Resources (the last already
existed) — and folds in the brief/intents mental model settled during the
brief-reconciliation work:

  • Artefacts (new section): the brief's hard promise in lay terms —
    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.
  • Process: shipping now closes the loop twice (fidelity verdict onto
    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).
  • Retained from the old text: the reviewer's fail-honestly paragraph
    (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).

REPPL added 2 commits July 24, 2026 07:55
…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
REPPL enabled auto-merge July 24, 2026 07:01
@REPPL
REPPL merged commit 87cd9b3 into main Jul 24, 2026
12 checks passed
@REPPL
REPPL deleted the docs/readme-roles-artefacts-process branch July 24, 2026 07:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant