From d54377b111d300765e62c25e663ef4d50b5d4088 Mon Sep 17 00:00:00 2001 From: glennfaison Date: Sun, 25 Oct 2026 23:25:03 +0100 Subject: [PATCH] docs: require runner name on every agent comment Debugging triage and handoff comments is hard when the runner is not identified. Update handoff.md so every outcome, handoff and escalation comment records the runner. Log templates already require it; restate the rule for clarity. Closes #36. --- .../agent-workflow-protocol/references/handoff.md | 11 ++++++----- skills/meta/agent-workflow-protocol/references/log.md | 3 ++- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/skills/meta/agent-workflow-protocol/references/handoff.md b/skills/meta/agent-workflow-protocol/references/handoff.md index 8d2f88a..0cb8dbb 100644 --- a/skills/meta/agent-workflow-protocol/references/handoff.md +++ b/skills/meta/agent-workflow-protocol/references/handoff.md @@ -5,6 +5,7 @@ Elsewhere a handoff is often a document that compacts a conversation for another - Write for a fresh agent with none of your context. Reference artifacts (PR, issue, commit, check run) by link instead of copying them, and redact secrets and personal data. - Open with one sentence that says where things stand, then the sections. Keep it short enough to skim: a long handoff hides the one line a human needs. - Compose it in a file in the OS temp directory, then post it with `gh pr comment N --body-file FILE`. **Never write it into the repository.** +- **Record the runner.** Every comment an agent leaves (outcome, handoff, triage notes, escalation, failure note) must include the runner name near the top of the body, for example `**Runner:** grok` or `Runner: $runner`. Use the `runner` input (default `unknown`). Without it, debugging which automation produced the comment is guesswork. - End the comment with the marker the step requires. The marker is the last line: - `` - `` @@ -15,11 +16,11 @@ Elsewhere a handoff is often a document that compacts a conversation for another | Author | Comment | Required content | |---|---|---| -| Shepherding | the "ready" handoff on a PR | **Changes** made, **Decisions** taken and why, **Risks**, **Verification** actually run (commands and results, and a link to the green check run), **Reviewer focus** (where to look hardest), **Not done** (anything the issue asked for that this PR leaves out, and why) | -| Reviewing, not merged | the "review" handoff on a PR | **Verdict**, **Findings**: each with what is wrong, why, and whether it is fixed (with the commit) or still open; **What remains**; **Verification** you ran; **Round** (`review_rounds N` of `max_review_rounds`) | -| Reviewing, merged | the "merged" note on a PR, posted right after the merge | **Verdict** from `merge-safety` (compatibility, reversibility, GitHub readiness) and the outcome of `code-review`; **Verification** you ran; the merge commit and `merge_method`. It keeps the reason for an unattended merge with the PR | -| Any step that escalates | the escalation comment | see `escalate.md` | +| Shepherding | the "ready" handoff on a PR | **Runner**, **Changes** made, **Decisions** taken and why, **Risks**, **Verification** actually run (commands and results, and a link to the green check run), **Reviewer focus** (where to look hardest), **Not done** (anything the issue asked for that this PR leaves out, and why) | +| Reviewing, not merged | the "review" handoff on a PR | **Runner**, **Verdict**, **Findings**: each with what is wrong, why, and whether it is fixed (with the commit) or still open; **What remains**; **Verification** you ran; **Round** (`review_rounds N` of `max_review_rounds`) | +| Reviewing, merged | the "merged" note on a PR, posted right after the merge | **Runner**, **Verdict** from `merge-safety` (compatibility, reversibility, GitHub readiness) and the outcome of `code-review`; **Verification** you ran; the merge commit and `merge_method`. It keeps the reason for an unattended merge with the PR | +| Any step that escalates | the escalation comment | see `escalate.md` (include **Runner**) | ## Issues -For an issue, the comment `unattended-triage` writes is the handoff: an **Agent Brief** for `ready-for-agent`, the same structure plus why it cannot be delegated for `ready-for-human`, or **Triage Notes** for `needs-info`. A conversation summary on top would only duplicate it. +For an issue, the comment `unattended-triage` writes is the handoff: an **Agent Brief** for `ready-for-agent`, the same structure plus why it cannot be delegated for `ready-for-human`, or **Triage Notes** for `needs-info`. A conversation summary on top would only duplicate it. Every such comment must still include `**Runner:** $runner`. diff --git a/skills/meta/agent-workflow-protocol/references/log.md b/skills/meta/agent-workflow-protocol/references/log.md index 56b54db..fb9b2d4 100644 --- a/skills/meta/agent-workflow-protocol/references/log.md +++ b/skills/meta/agent-workflow-protocol/references/log.md @@ -51,7 +51,7 @@ problems_count: 1 |---|---|---| | `step` | yes | Exploring, Triaging, Implementing, Shepherding, Reviewing | | `run` | yes | `RUN_ID` | -| `runner` | yes | Runner name | +| `runner` | yes | Runner name (from the `runner` input; default `unknown`). Required so log and issue comments can be attributed | | `at` | yes | When the entry was written, UTC ISO-8601 (`log_run` adds it if missing) | | `outcome` | yes | Short summary string (same facts as **Outcome:**) | | `problems_count` | yes | Number of tagged problem lines (0 if none) | @@ -79,6 +79,7 @@ Rules: - **One entry per run and step.** `log_run` skips an entry whose `run` and `step` are already on the log issue, so a retry is safe. A runner with no shell checks the issue's comments (`hasLogEntry`) first. - Write real line breaks, never the two characters backslash and `n`. `log_run` repairs an entry written that way, but do not rely on it. - Write the entry to a temp file, then run `log_run FILE` (shell) or post the same body with GitHub tools (no-shell). Use `formatLogComment` from `scripts/helpers.mjs` so the header and field order stay identical across runners. +- The prose header line must include `**Runner:**` with the same value as the YAML `runner` key. Agent comments on issues and PRs (outside the log) follow the same rule; see `references/handoff.md`. ## Reading