docs: compact Controller Handoff as default format (#108)

Make the nine-line compact Controller Handoff the default end-of-task
format; reserve the long Controller Handoff Summary for high-risk/complex
tasks (merge/tag/release, failed validation, blocked gates, secrets/prod,
complicated owner decisions, cross-repo state, or explicit owner request).
Compact form is for controller-LLM readability, safety confirmations are
never omitted, and PR bodies still carry full review detail.

Updates SKILL.md §K, llm-workflow-runbooks.md, and the start-issue /
review-pr templates. Documentation only.

Refs #101. Closes #108.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-02 18:59:23 -04:00
parent 790c2c80b1
commit e9c67e7292
4 changed files with 67 additions and 21 deletions
+43 -6
View File
@@ -48,7 +48,7 @@ Additional issue-first rules:
the existing one. Design debates belong on the issue, where other LLMs
comment directly. Discussion-only tasks must **not** create branches or PRs;
their comments should include recommendations, risks, open questions, and a
Controller Handoff Summary (§K).
Controller Handoff (§K; compact format unless high-risk).
- **If the repo/tracker home for the work is unclear, stop and ask for an
owner decision.** Do not create a new repository or a new tracker unless
explicitly approved by the owner.
@@ -247,16 +247,42 @@ Ready-to-copy templates live in [`templates/`](templates/):
- [`worktree-cleanup.md`](templates/worktree-cleanup.md) — clean up after merge.
- [`release-tag.md`](templates/release-tag.md) — create a release tag.
## K. Controller Handoff Summary (required, every task)
## K. Controller Handoff (required, every task)
Every LLM task **must end with a `Controller Handoff Summary`** — whether the
Every LLM task **must end with a `Controller Handoff`** — whether the
task was implementation, review, merge, issue triage, documentation,
discussion-only, or blocked planning. It lets a controller LLM understand the
current state immediately, without rereading the conversation.
Rules:
**The compact format is the default.** It is written for controller-LLM
readability, not as a full human status report. PR bodies still carry the
full review detail — the handoff never replaces PR documentation.
- Never omit the summary.
Compact format (default):
```md
## Controller Handoff
- Task:
- Repo/state:
- Issues/PRs:
- Changed:
- Validation:
- Blockers:
- Review:
- Next:
- Safety:
```
The `Safety:` line is never omitted; it is usually:
```text
no self-review; no self-merge; no tags; no secrets; no prod
```
Rules (both formats):
- Never omit the handoff, and never omit the safety confirmations.
- Never bury blockers in earlier text only — they must appear here.
- If you opened a PR, state clearly that review is needed.
- If you reviewed but could not merge, name the exact gate that blocked it.
@@ -268,7 +294,18 @@ Rules:
bypass classifiers, profile gates, missing permissions, or live-consent
requirements**; give the owner concrete options.
Required format:
**Use the long format below instead of the compact one only when the task was
high-risk or complex** — i.e. when any of these happened:
- a merge, tag, or release
- failed validation
- permissions/profile gates blocked work
- secrets or production access were involved
- a complicated owner decision
- multiple repos or cross-issue state
- the owner explicitly asks for the full format
Long format (high-risk/complex tasks only):
```md
## Controller Handoff Summary
@@ -33,6 +33,6 @@ Steps:
- Eligibility: passed/failed
Handoff: reviewer identity, PR author, scope verdict, checks + results, decision —
formatted as the Controller Handoff Summary (SKILL.md §K); if you could not
merge, name the exact gate that blocked it.
formatted per SKILL.md §K (compact by default; long form if a merge happened
or a gate blocked you); if you could not merge, name the exact gate.
```
@@ -37,6 +37,6 @@ Steps:
8. Stop before review/merge — you are the author.
Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL —
formatted as the Controller Handoff Summary (SKILL.md §K); end with
"Review needed — PR is open".
formatted as the compact Controller Handoff (SKILL.md §K; long form only on
the high-risk triggers); Review line: "Review needed — PR is open".
```