From e9c67e72928d628b47b01dda4654d62340a1c773 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Thu, 2 Jul 2026 18:59:23 -0400 Subject: [PATCH] docs: compact Controller Handoff as default format (#108) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/llm-workflow-runbooks.md | 31 +++++++----- skills/llm-project-workflow/SKILL.md | 49 ++++++++++++++++--- .../templates/review-pr.md | 4 +- .../templates/start-issue.md | 4 +- 4 files changed, 67 insertions(+), 21 deletions(-) diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 868f6c0..634affb 100644 --- a/docs/llm-workflow-runbooks.md +++ b/docs/llm-workflow-runbooks.md @@ -337,28 +337,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 -without rereading the conversation. The canonical format and rules live in the -portable skill: +`Controller Handoff`** so a controller LLM can pick up the state +without rereading the conversation. The canonical formats and rules live in +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 -commit, issue #s, PR #s, complete/blocked/ready-for-review/discussion-only) · -Files changed · Validation · Issues encountered · Review needed? (one of the -five fixed answers) · Next recommended action · Safety confirmations -(no self-review; no self-merge; no release/tag changes unless requested; no -secrets; no production access unless authorized). +**Compact format is the default** — nine lines (`Task / Repo/state / +Issues/PRs / Changed / Validation / Blockers / Review / Next / Safety`), +written for controller-LLM readability, not a full human status report. The +`Safety:` line is never omitted (usually +`no self-review; no self-merge; no tags; no secrets; no prod`). PR bodies +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 diff --git a/skills/llm-project-workflow/SKILL.md b/skills/llm-project-workflow/SKILL.md index 2cd53a4..b408895 100644 --- a/skills/llm-project-workflow/SKILL.md +++ b/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. @@ -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 diff --git a/skills/llm-project-workflow/templates/review-pr.md b/skills/llm-project-workflow/templates/review-pr.md index afd44d1..af41c34 100644 --- a/skills/llm-project-workflow/templates/review-pr.md +++ b/skills/llm-project-workflow/templates/review-pr.md @@ -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. ``` diff --git a/skills/llm-project-workflow/templates/start-issue.md b/skills/llm-project-workflow/templates/start-issue.md index aec81e5..80c2b9a 100644 --- a/skills/llm-project-workflow/templates/start-issue.md +++ b/skills/llm-project-workflow/templates/start-issue.md @@ -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". ```