github-issue-tracker: batch agents miss PR merge-readiness signals and trust stale tracker data

[ElliotDrel]

Summary

Two distinct failure modes discovered during a 2026-05-03 check-in run caused the skill to miss actionable PR problems (merge conflicts, CI failures, bot review requests). Both require changes to the skill's analysis agent prompts and result-file schema.

---

Failure Mode 1: Batch agents don't check PR merge-readiness fields

What happened

The batch analysis agents (Step 2b) were analyzing several tracked PRs:

• openclaw/openclaw#75343
• garrytan/gbrain#127
• punkpeye/fastmcp#265
• modelcontextprotocol/typescript-sdk#2003

None of them surfaced that:

• openclaw#75343 and gbrain#127 had merge conflicts (mergeStateStatus: DIRTY)
• fastmcp#265 had a CI failure (Prettier lint on test file)
• openclaw#75343 had a bot review requesting changes (not approved)

These were only caught when a separate dedicated PR-check agent was run afterward, explicitly fetching mergeStateStatus, CI rollup (statusCheckRollup), and reviewDecision.

Root cause

The result-file schema (references/result-file-schema.md) has no section for PR-specific health fields. The batch agent prompts don't instruct agents to fetch:

gh pr view NUMBER --repo OWNER/REPO --json state,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup

Agents only look at comments, state (open/closed), and duplicates — which is sufficient for issues but insufficient for PRs.

Fix

Option A (preferred): Add a PR-specific section to the result-file schema that is required when type: pr (or when the issue is detected as a PR from the raw JSON). Fields to include:

## PR Status (PRs only)
- mergeStateStatus: CLEAN | DIRTY | BLOCKED | UNKNOWN
- mergeable: MERGEABLE | CONFLICTING | UNKNOWN
- reviewDecision: APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | null
- ciStatus: passing | failing | pending | none
- ciFailures: [list of failing check names]

Option B: Add a parallel PR health pass (Step 2c) that runs after batch analysis, specifically for issues identified as PRs, fetching these fields via gh pr view --json.

Option C (minimal): Add the following to each batch agent prompt when the issue is a PR:

"If this issue is a PR, also fetch mergeStateStatus, reviewDecision, and statusCheckRollup from the PR API and include them in the Status Summary and Next Steps sections."

---

Failure Mode 2: Agents trust stale tracker data instead of re-verifying from the API

What happened

The tracker entry for openclaw/openclaw#75343 contained:

"Approved by @clawsweeper with one blocking item"

This was written in a previous session. However, @clawsweeper is a bot, and its actual review state was COMMENTED with "needs changes before merge" — not APPROVED. The batch analysis agent for this run read the tracker's existing entry and carried the incorrect "approved" status forward without verifying it against the live API data.

The result: the tracker continued to say the PR was approved and ready to merge, when in fact it had outstanding bot review requests that needed addressing.

Root cause

The batch agent prompt says:

"Fill in missing data: For each issue, compare what the tracker has against what the API returned. If the tracker entry is missing factual fields... the agent should fill them in from the API data."

But the key word is missing — agents fill in gaps, they don't overwrite existing tracker data with fresher API data. So a wrong "approved" status baked into the tracker stays wrong indefinitely.

Fix

Update the batch agent prompt to explicitly re-verify certain high-churn fields against the API on every run, regardless of what the tracker says:

Fields that must always be re-fetched and overwritten (never trusted from tracker):

• PR merge state (mergeStateStatus, mergeable)
• Review decision (reviewDecision)
• CI status (statusCheckRollup)
• Issue/PR open/closed state
• Label list
• Comment count

Fields that can be trusted from tracker (low churn, expensive to re-derive):

• Root cause analysis
• Workarounds
• Duplicate relationships
• Technical background

The distinction: API-observable facts should always be refreshed. Human analysis (workarounds, root cause, context) can be preserved.

---

Failure Mode 3 (minor): "approved by @clawsweeper" misread persisted across sessions

What happened

The original misread ("approved" vs "changes requested") came from a batch agent in a prior run that misinterpreted the bot's review state. Because the tracker was then written with this incorrect data, every subsequent run that trusted the tracker perpetuated the error.

Fix

In the batch agent prompt, add explicit guidance:

"When reading review state from the API: COMMENTED is not an approval. Only APPROVED state counts as an approval. Bot reviews ([bot] suffix on reviewer login) should be noted separately from human reviews — a bot APPROVED does not satisfy a branch protection rule requiring human review."

---

Acceptance Criteria

• references/result-file-schema.md includes a PR-specific section with merge state, review decision, and CI status fields
• Batch agent prompts instruct agents to always re-fetch API-observable PR health fields (not trust tracker)
• Batch agent prompts clarify the distinction between bot reviews and human reviews
• A future run on the same PRs correctly surfaces merge conflicts, CI failures, and bot review requests in the result files and compiled report

Affected Files

• references/result-file-schema.md
• bin/tracker-tools.cjs (if compile-report needs to surface PR health)
• Skill prompt in the main skill file (batch agent prompt section in Step 2b)