Triage agent: PR ownership signaling + iteration loop on review comments

[bokelley]

Background

Triage opened #3110 (closing #3106 — list_accounts handler) without me asking. CI failed on the storyboard idempotency_key lint, and I posted a comprehensive review comment with three concrete blockers (missing idempotency_key, cursor-codec duplication with #3109, bootstrap primitive drift from the seeded-storyboard precedent).

It's unclear whether triage:

1. Reads PR comments and iterates.
2. Watches its own PRs for CI failures and auto-iterates.
3. Treats its first push as final and waits for human takeover.

Asks

1. Discoverability — how do humans know a PR is "owned" by triage?

The branch name pattern `claude/issue-NNNN-*` is one signal but not advertised. Add one of:

• A label (e.g. `claude-triaged`, `triage-owned`) auto-applied on creation.
• A line in the PR body identifying the owning agent and its iteration policy ("This PR is managed by triage. Comments tagged `@triage` will be picked up on the next pass.").
• A bot identity that's distinct from the human reviewer's identity (right now PRs appear from `@bokelley`'s account).

Issue `#3106` already carries the `claude-triaged` label — extend the same to PRs.

2. Iteration loop on review comments

If triage doesn't currently iterate on PR comments, document that in the PR body so reviewers know whether to (a) wait, (b) push fixes themselves, or (c) ping a specific channel. If it does iterate, document the trigger (slash command, mention, label change?) and the latency expectation.

If triage DOES auto-fix in response to CI failures, confirm and document. Right now I'd assume the bot pushes once and stops, which means human reviewers need to either fix or send back manually.

3. Pre-flight check parity with what reviewers run

The triage internal review on #3110 claimed code-reviewer + ad-tech-protocol-expert approval but missed the storyboard `idempotency_key` lint, which is a build-time check at `scripts/build-compliance.cjs:251`. Either:

• Triage's prep checklist should run `node scripts/build-compliance.cjs` before opening the PR (this would have caught the lint locally).
• Or triage should wait for CI to go green before declaring `ready for review` (currently shipped as DRAFT, which is correct, but still surprised the human reviewer who saw "approved" in the body).

Scope

This issue is about agent ergonomics, not blocking any PR. The pagination conformance series (#3095, #3100, #3109, #3110, #3111, #3112) keeps moving — I'll just fix #3110 directly this round. Filing this so the next round either (a) is clearer about who owns what, or (b) automates the iteration loop so humans only step in when actually needed.

Pointers

• Existing claude-triaged label on issues: `gh issue list --label claude-triaged`
• Memory entry: project_claude_routines (5 remote triggers, 2026-04-23)
• The reviewer's deep dive on feat(training-agent): add list_accounts handler with pagination conformance #3110: feat(training-agent): add list_accounts handler with pagination conformance #3110 (comment)

[bokelley]

Triage

Classification: Feature request — agent ergonomics
Bucket: infra / agents
Status: ready-for-human

What the experts said:

• prompt-engineer: All three are blockers. Asks 1+2 are PR-body template edits (~15 min each); Ask 3 needs a conditional pre-flight step explicitly covering compliance-suite diffs.
• dx-expert: Ask 2 is the primary pain — no documented iteration policy leaves reviewers unable to decide whether to wait or act. Ask 3 creates false confidence: "pre-PR review: approved" next to red CI is a trust-eroding signal.

My take: All three fixes live in .agents/routines/triage-prompt.md (infra/agents bucket — self-modification is high-risk, human author required). One wrinkle on Ask 3: npm run build already chains build:compliance, so the fallback path should have caught the #3110 lint — the specific miss there warrants a look before or alongside the prompt fix.

@bokelley, your call on Ask 2: document or automate?

Option A — Document current behavior (add to PR body template, ships today):

+> **Triage-opened PR.** Triage does not monitor review comments on this PR.
+> Push fixup commits directly, or re-trigger via `/triage` on the source issue.

Option B — Build a PR review-comment loop (new event handler):

# pull_request_review_comment.created on claude/* branch
# → re-run bucket experts on flagged diff chunk → push fixup or comment explaining why not

This is a multi-day feature. Option A is the immediate unblock; Option B is the eventual goal.

Asks 1 and 3 have unambiguous single-path fixes and can ship alongside either choice above.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_015u29xzX54bRNSJUrbLW3SL

---

Generated by Claude Code

[bokelley]

Decision: Option A first, B as 4.x roadmap

Ship Option A (PR-body documentation) immediately as the unblock. The reviewers I spawned on triage's #3110, #3114, #3120, #3122 didn't know whether to wait or push fixes — I ended up pushing fixes directly, which works but wastes both my time and the bot's. A one-line PR-body callout ("triage does not iterate on review comments — push fixup commits or re-trigger via slash command") fixes the reviewer-decision problem today.

On Ask 3 (the build-compliance gap): my session uncovered five separate cases where triage's pre-PR review approved code that build-compliance immediately rejected:

• feat(training-agent): add list_accounts handler with pagination conformance #3110 — `idempotency_key` lint (sync_accounts setup phase)
• feat(compliance): add seed_creative_format + list_creative_formats pagination #3114 — `creative_formats` not registered in `lint-storyboard-contradictions` FIXTURE_CATEGORY_PRIMARY_ID
• feat(training-agent): add list_accounts handler with pagination conformance #3110, feat(compliance): add seed_creative_format + list_creative_formats pagination #3114, feat(compliance): pagination integrity for get_media_buys #3122 — doc-parity rows missing in `docs/building/conformance.mdx` and `docs/building/compliance-catalog.mdx`
• feat(compliance): pagination integrity for get_media_buys #3122 — TypeScript cast through unknown for the seeded-format type
• feat(training-agent): add list_accounts handler with pagination conformance #3110, feat(compliance): add seed_creative_format + list_creative_formats pagination #3114, feat(compliance): pagination integrity for get_media_buys #3122 — cursor codec duplication (three private codecs) instead of using the shared `encodeOffsetCursor` shipped in feat(compliance): pagination cursor↔has_more invariant lint and storyboard #3095/feat(training-agent): add list_accounts handler with pagination conformance #3110

Every one of those is something `node scripts/build-compliance.cjs` plus `node scripts/lint-pagination-invariant.cjs` plus `npm run typecheck` would have caught locally. So Ask 3 should be simple: make triage run `npm run build && npm run typecheck` before declaring approval. That `build` invocation chains all of build-schemas, build-compliance, and build-protocol-tarball, which transitively runs every storyboard lint plus the doc-parity check. No new conditional logic needed; it's the same command CI runs. If the local build fails, the bot's review verdict is wrong and it should iterate before opening the PR.

On Option B (review-comment loop): real but secondary. The PR-body docs (Option A) covers the reviewer-decision case. The auto-iteration loop is nice-to-have once the immediate workflow stops blocking. Tier it in 4.x.

On Ask 1 (PR ownership signaling): label all triage PRs `claude-triaged` (mirrors the issue label). The branch-name pattern `claude/issue-NNNN-*` is already a strong signal but a label is searchable in PR list views.

Three concrete changes, all in `.agents/routines/triage-prompt.md`:

1. Add label `claude-triaged` on PR creation.
2. Append PR body block:
   ```

   Triage-managed PR. This bot does not currently iterate on review comments.
   To unblock: push fixup commits directly (`gh pr checkout ` → fix → push), or
   re-trigger triage via `/triage` on the source issue.
   ```

3. Pre-flight checklist: require `npm run build && npm run typecheck` to exit 0 before declaring "approved" in the internal review block.

Want me to push that prompt change to `.agents/routines/triage-prompt.md` directly, or would you rather do it (high-risk self-modification per your earlier note)?