/crucible
Read first, ask last. The human answers only what the code can't.
Step 1: Read (no questions yet)
Write what the code already decides as facts with path:line. Every later question must be one these facts couldn't answer.
Step 2: The ladder (before proposing anything new)
For each piece of the requested change, stop at the first "yes":
- Can we skip or delete it? Is the requirement already met, or not needed? → say so.
- Is it already in the repo? An existing helper, component, or pattern → reuse it (cite
path:line). - Is it in the stdlib or an existing dependency? → use it.
- Only then: the minimal new code, with no speculative options or abstractions.
Step 3: Five axes
For each axis, mark it settled (cite the code or the request) or open:
- Scope: what's in, and explicitly what's out.
- Data and state invariants: what must always be true. Migrations?
- Failure modes: what happens on bad input, timeout, partial failure, retry.
- Security and trust boundaries: who can call this, with what data, and where validation lives.
- Verification proof: which check will prove it's done (feeds
/proof).
Step 4: Ask only what's open
- Is an axis open, and does the answer change the design? → ask. Max 3 questions per batch. Each gives your recommended answer and its trade-off, so the human can just say "yes".
- Is it open but low-stakes? → decide, and record it as
assumed. - Is everything settled? → don't ask anything. Go to step 5.
- Is a genuine architectural fork worth other models' views? →
/councilwith this record as the artifact.
Step 5: Record
Write .ramos/decisions/<topic>.md:
# <topic> (<date>)
## Facts (from code) - … (path:line)
## Ladder outcome - reuse X / stdlib Y / new Z (why)
## Axes | axis | settled/assumed/answered | decision | source |
## Out of scope - …
## Proof - exact command(s) /proof will run
Done when
Every axis is settled, assumed, or answered, the record exists, and the proof command is named. Unanswered design-changing questions → stop and report blocked on the human. Don't start coding.