Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 6 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
Jason Walker
2026-07-02 18:59:23 -04:00
parent 790c2c80b1
commit e9c67e7292
4 changed files with 67 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/llm-workflow-runbooks.md
+20 -11
View File
@@ -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