From 6eb5ef5c731b74448bffd59bdfd509bab327f9d8 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Tue, 15 Sep 2026 15:21:28 -0400 Subject: [PATCH] docs(plugin): a request for the operator's approval gets its own "Approval requested" section (#4084) A session's go-ahead request sat inside a completion list as "Blocked by the permission check", and the operator read it as a fault rather than a question waiting on them. The reporting-back skill now puts any action held for a yes under a section headed "Approval requested", near the top of whatever reply it is: each change numbered so part can be approved, why it needs them, how it is undone, and what happens after. The Asks table gains an Approval row, and the completion report's "Needs you" points at the section. test_reporting_back_skill pins the heading and the row. Plugin version minted: 2026.09.15.1921. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy --- plugin/.claude-plugin/plugin.json | 2 +- plugin/skills/reporting-back/SKILL.md | 10 +++++++++- tests/test_reporting_back_skill.py | 10 ++++++++++ 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 0db0f27..e67ef7b 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.15.1744", + "version": "2026.09.15.1921", "author": { "name": "Bryan Van Deusen" }, diff --git a/plugin/skills/reporting-back/SKILL.md b/plugin/skills/reporting-back/SKILL.md index 90d91b5..a2f1288 100644 --- a/plugin/skills/reporting-back/SKILL.md +++ b/plugin/skills/reporting-back/SKILL.md @@ -23,6 +23,12 @@ when one is short — "**Needs you:** nothing" is an answer they were looking fo plain. - **End with the ask, in bold** — the one thing they need to decide or do. If there is nothing, say so. +- **A request for approval gets its own section, headed "Approval requested".** + Whenever you are holding an action until the operator says yes — a permission + prompt their client raised, something hard to undo, a change you have + prepared and not made — put it there, near the top, whatever kind of reply + this is. Inside a progress or completion list it reads as a status line, and + the operator does not see that you are waiting on them. - **Plain words.** Use the operator's vocabulary, not the names you coined while working. If a term has to appear, explain it once. - **Place the work in Scribe.** Name the task, issue or milestone it belongs to, @@ -76,6 +82,7 @@ default differ, the preference is what they asked for. | **Decision** | The question first · 2–4 options, each with what it changes · recommendation first | | **Clarification** | "My reading is X · the gap is Y · unless you say otherwise I'll do Z" | | **Handoff** (only they can do it) | The action · why it needs them · what it unblocks · what you'll do after · any way to skip it | +| **Approval** (you are ready to act and holding for a yes) | **Approval requested:** exactly what happens once they approve, one numbered item per change so they can approve part · why it needs their yes · how it can be undone · what you'll do after | | **Conflict** (what you're about to do clashes with a rule, a plan or an earlier decision) | What it says · what you were about to do · where they clash · A or B? | Before asking, check whether you can find the answer yourself — something that @@ -128,7 +135,8 @@ Notes on each section: verified**. If something could not be verified, say what and why here rather than letting it read as passed. - **Needs you** — an action, an approval, a decision, or "nothing". If it's an - action, give the reason with it. + action, give the reason with it. An approval you are holding for also gets + its own **Approval requested** section, and this line points at it. - **Next** — from `placement.next`, or say the milestone is finished. If you found something you didn't fix, the offer to fix it goes here. diff --git a/tests/test_reporting_back_skill.py b/tests/test_reporting_back_skill.py index 7cdce13..da10576 100644 --- a/tests/test_reporting_back_skill.py +++ b/tests/test_reporting_back_skill.py @@ -38,6 +38,16 @@ def test_the_completion_report_keeps_its_sections(): assert section in text, f"the completion report lost its {section!r} section" +def test_a_request_for_approval_has_its_own_named_section(): + """The operator, 2026-09-15 (#4084): a session's go-ahead request sat inside + a completion list as "Blocked by the permission check", and read as a + fault rather than a question waiting on them. The heading is what they + scan for, so it is pinned by name.""" + text = _text() + assert "Approval requested" in text + assert "| **Approval**" in text, "the Asks table lost its Approval row" + + def test_placement_comes_from_the_record(): """The failure this milestone started from: a placement written from memory reads exactly like a real one when it is wrong."""