Document Controller Handoff Summary and LLM workflow requirements #101

New Issue

2026-07-02T17:13:48-05:00

sysadmin commented

2026-07-02 17:13:48 -05:00

Documentation/skills update capturing the workflow rules established during the Gitea-Tools completion cycle (v1.1.0).

Problem

The portable LLM workflow skill and runbooks do not yet document:

The mandatory end-of-task Controller Handoff Summary block (required for every task type: implementation, review, merge, triage, documentation, discussion-only, blocked planning).
Workflow rules proven during the completion cycle:
- issue-first requirement (incl. "stop and ask when tracker home is unclear"; "no new repo/tracker without explicit approval")
- discussion/RFC issue requirement (design debates on issues; discussion tasks create no branches/PRs)
- review/merge requirement (identity + author verification, no self-review/self-merge, profile gates, pinned head SHA + expected changed files, independent validation, post-merge cleanup)
- release/tag requirement (no tag ops unless instructed; tag only the verified final master merge commit; always report tag target)
- branch/worktree requirement (one issue = one branch/worktree; issue number in branch name; no stale-branch reuse; no bundling)
- blocked/owner-decision handling (stop cleanly; never bypass classifiers/gates/consent; give concrete owner options)

Scope

Docs/skill text only. Update skills/llm-project-workflow/SKILL.md (+ templates as needed) and docs/llm-workflow-runbooks.md. Include the required Controller Handoff Summary format verbatim and a short worked "blocked handoff" example.

Acceptance criteria

Controller Handoff Summary section with the exact required format.
All six rule groups above documented.
Blocked-handoff example included.
No code behavior changed; no labels created; no tags touched; #100 (profiles.json v2 RFC) not modified.

Non-goals

No profiles.json v2 implementation (#100 stays discussion).
No mcp-control-plane repo creation; no phase-2 issues.

Documentation/skills update capturing the workflow rules established during the Gitea-Tools completion cycle (v1.1.0). ## Problem The portable LLM workflow skill and runbooks do not yet document: 1. The mandatory end-of-task **Controller Handoff Summary** block (required for every task type: implementation, review, merge, triage, documentation, discussion-only, blocked planning). 2. Workflow rules proven during the completion cycle: - issue-first requirement (incl. "stop and ask when tracker home is unclear"; "no new repo/tracker without explicit approval") - discussion/RFC issue requirement (design debates on issues; discussion tasks create no branches/PRs) - review/merge requirement (identity + author verification, no self-review/self-merge, profile gates, pinned head SHA + expected changed files, independent validation, post-merge cleanup) - release/tag requirement (no tag ops unless instructed; tag only the verified final master merge commit; always report tag target) - branch/worktree requirement (one issue = one branch/worktree; issue number in branch name; no stale-branch reuse; no bundling) - blocked/owner-decision handling (stop cleanly; never bypass classifiers/gates/consent; give concrete owner options) ## Scope Docs/skill text only. Update `skills/llm-project-workflow/SKILL.md` (+ templates as needed) and `docs/llm-workflow-runbooks.md`. Include the required Controller Handoff Summary format verbatim and a short worked "blocked handoff" example. ## Acceptance criteria - Controller Handoff Summary section with the exact required format. - All six rule groups above documented. - Blocked-handoff example included. - No code behavior changed; no labels created; no tags touched; #100 (`profiles.json v2` RFC) not modified. ## Non-goals - No `profiles.json v2` implementation (#100 stays discussion). - No `mcp-control-plane` repo creation; no phase-2 issues.

sysadmin added the status:in-progress mcp documentation workflow labels 2026-07-02 17:14:00 -05:00

jcwalker3 referenced this issue from a commit

2026-07-02 17:17:05 -05:00

docs: require Controller Handoff Summary + codify LLM workflow rules (#101)

sysadmin referenced a pull request that will close this issue

2026-07-02 17:17:46 -05:00

docs: require Controller Handoff Summary + codify LLM workflow rules (#101) #102

sysadmin closed this issue

2026-07-02 17:25:27 -05:00

sysadmin removed the status:in-progress label 2026-07-02 17:25:27 -05:00

sysadmin referenced this issue from a commit

2026-07-02 17:25:28 -05:00

docs: require Controller Handoff Summary + codify LLM workflow rules (#101) (#102)

jcwalker3 referenced this issue from a commit

2026-07-02 17:59:27 -05:00

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

jcwalker3 commented

2026-07-02 18:08:40 -05:00

Workflow/skills improvement batch filed

Four follow-up issues from the workflow + skills review (session incident log):

#109 — Add dual-profile MCP launcher pattern to eliminate identity-relaunch bottleneck
#110 — Close Implements #N tracker gap in PR bodies and cleanup regex
#111 — Re-land release/version SOP with v1.1.0 audit lessons (predecessor: #68, closed without merge)
#112 — Add post-merge file-presence verification to merge-pr workflow

All four are open and unclaimed; no implementation started. Suggested priority: #109 > #110 > #111 > #112.

## Workflow/skills improvement batch filed Four follow-up issues from the workflow + skills review (session incident log): - #109 — Add dual-profile MCP launcher pattern to eliminate identity-relaunch bottleneck - #110 — Close `Implements #N` tracker gap in PR bodies and cleanup regex - #111 — Re-land release/version SOP with v1.1.0 audit lessons (predecessor: #68, closed without merge) - #112 — Add post-merge file-presence verification to merge-pr workflow All four are open and unclaimed; no implementation started. Suggested priority: #109 > #110 > #111 > #112.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#101