feat(guidance): an operator's ruling lives on the System it governs, and code is read as behaviour, not intent (milestone 444 steps 1-2, #4754 #4755)
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 53s
CI & Build / integration (push) Successful in 55s
CI & Build / Python tests (push) Successful in 1m46s
CI & Build / Build & push image (push) Successful in 56s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 53s
CI & Build / integration (push) Successful in 55s
CI & Build / Python tests (push) Successful in 1m46s
CI & Build / Build & push image (push) Successful in 56s
A Librarian session contradicted a decision the operator had made 13 days
earlier. The ruling ("retry, then replace, never give up on a book") was
kept only as a quote in a work log, beside a session's reading of it that
capped replacements at 3. Three later sessions built on the reading, and one
carried the cap into an option as a "known cost", which the operator then
approved without being asked about it.
- writing-records.md: "A ruling goes on the System it governs". What a
ruling is (the operator decided it; a later change could undo it), how it
differs from a rule, and where it goes: a Rulings section at the end of
the System description, one line each with who, when and the source
record. Written the turn the operator decides; holds what is in force,
not history; a charter line that contradicts a ruling is fixed in the
same edit.
- using-scribe SKILL.md: reflex 1 says code tells you what a thing does,
not what was wanted, and a limit read from code is unconfirmed until a
System's Rulings says otherwise. Reflex 9 points to the ruling section.
- reporting-back: an option that carries existing behaviour says whose call
it was (the operator's ruling, or a past session's never confirmed); one
that contradicts a ruling is a Conflict.
- create_system / update_system docstrings: the Rulings section, and that
description replaces the whole text.
- test_guidance_ownership: three topics pinned to their owners.
- Plugin version minted.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -2,11 +2,13 @@
|
||||
|
||||
Part of the using-scribe skill. Read it before `create_rule`,
|
||||
`create_project_rule`, `create_preference` or `create_lesson`; when a lesson
|
||||
arrives that names the situation you are actually in; and before filling
|
||||
arrives that names the situation you are actually in; when the operator
|
||||
decides how some area of the work must behave; and before filling
|
||||
`verify_with` or `expires_when` on a note.
|
||||
|
||||
## Contents
|
||||
- Where a new rule goes — its home, its trigger, what already covers the moment
|
||||
- A ruling goes on the System it governs
|
||||
- A lesson grows each time it proves itself
|
||||
- A lesson names the rule it is an instance of
|
||||
- A note that asserts a fact can carry its own check
|
||||
@@ -65,6 +67,52 @@ insight that costs time is a **lesson** (`create_lesson`), keyed to the
|
||||
situation it applies to so a later session meets it there. Both are first-class
|
||||
outcomes of noticing something, not what's left when a rule proposal fails.
|
||||
|
||||
## A ruling goes on the System it governs
|
||||
|
||||
A **ruling** is the operator's decision about what the work itself does in one
|
||||
area: how it behaves, what it must never do, which way a trade-off goes. It is
|
||||
not a rule. A rule governs how *you* work and reaches you when your work
|
||||
resembles it; a ruling governs what the *thing being built* does, and it has to
|
||||
reach every session working in that area, whatever words that session is using.
|
||||
|
||||
Two tests, and it needs both:
|
||||
|
||||
- **The operator decided it.** They said it, or approved it when it was put to
|
||||
them as its own question. Approving an option is not approving every
|
||||
assumption the option carried — only what it named.
|
||||
- **A later change could plausibly undo it.** "Failed work is retried until it
|
||||
succeeds" qualifies. The name of the table that tracks the retries does not;
|
||||
that is implementation, and it lives in the code and the logs.
|
||||
|
||||
A choice a session made on its own is not a ruling, however sound. Keeping the
|
||||
two apart is the point: once code embodies a session's choice, it reads exactly
|
||||
like the operator's intent, and the next session builds on it as if it were.
|
||||
|
||||
**Where it goes: a `Rulings` section at the end of the System's description**,
|
||||
one line each — the statement, who decided, when, and the record it came from:
|
||||
|
||||
Rulings
|
||||
- Failed work is retried until it succeeds; no attempt limit. (Operator, 2026-09-19, #1234; restated 2026-10-02, #1290)
|
||||
|
||||
The description arrives with every record filed under that System, so a ruling
|
||||
there reaches each session working in the area without having to win a search.
|
||||
A quote inside a work log does not: it surfaces only when a query happens to
|
||||
match it, and the passage that matches is usually the prose around it — often a
|
||||
session's *reading* of the ruling rather than the ruling.
|
||||
|
||||
**When: in the turn the operator decides, before building on it.**
|
||||
`get_system(id)`, then `update_system(id, description=...)` with the whole
|
||||
description — the field is replaced, not appended to. Also when the operator
|
||||
corrects work that departed from something they had already said: that ruling
|
||||
existed and did not reach the work, and writing it where it will is half the
|
||||
fix. No System fits? The area is probably unnamed — create it.
|
||||
|
||||
**It holds what is in force, not its history.** When a ruling is overturned,
|
||||
change or remove its line and cite the record that changed it; the work log
|
||||
keeps the history. If the charter above the section contradicts a ruling —
|
||||
usually a charter written before the decision — fix that sentence in the same
|
||||
edit. A stale charter line is a ruling nobody made, and it is read as one.
|
||||
|
||||
## A lesson grows each time it proves itself
|
||||
|
||||
When one arrives and the situation it names is the one you are actually in, you
|
||||
|
||||
Reference in New Issue
Block a user