Merge pull request 'docs: compact Controller Handoff as default format (#108)' (#115) from docs/issue-108-compact-controller-handoff into master

docs/llm-workflow-runbooks.md

@@ -364,28 +364,37 @@ touching anything.
   files, detected secret, or any production/deploy behavior — **stop, report the
   blocker, and take no mutating action.** Fail closed; never work around a gate.
 
-## Controller Handoff Summary (required, every task)
+## Controller Handoff (required, every task)
 
 Every task — implementation, review, merge, triage, documentation,
 discussion-only, or blocked planning — **must end with a
-`Controller Handoff Summary`** so a controller LLM can pick up the state
+`Controller Handoff`** so a controller LLM can pick up the state
-without rereading the conversation. The canonical format and rules live in the
+without rereading the conversation. The canonical formats and rules live in
-portable skill:
+the portable skill:
 [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) §K.
 
-Sections (in order): Work performed · Current state (repo, branch/master
+**Compact format is the default** — nine lines (`Task / Repo/state /
-commit, issue #s, PR #s, complete/blocked/ready-for-review/discussion-only) ·
+Issues/PRs / Changed / Validation / Blockers / Review / Next / Safety`),
-Files changed · Validation · Issues encountered · Review needed? (one of the
+written for controller-LLM readability, not a full human status report. The
-five fixed answers) · Next recommended action · Safety confirmations
+`Safety:` line is never omitted (usually
-(no self-review; no self-merge; no release/tag changes unless requested; no
+`no self-review; no self-merge; no tags; no secrets; no prod`). PR bodies
-secrets; no production access unless authorized).
+still carry the full review detail — the handoff never replaces PR
+documentation.
+
+**The long form** (Work performed · Current state · Files changed ·
+Validation · Issues encountered · Review needed? · Next recommended action ·
+Safety confirmations) **is reserved for high-risk or complex tasks**: a
+merge/tag/release happened, validation failed, permissions/profile gates
+blocked work, secrets or production access were involved, an owner decision
+is complicated, the task spanned multiple repos or cross-issue state, or the
+owner explicitly asks for it.
 
 Hard rules: never omit it; never bury blockers earlier only; an opened PR
 means "Review needed — PR is open"; a blocked merge names the exact gate;
 discussion-only comments need owner/design feedback, not code review; any
 touched release state names the exact tag/commit and why. Design debates
 belong in **discussion/RFC issues** (e.g. #100 `profiles.json v2`) — comment
-on the issue, create no branches/PRs, and end the comment with this summary.
+on the issue, create no branches/PRs, and end the comment with this handoff.
 
 ## Fail-closed behavior
 

skills/llm-project-workflow/SKILL.md

@@ -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.
@@ -248,16 +248,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.
@@ -269,7 +295,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

skills/llm-project-workflow/templates/review-pr.md

@@ -38,6 +38,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
+formatted per SKILL.md §K (compact by default; long form if a merge happened
-merge, name the exact gate that blocked it.
+or a gate blocked you); if you could not merge, name the exact gate.
 ```

skills/llm-project-workflow/templates/start-issue.md

@@ -42,6 +42,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
+formatted as the compact Controller Handoff (SKILL.md §K; long form only on
-"Review needed — PR is open".
+the high-risk triggers); Review line: "Review needed — PR is open".
 ```