A canon is only urged on a shape that could be it, the ledger can say what looks wrong, and the agent is the judge #173

Merged
bvandeusen merged 7 commits from dev into main 2026-09-20 23:07:04 -04:00
5 changed files with 84 additions and 2 deletions
Showing only changes of commit 76bf21633e - Show all commits
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "scribe",
"description": "Scribe for Claude Code: connects the scribe MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Scribe skills (using-scribe, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting), and syncs your saved Scribe Processes as skills (/scribe:sync).",
"version": "2026.09.20.2244",
"version": "2026.09.21.0253",
"author": {
"name": "Bryan Van Deusen"
},
+35 -1
View File
@@ -101,11 +101,45 @@ default differ, the preference is what they asked for.
| Kind | Sections |
|---|---|
| **Completion** | Where this sits · What now works · How / why · Needs you · Next |
| **Finding** (a problem you found and did not fix) | Symptom · Cause · Size of the fix · **Offer to fix it** |
| **Finding** (a problem you found) | Symptom · Cause · **What you decided and did** — judge it and act; an offer to fix it is the judgment not made (see *You are the judge*) |
| **Blocked / failed** | What stopped · What you tried · What you need from them |
| **Progress** (mid-work) | One or two lines: where things are, what's next, any blocker |
| **Where are we** | The milestone and its progress · Done · Open · Needs you · Next |
## You are the judge
You are the judge of record for the work itself: what a shape is, whether a
finding holds, whether a record is right, whether something is done. The
operator reads the decision — they do not make it.
**A finding surfaced and not judged is a finding dropped, not deferred.** This
is the failure that hides inside a good report: the symptom named, the cause
traced, the fix sized, and then handed over for someone else to rule on. It
reads as diligence and functions as a backlog. The tells are "say the word and
I'll…", "your call", "let me know if you want me to…", and a list of options
for a decision that was yours.
So: decide, act, and report what you decided and why. If the evidence is
genuinely balanced, say which way you went and what would change your mind —
that is still a decision.
**What DOES go to them**, and the distinction is the act, not the difficulty:
spending their money, reaching their infrastructure, merging to a protected
branch, anything hard to reverse or facing outward — the **Handoff** and
**Approval** shapes below. Judging a record is never one of these. A hard call
is still yours; an irreversible act is still theirs.
**Judging is attended, not automatic.** You judge by reading the evidence and
recording why. A threshold, a sweep or a rule that reclassifies in bulk with
nobody reading it is not you judging — it is the thing that usually created
the mess, wearing your name. When you catch yourself fixing bad unattended
writes with another unattended write, stop.
**Building a review surface?** Ask who its implied reader is. If the answer is
"a person works through this queue", it is mis-designed: give the reader the
evidence needed to decide and a way to record the decision under their own
name.
## Asks — the operator needs to act or decide
| Kind | Sections |
+29
View File
@@ -376,6 +376,35 @@ 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.
## You are the judge of what the record says
Scribe's shape exists to support how you work, so you are the judge of record
for the work itself: what a shape is, which canon a thing belongs to, whether
a finding holds, whether something is done. `classify_shapes`, `update_task`,
`create_snippet` and the rest are where your judgment lands — under your own
name, with the reasoning recorded beside it.
**Judging is attended, and that is the whole distinction.** You judge by
reading the evidence and writing down why. A threshold, a sweep or a hook that
classifies in bulk with nobody reading it is not judgment; it is the thing
that fills a ledger with confident nonsense. The write-path hook may offer
evidence (`classified_by="hook"`) and any judgment of yours overrides it —
that asymmetry is deliberate. When you are about to correct a pile of bad
unattended writes with one more unattended write, stop and read them instead.
**A finding you surface and do not judge is a finding dropped.** Handing a
classification, a verdict or a done/not-done call to the operator "to decide"
is the judgment not being made, however carefully it is written up. Keep
escalating the acts that are genuinely theirs — their money, their
infrastructure, anything hard to reverse or facing outward — and keep the
decisions. A hard call is still yours; an irreversible act is still theirs.
**A record that is wrong stays wrong until something rewrites it.** A guard
added at the point of classification does not undo classifications already
stored, so when you fix how judgments are made, go and look at the ones
already there. That look is yours to do, and its result is a judgment you
record, not a queue you leave behind.
## When a record doesn't reach the moment it should
Retrieval misjudging is ordinary, and it is fixable — but only by whoever
+6
View File
@@ -51,6 +51,12 @@ client reads Agent Skills) and in each tool's description. The index:
guide and you keep them current; lessons inform.
- MISSED: a rule that missed you is a trigger to fix, not a
floor to move (retrieval_telemetry).
- JUDGE: you are the judge of record here — what a shape is, whether a
finding holds, whether work is done. Surfacing one for the operator to
rule on is the judgment NOT made, however well it is written up. Escalate
the acts that are theirs (their money, their infrastructure, anything hard
to reverse), not the decisions. Judging is attended: an agent reading the
evidence and recording why — never a threshold firing on its own.
- RECALL: search before acting, scoped with the active project_id.
- RECORD: create_task; a fix is kind="issue". add_task_log as you go; status
in_progress on start, done on finish. Tag system_ids as you write.
+13
View File
@@ -212,6 +212,19 @@ TOPICS: tuple[Topic, ...] = (
"a record you only mention is a record to read"),
# ── per-tool contracts and in-band behaviour — owned by the server ──
Topic("closing a task cues the report", "docstrings", ("report_back",), "reporting this to the operator?"),
# The agent is the judge (#4208). Two topics, not one, because they fire
# at different moments and say different things: using-scribe owns the
# authority — what you may decide and that deciding means READING, not
# thresholding — while reporting-back owns the shape a report takes when
# the judgment is made. They are stated separately rather than shared so
# that trimming one cannot quietly take the other with it.
Topic("the agent judges the record, and judging is attended", U,
("judge of record", "attended", "classify_shapes"),
"a record that is wrong stays wrong until something rewrites it",
index=("judge of record",)),
Topic("a finding surfaced and not judged is a finding dropped",
"skill:reporting-back", ("you are the judge", "hard to reverse"),
"it reads as diligence and functions as a backlog"),
Topic("a note that asserts a fact carries its check", "docstrings", ("verify_with", "expires_when"),
"could this note become false without anyone editing it",
# Stated at two different moments on purpose: the tool contract is