AGENTS: add Tracking Issues And Handoffs hygiene policy

[justin808]

What

Adds a Tracking Issues And Handoffs policy section to AGENTS.md (the canonical agent policy) plus a pointer in the pr-batch skill.

Why

The agent-batch workflow accreted ~10 standalone handoff / audit / process-snapshot issues (closed in a sweep alongside this change) because "open a tracker" had no matching "close it" step, and transient coordination state was being filed as durable issues. This codifies how to prevent the re-accumulation.

The policy

• No standalone handoff or point-in-time audit issues. Handoffs → a comment on the parent tracking issue (or the agent-coordination repo if one is in use); audits → appended to the release audit ledger (Release audit ledger: track audit ranges, heads, artifacts, and follow-up status #4010) in place.
• One durable ledger per recurring concern, updated in place (release audits → Release audit ledger: track audit ranges, heads, artifacts, and follow-up status #4010; coordination state → Tracking: cross-agent batch coordination layer (heartbeats, leases, status) for multi-machine batch engineering #3974) — no sibling issue each cycle.
• Closure follows the work, not the opener. A tracking issue closes when its underlying PR/work lands, by whoever finishes it — not by whoever opened it. WIP outlives sessions (lost chat, disconnect); the heartbeat detects abandonment and an unfinished PR is the real signal.
• 30-day test before opening any meta issue; sweep superseded process issues on sight.

Scope

Docs-only (AGENTS.md + skill); no runtime/CI impact. AGENTS.md is not a check-llms-full input, so no llms-full regen. Prettier clean.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes to agent policy and skills; no runtime, CI, or application code paths affected.

Overview
Adds canonical Tracking Issues And Handoffs rules to AGENTS.md so transient agent work (session handoffs, point-in-time audits, process snapshots) stops accumulating as standalone GitHub issues.

Policy highlights: handoffs belong in parent-tracker comments, the coordination repo, or the batch PR—not new Handoff: ... issues; audit reports append to the standing release audit ledger in place, not Post-rc.N audit issues; one durable ledger per recurring concern; close trackers when the underlying work lands (any finisher, not only the opener); apply a 30-day test before meta issues; sweep obsolete process issues after consolidating live findings.

Wiring: identical callouts in .agents/workflows/pr-processing.md and .agents/skills/pr-batch/SKILL.md under Batch Handoff Format; post-merge-audit narrows parent-issue creation to grouping real child fix issues and explicitly forbids audit-snapshot tracker issues.

^{Reviewed by Cursor Bugbot for commit 2872deb. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added guidance section “Tracking Issues And Handoffs” to standardize how transient handoffs and audits are recorded.
  • Updated batch “Process Gap / handoff” instructions to require handoffs be logged as comments on the relevant parent (or an appropriate fallback) and to avoid standalone “Handoff: …” or “Post-rc.N audit” issues.
  • Refined post-merge audit instructions to append reports to the standing release audit ledger and create parent issues only when bundling multiple related fixes.

[coderabbitai]

Walkthrough

Three documentation files are updated to codify agent handoff and audit tracking rules across the agent ecosystem. AGENTS.md gains a new "Tracking Issues And Handoffs" section with policies. .agents/skills/pr-batch/SKILL.md tightens "Batch Handoff Format" guidance. .agents/workflows/pr-processing.md adds explicit workflow rules. .agents/skills/post-merge-audit/SKILL.md refines parent issue creation constraints.

Changes

Handoff and Audit Issue-Tracking Policy

Layer / File(s)

Summary

Policy documentation AGENTS.md, .agents/skills/pr-batch/SKILL.md, .agents/workflows/pr-processing.md, .agents/skills/post-merge-audit/SKILL.md

AGENTS.md adds a "Tracking Issues And Handoffs" section defining rules: no new issues for session handoffs/audits, record handoffs as comments on parent issues, append audits to the release ledger, apply a 30-day usefulness check, and close superseded issues. SKILL.md's "Batch Handoff Format" adds matching procedural instructions prohibiting standalone handoff/audit issues and directing closure of superseded process issues on sight. pr-processing.md adds a boxed workflow rule clarifying handoffs must be recorded as comments (not standalone issues) and specifying where to record them. post-merge-audit/SKILL.md refines when to create parent issues, restricting them to bundling two or more related child fix issues from the same audit and prohibiting standalone audit-snapshot trackers.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• shakacode/react_on_rails#3691: Updates handoff/audit tracking rules in .agents/workflows/pr-processing.md with overlapping policy on when and how to record or close issue-tracker items for agent handoffs and deferred work.
• shakacode/react_on_rails#3729: Introduces batch-launch and audit guidance updates to .agents/skills/pr-batch/SKILL.md and .agents/workflows/pr-processing.md, sharing the same handoff/audit recording standardization.
• shakacode/react_on_rails#3824: Directly reworks the .agents/skills/pr-batch/SKILL.md "Batch Handoff Format" section and .agents/workflows/pr-processing.md closeout guidance with overlapping handoff-recording and process-issue-closure rules.

Suggested labels

enhancement, codex

Suggested reviewers

• alexeyr-ci2

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a 'Tracking Issues And Handoffs' hygiene policy to the agents documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/tracking-issue-hygiene

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Review: AGENTS: add Tracking Issues And Handoffs hygiene policy

Summary: Docs-only PR that adds a "Tracking Issues And Handoffs" policy section to AGENTS.md and a short callout in the pr-batch skill. Addresses a real operational problem (transient coordination issues accumulating in the tracker) with clear, actionable rules.

---

What works well

• Structure is clear. Each rule is bold-headed with an explanation and a concrete alternative — easy for an agent to parse at policy-read time.
• Skill callout follows the established pattern. Routing to AGENTS.md as canonical and keeping the skill as a concise pointer is consistent with how the "Maintainer Attention Contract" section is handled in the same file.
• Placement is logical. The new section sits between "Maintainer Attention Contract" and "Release Mode And Auto-Merge Coordination", which is the right neighbourhood thematically.
• The 30-day test is a good concrete heuristic for the ambiguous middle-ground case.

---

Issues to address

1. Hard-coded issue numbers are brittle

#4010 (release audit ledger) and #3974 (coordination layer) are referenced as durable, always-open targets. If either is ever closed, replaced, or superseded, agents following this policy will route to a dead or stale issue — exactly the failure mode the policy is trying to prevent.

Suggest qualifying them or adding a discovery method:

append an audit to the standing release audit ledger (search for the open issue with label `release-audit-ledger`, currently #4010) in place

Or at minimum add a note like "check for a superseding ledger before appending".

2. "Sweep on sight" may be too aggressive in the SKILL.md callout

The AGENTS.md text is appropriately hedged: "When you encounter a resolved or superseded handoff/audit/process-snapshot issue, close it." The SKILL.md callout shortens this to "Close superseded process issues on sight" — which drops the "resolved or superseded" qualifier and sounds like an unconditional sweep instruction. An agent acting on the skill callout without reading the full policy could close issues that are still active but look like handoffs. Tightening the callout language to match AGENTS.md would reduce that risk.

3. No guidance on what to do when the parent tracking issue doesn't exist

The policy says "record a handoff as a comment on the relevant parent tracking issue" — but what if the batch has no parent umbrella issue (a standalone feature, a one-off PR)? A short fallback sentence ("if no parent exists, use the agent-coordination repo or omit the handoff") would close that gap.

---

Minor

• The sentence "WIP can outlive a session (lost chat, unanswered question, disconnect). The heartbeat detects abandonment" references a "heartbeat" mechanism without defining or linking it. A parenthetical like "(see .agents/workflows/pr-processing.md)" would make this self-contained for readers encountering this section in isolation.
• The SKILL.md blockquote does not mention #4010 by number. That is the right call (keeps the skill abstract), but it does mean an agent reading only the skill never learns where the ledger actually lives. Acceptable tradeoff given the canonical source is one hop away, but worth a conscious decision.

---

Overall this is a solid process improvement for a docs-only change. The hard-coded issue numbers and the "sweep on sight" wording are the two things worth fixing before merge.

[greptile-apps]

Greptile Summary

This is a docs-only change that codifies a "Tracking Issues And Handoffs" hygiene policy in AGENTS.md and adds a matching callout in the pr-batch skill to prevent future accumulation of transient session-handoff and per-cycle audit issues.

• AGENTS.md: Adds five policy bullets covering: no standalone handoff/audit issues, one durable ledger per concern (updated in place), closure ownership follows the finisher not the opener, a 30-day test before opening any meta issue, and a "sweep on sight" rule for resolved process-snapshot issues.
• .agents/skills/pr-batch/SKILL.md: Inserts a blockquote callout before the Batch Handoff Format section summarising the new policy and cross-linking to AGENTS.md as the canonical source.

Confidence Score: 4/5

Docs-only change with no runtime, CI, or library impact; safe to merge.

Both files are agent-policy documentation with no executable code. The single note worth flagging is that the new policy hard-codes issue numbers #4010 and #3974 as permanent ledgers without marking them immune to the same "sweep on sight" rule introduced in the same section — a future agent could misclassify one as a superseded process issue. Otherwise the wording is clear and internally consistent.

AGENTS.md — specifically the bullet that references #4010 and #3974 by number only, without a guard against those issues being closed during a hygiene sweep.

Important Files Changed

Filename	Overview
AGENTS.md	Adds a new "Tracking Issues And Handoffs" section (5 policy bullets) between the Confidence Notes block and Release Mode section; docs-only, no code impact, but hard-codes two specific issue numbers (#4010 and #3974) as the canonical ledgers.
.agents/skills/pr-batch/SKILL.md	Inserts a blockquote callout before the Batch Handoff Format section, summarising the new AGENTS.md policy and cross-linking to it; no logic changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent wants to record state / open issue] --> B{Is it a session handoff\nor point-in-time audit?}
    B -- Yes --> C[Add comment to parent\ntracking issue or agent-\ncoordination repo]
    B -- No --> D{Is it a recurring\nprocess concern?}
    D -- Yes --> E[Append to standing\ndurable ledger\n#4010 / #3974]
    D -- No --> F{30-day test:\nwill it matter\nin 30 days?}
    F -- No --> G[Comment or ledger entry,\nnot a new issue]
    F -- Yes --> H[Open a real tracking\nor backlog issue]
    H --> I{Closure: who closes it?}
    I --> J[Whoever finishes the\nunderlying work — not\nnecessarily the opener]
    K[Agent encounters open\nhandoff/audit/snapshot issue] --> L[Close it; consolidate\nlive findings into ledger\nor real backlog issue]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Agent wants to record state / open issue] --> B{Is it a session handoff\nor point-in-time audit?}
    B -- Yes --> C[Add comment to parent\ntracking issue or agent-\ncoordination repo]
    B -- No --> D{Is it a recurring\nprocess concern?}
    D -- Yes --> E[Append to standing\ndurable ledger\n#4010 / #3974]
    D -- No --> F{30-day test:\nwill it matter\nin 30 days?}
    F -- No --> G[Comment or ledger entry,\nnot a new issue]
    F -- Yes --> H[Open a real tracking\nor backlog issue]
    H --> I{Closure: who closes it?}
    I --> J[Whoever finishes the\nunderlying work — not\nnecessarily the opener]
    K[Agent encounters open\nhandoff/audit/snapshot issue] --> L[Close it; consolidate\nlive findings into ledger\nor real backlog issue]

Loading

_{Reviews (1): Last reviewed commit: "AGENTS: add Tracking Issues And Handoffs..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 73df724737

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a7b6d3866

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Code Review: AGENTS — Tracking Issues And Handoffs Policy

Summary: Documentation-only PR. Adds a ## Tracking Issues And Handoffs section to AGENTS.md and matching reminder blockquotes to the Batch Handoff sections of .agents/skills/pr-batch/SKILL.md and .agents/workflows/pr-processing.md. No runtime or CI impact.

---

What works well

• The five sub-rules (no standalone handoff issues, one ledger per concern, closure follows work, 30-day test, sweep on sight) are clear and actionable.
• The self-aware caveat on issue numbers ("treat any such number as a movable pointer") acknowledges their inherent staleness — a nice guard against the same disease the policy prevents.
• Placement between ## Maintainer Attention Contract and ## Release Mode And Auto-Merge Coordination is logical.

---

Issues

1. The two new blockquotes are meaningfully inconsistent

SKILL.md blockquote covers audits but omits the "no-parent-umbrella → PR comment" path:

"record a handoff as a comment on the relevant parent tracking issue … and append audits to the release audit ledger in place"

pr-processing.md blockquote covers the no-umbrella path but omits the audit ledger:

"record the handoff … or in the batch's own PR comment/description when there is no parent umbrella"

An agent reading only one file gets an incomplete picture of the rule. They should be consistent summaries of the same policy.

2. Existing sync comment warns against duplication in SKILL.md

pr-processing.md already has a comment:

<!-- Canonical batch handoff copy. .agents/skills/pr-batch/SKILL.md should point
     here instead of duplicating this section. -->

And SKILL.md has its own comment:

<!-- Keep this handoff summary in sync with .agents/workflows/pr-processing.md -->

These comments signal the intent to keep SKILL.md as a pointer rather than a copy. The new blockquote in SKILL.md adds more content to keep in sync rather than reducing duplication. Consider whether the SKILL.md blockquote should instead just say "see pr-processing.md → Batch Handoff Format" and rely on the canonical copy there.

3. Minor wording inconsistency between blockquotes

• SKILL.md uses `Handoff: ...` / `Post-rc.N audit` (slash separator)
• pr-processing.md uses `Handoff: ...` or `Post-rc.N audit` ("or")

Small, but since agents may key on these as patterns, consistency is worth it.

---

Suggestions

• Option A (preferred): Make the SKILL.md blockquote a single-sentence pointer to pr-processing.md rather than another partial copy of the rule. This is what the existing Canonical batch handoff copy comment recommends.
• Option B: Unify the two blockquotes so they are word-for-word identical, covering all three paths (parent tracker comment, agent-coordination repo, standalone PR comment) and the audit ledger.

---

Verdict

The policy itself is well-reasoned and needed. The content inconsistency between the two reminder blockquotes is the main thing worth fixing before merge — an agent reading only the SKILL.md path will not learn about the "no parent umbrella → PR comment" option, which is likely the common case in a standalone batch.

[claude]

Code Review: Tracking Issues And Handoffs Policy

Overall: This is a well-reasoned docs-only PR that addresses a real problem — transient agent coordination artifacts accumulating as durable GitHub issues. The policy is clear, actionable, and internally consistent across the three modified files. No runtime or CI impact.

---

What works well

• The movable pointer annotation on issue numbers Release audit ledger: track audit ranges, heads, artifacts, and follow-up status #4010 and Tracking: cross-agent batch coordination layer (heartbeats, leases, status) for multi-machine batch engineering #3974 is appropriately self-aware; it guards against exactly the staleness problem the policy is designed to prevent.
• The "Sweep on sight" rule has the right safeguard built in: consolidate first, then close — preventing silent data loss when closing obsolete trackers.
• The 30-day test is a useful concrete heuristic that should prevent most over-tracking impulses.
• Cross-file consistency between the two callout blocks (pr-batch and pr-processing) is deliberately contextual, not accidental drift — the "below" in pr-processing.md is appropriately context-specific.

---

Issues to address

1. Silent behavior change in post-merge-audit/SKILL.md (worth confirming intent)

The old text allowed a parent issue in two cases:

when there are two or more related child issues or when the audit spans a release-candidate readiness decision

The new text drops the RC-readiness case entirely. Based on the new policy (RC audits → standing ledger, not new issues) this appears intentional, but it is a behavioral narrowing, not just a documentation addition. The PR description does not call it out explicitly. Please confirm this is deliberate and consider a one-sentence note in the PR body.

2. Sync comment placement in .agents/skills/pr-batch/SKILL.md

The new callout blockquote is inserted before the sync comment:

## Batch Handoff Format

> **A handoff is a comment, not a new issue.** ...   ← new, above sync comment

<!-- Keep this handoff summary in sync with .agents/workflows/pr-processing.md ... -->

Since both pr-batch/SKILL.md and pr-processing.md now carry the callout, future maintainers syncing per the comment might miss that the callout is also duplicated and needs updating. Consider either (a) moving the sync comment above the callout, or (b) adding a brief note that the callout is also part of what must be kept in sync.

---

Minor observations

• The "Sweep on sight" bullet embeds a non-obvious ordering requirement (consolidate before closing) in a single sentence with an em-dash. A numbered micro-list would make the sequencing unambiguous for agents that parse instructions linearly.
• The callout wording in the two files is intentionally slightly different ("record a handoff" vs. "record the handoff below") — this is correct and appropriate given the context of each file.

---

Summary

Approve with the RC-readiness behavior change confirmed. The policy is well-scoped, the wording is clear, and the meta-advice about treating ledger issue numbers as movable pointers is the right defensive stance.

[coderabbitai]

🧹 Nitpick comments (1)

.agents/skills/pr-batch/SKILL.md (1)

142-142: 💤 Low value

Migrate hidden maintenance instructions from HTML comments to visible documentation.

Line 142 contains a synchronization directive in a hidden HTML comment: <!-- Keep this /simplify block in sync with ... -->. While benign, embedding maintenance notes in invisible comments (even with good intent) establishes a pattern that can obscure future malicious injection.

Move this note to a visible inline comment (e.g., as a leading // NOTE: Keep in sync... block in a code snippet or a dedicated visible section) or to a separate MAINTENANCE.md changelog.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/pr-batch/SKILL.md at line 142, The HTML comment on line 142
containing the synchronization directive for the /simplify block is hidden and
should be made visible to prevent maintenance notes from being obscured. Remove
the hidden HTML comment that reads "Keep this /simplify block in sync with..."
and replace it with a visible approach by either adding a visible NOTE section
at the beginning of the file documenting which files need to stay synchronized,
or creating a dedicated MAINTENANCE.md file that lists these synchronization
requirements. Ensure the synchronization information remains clear and
discoverable but is no longer hidden in an HTML comment.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.agents/skills/pr-batch/SKILL.md:
- Line 142: The HTML comment on line 142 containing the synchronization
directive for the /simplify block is hidden and should be made visible to
prevent maintenance notes from being obscured. Remove the hidden HTML comment
that reads "Keep this /simplify block in sync with..." and replace it with a
visible approach by either adding a visible NOTE section at the beginning of the
file documenting which files need to stay synchronized, or creating a dedicated
MAINTENANCE.md file that lists these synchronization requirements. Ensure the
synchronization information remains clear and discoverable but is no longer
hidden in an HTML comment.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c3f6ff46-e34b-436b-9e16-41eb7548be5d

📥 Commits

Reviewing files that changed from the base of the PR and between 3a7b6d3 and 2872deb.

📒 Files selected for processing (3)

• .agents/skills/post-merge-audit/SKILL.md
• .agents/skills/pr-batch/SKILL.md
• .agents/workflows/pr-processing.md

✅ Files skipped from review due to trivial changes (1)

• .agents/workflows/pr-processing.md