🐛 Add shutdown protocol to pr-logbook skill - #106
Conversation
hcross
left a comment
There was a problem hiding this comment.
Cold-start review — PR #106
Independent audit, no authoring context. (Posted as COMMENT because GitHub blocks self-approval; intended verdict is Approve.)
Correctness
The change adds a ## Shutdown protocol section to the three pr-logbook/SKILL.md files (community-config/, .claude/, .gemini/). The new section:
- Specifies the exact
shutdown_responseJSON payload (type,request_id,approve: true) — verifiable atcommunity-config/skills/pr-logbook/SKILL.md:223-227. - States the hard-stop semantics: no deferral, no summarising, no waiting on in-flight ops.
- Adds a post-completion rule:
TaskUpdate→ completion message → stop, no re-entering the wait loop.
This directly addresses the failure mode described in #104 (agent kept sending idle notifications without consuming shutdown_request). The mitigation is prescriptive only, which is consistent with the PR body's note that the runtime watchdog is tracked separately under #42.
Convention compliance
- Gitmoji title:
🐛 Add shutdown protocol to pr-logbook skill— conforms toAGENTS.md§"Commit Convention". - PR body structure: all four required sections present (intro, How to read, How to test, Detailed description). ✅
- Logbook linkage: PR body states the logbook entry was appended as a comment on #104 itself. Acceptable interpretation — the friction-cluster issue serves dual duty as feedback and logbook anchor.
- Version bump:
provenance.version1.1.3→1.1.4in the community-config source (PATCH for wording-only change). Mirrors carry the same string. ✅ - Three mirrors byte-identical for the new section: verified locally via the
diffcommands from the PR's test plan —MIRRORS_OK. ✅ - Branch name:
fix/issue-104-pr-logbook-shutdown-protocol— conforms tofix/prefix convention.
Test coverage
Documentation-only change; no executable surface to cover with tests. The PR's test plan provides two verification steps (mirror diff + task check-skill-versions); both are appropriate for a SKILL.md edit. Mirror diff confirmed clean locally.
Linter findings
lint-markdown.sh community-config/skills/pr-logbook/SKILL.md→ exit 0, no output. Clean.BASE_REF=origin/main lint-skill.sh community-config/skills/pr-logbook/SKILL.md→ exit 0, no output. Frontmatter fields present, version bumped vs base. Clean.
Nit (non-blocking)
The "Detailed description" claims "Each file gains the same two sections at the end: ## Idle behavior and ## Shutdown protocol." The diff actually adds only ## Shutdown protocol; ## Idle behavior was already present from #96 (visible in the @@ -216,3 +216,21 @@ hunk, which appends after the existing Idle-behavior block). Minor description-vs-reality drift, not worth a re-push.
Verdict
Approve. The change is tight, well-scoped, conforms to project conventions, and closes the skill-text half of the gap reported in #104. Mirrors are consistent and linters are clean.
Implements #104. Adds a
Shutdown protocolsection to the pr-logbook skill so the agent exits cleanly after completing a task and responds immediately toshutdown_requestsignals instead of idling in a poll-without-consume loop.How to read this PR?
Single logical change, three mirrored files. Read in this order:
community-config/skills/pr-logbook/SKILL.md— the source of truth. Two additions at the bottom: a one-paragraphIdle behaviornote and aShutdown protocolsection with the exact JSON payload the agent must send.provenance.versionbumped1.1.3→1.1.4per the version-bump rule in §"Cross-cutting: skill / agent source version bumps"..claude/skills/pr-logbook/SKILL.mdand.gemini/skills/pr-logbook/SKILL.md— byte-identical mirrors of the community-config source.Non-obvious design decision: the shutdown text is prescriptive only. It does not implement a watchdog. The curator's report (#104) proposed a runtime mitigation at the team-orchestration layer; that work is tracked separately under the auto-fix effort referenced by #42. This PR closes the skill-text half of the gap.
How to test this PR?
Failure mode covered: forgetting to bump
provenance.versionwhile editing a SKILL.md source —scripts/check-skill-versions.shrejects the diff.Detailed description (for agents)
Modified:
community-config/skills/pr-logbook/SKILL.md,.claude/skills/pr-logbook/SKILL.md,.gemini/skills/pr-logbook/SKILL.md(3 files, +57 / −3 in commita65e963).Each file gains the same two sections at the end:
## Idle behavior— restates the one-sentence availability-confirmation rule established by Friction cluster: teammate-redundant-idle-confirmation (1 report) #96, kept here so the shutdown contract sits next to the related guidance.## Shutdown protocol— defines the contract:shutdown_requestmessage, respond with{"type": "shutdown_response", "request_id": "<id>", "approve": true}and stop. No deferral, no summarising, no waiting on in-flight ops.TaskUpdate→ completion message → stop. Do not re-enter a wait loop.provenance.versionin the community-config source is bumped1.1.3→1.1.4(PATCH — friction-driven wording fix, no contract change). The.claude/and.gemini/mirrors carry the same version string.Post-merge action (per skill §7): close #104 with
state_reason: completed. The logbook entry was appended as a comment on #104 itself (the upstream feedback issue), so no separate logbook issue exists to close.