Cratis decision records
A decision is a durable choice with a decider and a date. It is
documentation, not a work record: it lives in the repository's decisions/
folder (or the folder .cratis/ai.json sets as process.decisions.path) and is reviewed like any other documentation. A handover may summarize a
decision; it never holds the only copy.
This skill owns the procedure — how to consult, author, accept, and supersede
a record. It does not decide what to decide, and it never grants acceptance. Do
not turn an implementation request, issue plan, or reversible technical choice
into an approval ceremony merely because this skill is available.
When you need this
- You are about to make a significant architectural, contract, scope, or
cross-cutting change. Consult existing records first: a decision you did not
read still binds the change. Consulting does not imply that a new record or
human approval is required.
- A human made a durable ruling — in review, in chat, or in a meeting — that
later work has to obey. Record it in the same turn, while the reasoning is
still available.
- An accepted decision no longer holds and has to be replaced, narrowed, or
qualified.
- Your change would contradict an accepted record. Stop: supersession or a human
verdict comes first, never a workaround.
When you do not
- Session notes, plans, handovers, status boards. Those are work records.
They belong in the repository's ignored local working directory, never in
decisions/.
- Product or API documentation. A record says what was chosen and why; the
documentation says how the thing works. Use the documentation workflow.
- A work item's status. "Blocked on X" is a work item field, not a decision.
- A reversible choice inside your own scope that nobody will re-litigate.
Make it and move on; see the significance test in step 3.
- An implementation request or an issue's proposed plan. A request to do the
work authorizes ordinary in-scope implementation; it is not automatically a
request to create or accept an architectural record. Apply the significance
test and ask only about a concrete unresolved choice with meaningfully
different consequences.
- A decision this repository does not own. Company-level and portfolio
decisions live in the record set that owns them. Cite that id; do not copy the
record into a repository that cannot supersede it.
Steps
- List the records in force for the paths you are changing. Read
decisions/ (or the configured folder), keep the records whose applies-to matches a path you are
about to touch and whose status is accepted, and order them newest first.
Report the count — "0 records matched" and "3 matched, none contradicted" are
different verdicts and must read differently.
- Cite what you relied on. Name the ids on the work item, in the pull
request body, and as a
Decision: <id> commit trailer. A change that
silently contradicts an accepted record is a defect even when the code is
correct.
- Apply the significance test before proposing a record or asking for
acceptance. Write a record only when at least one of these holds: someone
will otherwise re-litigate the choice; it binds paths beyond the one you are
changing; reversing it would cost real migration or rework; or it rejects an
option a reasonable reader would reach for. If none holds, make the change
without a record. Do not ask the user to approve labels or abstractions they
have not been given enough context to understand.
- Pass the completeness gate, or open with
status: returned. A proposed
record states the options considered including the one not taken and why,
the default that applies if the question is never answered and what that
default costs, the timeline the decision has to hold to, and what is in scope
and out. A record missing any of the four is returned to its proposer for
revision — returned is not a rejection.
- Write the verification criterion before acceptance, not after. State the
observable signal that will say the decision was actually carried out, as
Done when and Verify by. A decision whose success cannot be observed
cannot reach stage: verified.
- Open the record as
status: proposed, stage: none, and regenerate the
index. A record the index does not list is a record the consult step in
step 1 will never find.
- Accept only after a human makes the significant choice. Set
status to
accepted, decided to the date, and decider to a named person — never a
role, a team, or a tool. Acceptance is a human verdict: draft it, do not grant
it. If the decider is not already explicit, first explain in plain language
that the choice will become durable repository documentation and why it
passed the significance test; only then ask whose name should be recorded.
- Spawn the build work carrying the criterion verbatim. The
Done when and
Verify by text written in step 5 travels onto the work item unchanged, so
the thing that gets built is the thing that was decided.
- Move
stage only on the evidence the next stage requires. none →
implemented when the change exists in the tree; implemented → verified
only on a signal observed this time. Accepted is not implemented, and
implemented is not verified.
- Supersede rather than rewrite. Never edit an accepted record's decision
text in place — that text is what people relied on. Correct a typo or add
context under a dated banner that says what changed and why. Change the
choice only with a new record.
- Point both ways and sweep the citations. The new record names the one it
replaces in
supersedes; the replaced record's status becomes
superseded and it gains a superseded-by pointer forward, with its
original text preserved. Then find every work item, pull request body, and
commit trailer citing the old id and point it at the new one. A reader
arriving at either record must be able to reach the other.
Read record-format.md when authoring or updating a record or regenerating its index; it defines the exact front-matter fields, closed value sets, and index shape.
What breaks
- Governance ceremony before user clarity. Asking someone to choose between
unexplained policy labels, approve an issue plan they already asked to
implement, or name a decider before explaining the durable decision transfers
the agent's interpretation burden to the user.
- A role in the
decider field. "The architecture team decided" names
nobody who can be asked what they meant or who can supersede it. The record
reads as authority but resolves to no one.
- Decision text edited in place. The next reader sees text nobody ever
agreed to, and the people who relied on the old wording have no way to tell
what changed. This is the failure that makes a whole
decisions/ folder
untrustworthy, because it is invisible.
- A one-way supersession. The new record says it supersedes the old one, but
the old one still reads as accepted. Whoever arrives from a search, a
citation, or an old pull request follows a decision that was replaced.
stage: verified set on a green build. Compilation proves it builds, not
that the decision was carried out. The stage then lies about the only thing it
exists to say.
- A ruling that stayed in chat. It binds the next change and nobody can find
it. The symptom is the same argument being had a second time, with a different
outcome.
- One record settling three questions. It cannot be superseded for one of
them, so it survives past the point where a third of it is wrong.
- An
applies-to that matches nothing. Step 1 returns zero records and reads
as "nothing binds this change" instead of "the glob is wrong". Report the count
so an empty result is visible rather than reassuring.
How it is proven
- Consult ran and found something specific. The count from step 1 appears in
the report, and the ids it returned appear on the work item, in the pull
request body, and in a
Decision: commit trailer.
- Acceptance resolves. The record carries a
decided date and a decider
that names a person you could actually ask.
- Supersession is traversable. Follow
superseded-by forward and
supersedes back; both land on the other record. Search the repository for
the superseded id and confirm no live citation still points only at it.
- The stage matches the evidence.
implemented is confirmed by the change
being in the tree; verified is confirmed by naming the signal — the command,
the gate, the observed behavior — that was watched this time.
- The index resolves. Every record in
decisions/ appears in the index, and
every index entry resolves to a file.
1---2name: cratis-engineering-decision-record-23description: Use before a significant architectural, contract or cross-cutting change, or when recording or replacing a durable decision. Not for routine implementation approvals, product docs, session handovers or issue status.4license: LICENSE5metadata:6 source: https://skillmd.com/skills/cratis/cratis-engineering-decision-record-27---89# Cratis decision records1011A decision is a durable choice with a **decider** and a **date**. It is12documentation, not a work record: it lives in the repository's `decisions/`13folder (or the folder `.cratis/ai.json` sets as `process.decisions.path`) and is reviewed like any other documentation. A handover may summarize a14decision; it never holds the only copy.1516This skill owns the *procedure* — how to consult, author, accept, and supersede17a record. It does not decide what to decide, and it never grants acceptance. Do18not turn an implementation request, issue plan, or reversible technical choice19into an approval ceremony merely because this skill is available.2021## When you need this2223- You are about to make a significant architectural, contract, scope, or24 cross-cutting change. Consult existing records first: a decision you did not25 read still binds the change. Consulting does not imply that a new record or26 human approval is required.27- A human made a durable ruling — in review, in chat, or in a meeting — that28 later work has to obey. Record it in the same turn, while the reasoning is29 still available.30- An accepted decision no longer holds and has to be replaced, narrowed, or31 qualified.32- Your change would contradict an accepted record. Stop: supersession or a human33 verdict comes first, never a workaround.3435## When you do not3637- **Session notes, plans, handovers, status boards.** Those are work records.38 They belong in the repository's ignored local working directory, never in39 `decisions/`.40- **Product or API documentation.** A record says what was chosen and why; the41 documentation says how the thing works. Use the documentation workflow.42- **A work item's status.** "Blocked on X" is a work item field, not a decision.43- **A reversible choice inside your own scope that nobody will re-litigate.**44 Make it and move on; see the significance test in step 3.45- **An implementation request or an issue's proposed plan.** A request to do the46 work authorizes ordinary in-scope implementation; it is not automatically a47 request to create or accept an architectural record. Apply the significance48 test and ask only about a concrete unresolved choice with meaningfully49 different consequences.50- **A decision this repository does not own.** Company-level and portfolio51 decisions live in the record set that owns them. Cite that id; do not copy the52 record into a repository that cannot supersede it.5354## Steps55561. **List the records in force for the paths you are changing.** Read57 `decisions/` (or the configured folder), keep the records whose `applies-to` matches a path you are58 about to touch and whose `status` is `accepted`, and order them newest first.59 Report the count — "0 records matched" and "3 matched, none contradicted" are60 different verdicts and must read differently.612. **Cite what you relied on.** Name the ids on the work item, in the pull62 request body, and as a `Decision: <id>` commit trailer. A change that63 silently contradicts an accepted record is a defect even when the code is64 correct.653. **Apply the significance test before proposing a record or asking for66 acceptance.** Write a record only when at least one of these holds: someone67 will otherwise re-litigate the choice; it binds paths beyond the one you are68 changing; reversing it would cost real migration or rework; or it rejects an69 option a reasonable reader would reach for. If none holds, make the change70 without a record. Do not ask the user to approve labels or abstractions they71 have not been given enough context to understand.724. **Pass the completeness gate, or open with `status: returned`.** A proposed73 record states the options considered *including the one not taken and why*,74 the default that applies if the question is never answered and what that75 default costs, the timeline the decision has to hold to, and what is in scope76 and out. A record missing any of the four is returned to its proposer for77 revision — `returned` is not a rejection.785. **Write the verification criterion before acceptance, not after.** State the79 observable signal that will say the decision was actually carried out, as80 `Done when` and `Verify by`. A decision whose success cannot be observed81 cannot reach `stage: verified`.826. **Open the record as `status: proposed`, `stage: none`, and regenerate the83 index.** A record the index does not list is a record the consult step in84 step 1 will never find.857. **Accept only after a human makes the significant choice.** Set `status` to86 `accepted`, `decided` to the date, and `decider` to a named person — never a87 role, a team, or a tool. Acceptance is a human verdict: draft it, do not grant88 it. If the decider is not already explicit, first explain in plain language89 that the choice will become durable repository documentation and why it90 passed the significance test; only then ask whose name should be recorded.918. **Spawn the build work carrying the criterion verbatim.** The `Done when` and92 `Verify by` text written in step 5 travels onto the work item unchanged, so93 the thing that gets built is the thing that was decided.949. **Move `stage` only on the evidence the next stage requires.** `none` →95 `implemented` when the change exists in the tree; `implemented` → `verified`96 only on a signal observed this time. Accepted is not implemented, and97 implemented is not verified.9810. **Supersede rather than rewrite.** Never edit an accepted record's decision99 text in place — that text is what people relied on. Correct a typo or add100 context under a dated banner that says what changed and why. Change the101 *choice* only with a new record.10211. **Point both ways and sweep the citations.** The new record names the one it103 replaces in `supersedes`; the replaced record's `status` becomes104 `superseded` and it gains a `superseded-by` pointer forward, with its105 original text preserved. Then find every work item, pull request body, and106 commit trailer citing the old id and point it at the new one. A reader107 arriving at either record must be able to reach the other.108109Read [record-format.md](references/record-format.md) when authoring or updating a record or regenerating its index; it defines the exact front-matter fields, closed value sets, and index shape.110111## What breaks112113- **Governance ceremony before user clarity.** Asking someone to choose between114 unexplained policy labels, approve an issue plan they already asked to115 implement, or name a decider before explaining the durable decision transfers116 the agent's interpretation burden to the user.117- **A role in the `decider` field.** "The architecture team decided" names118 nobody who can be asked what they meant or who can supersede it. The record119 reads as authority but resolves to no one.120- **Decision text edited in place.** The next reader sees text nobody ever121 agreed to, and the people who relied on the old wording have no way to tell122 what changed. This is the failure that makes a whole `decisions/` folder123 untrustworthy, because it is invisible.124- **A one-way supersession.** The new record says it supersedes the old one, but125 the old one still reads as accepted. Whoever arrives from a search, a126 citation, or an old pull request follows a decision that was replaced.127- **`stage: verified` set on a green build.** Compilation proves it builds, not128 that the decision was carried out. The stage then lies about the only thing it129 exists to say.130- **A ruling that stayed in chat.** It binds the next change and nobody can find131 it. The symptom is the same argument being had a second time, with a different132 outcome.133- **One record settling three questions.** It cannot be superseded for one of134 them, so it survives past the point where a third of it is wrong.135- **An `applies-to` that matches nothing.** Step 1 returns zero records and reads136 as "nothing binds this change" instead of "the glob is wrong". Report the count137 so an empty result is visible rather than reassuring.138139## How it is proven140141- **Consult ran and found something specific.** The count from step 1 appears in142 the report, and the ids it returned appear on the work item, in the pull143 request body, and in a `Decision:` commit trailer.144- **Acceptance resolves.** The record carries a `decided` date and a `decider`145 that names a person you could actually ask.146- **Supersession is traversable.** Follow `superseded-by` forward and147 `supersedes` back; both land on the other record. Search the repository for148 the superseded id and confirm no live citation still points only at it.149- **The stage matches the evidence.** `implemented` is confirmed by the change150 being in the tree; `verified` is confirmed by naming the signal — the command,151 the gate, the observed behavior — that was watched *this time*.152- **The index resolves.** Every record in `decisions/` appears in the index, and153 every index entry resolves to a file.