diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index f6bc7e8..0eb3307 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -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" }, diff --git a/plugin/skills/reporting-back/SKILL.md b/plugin/skills/reporting-back/SKILL.md index 02f8980..87aba75 100644 --- a/plugin/skills/reporting-back/SKILL.md +++ b/plugin/skills/reporting-back/SKILL.md @@ -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 | diff --git a/plugin/skills/using-scribe/SKILL.md b/plugin/skills/using-scribe/SKILL.md index da98344..984a30e 100644 --- a/plugin/skills/using-scribe/SKILL.md +++ b/plugin/skills/using-scribe/SKILL.md @@ -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 diff --git a/src/scribe/mcp/server.py b/src/scribe/mcp/server.py index 22d8111..2163ef4 100644 --- a/src/scribe/mcp/server.py +++ b/src/scribe/mcp/server.py @@ -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. diff --git a/tests/test_guidance_ownership.py b/tests/test_guidance_ownership.py index 57f256e..99241be 100644 --- a/tests/test_guidance_ownership.py +++ b/tests/test_guidance_ownership.py @@ -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