Agent-Skills.md

Agent Skills: Codex Review Backlog — post-merge (and open) Codex follow-ups

>-

UncategorizedID: arcblock/agent-skills/codex-review-backlog

Repository

arcblock/agent-skills
ArcBlockLicense: MIT
51

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ArcBlock/agent-skills/tree/HEAD/plugins/agentloop/skills/codex-review-backlog

Skill Files

Browse the full folder contents for codex-review-backlog.

Download Skill

Loading file tree…

plugins/agentloop/skills/codex-review-backlog/SKILL.md

Skill Metadata

Name
codex-review-backlog
Description
>-

Codex Review Backlog — post-merge (and open) Codex follow-ups

Why this exists. Codex is usually fast on open PRs (minutes: findings or a single 👍 = no opinions) — that pre-merge path is owned by pr-review (bot comments are review input) — never a per-push wait or a multi-hour stall. Codex can still post after merge or after that review. This skill is the complementary post-merge / late lag sweep: find comments that landed too late for the open-PR loop, triage them on current main, and open small fix PRs (never one mega-PR).

Repo profile first. Read .claude/repo-profile.md for repo_slug, default_branch, package_manager, test_runner, comment_language. Arc is the reference implementation.

Usage

/agentloop:codex-review-backlog              # last 24h merged PRs (default daily window)
/agentloop:codex-review-backlog --hours 12   # custom lookback
/agentloop:codex-review-backlog --days 7     # week scan (same as manual audits)
/agentloop:codex-review-backlog --open-too   # also scan open PRs for late Codex
/agentloop:codex-review-backlog --dry-run    # matrix only; no branch/PR/comment

Disposition tags

| Tag | Meaning | |---|---| | FIXED_LATER | Valid when Codex wrote; current main already addresses it | | IN_PR | Being fixed in an open follow-up PR this run opened/updated | | OPEN_EASY | Still valid; small scoped fix — implement this run if capacity | | OPEN_HARD | Still valid; needs design / multi-file / store CAS — track only | | REJECT | False positive or wrong layer (e.g. build script AFS purity) |

Step 0 — Sync main (do not skip)

git fetch origin <default_branch>
git reset --hard origin/<default_branch>
git log --oneline -1

Shared checkouts: stash first if dirty; never blind-wipe human WIP.

Step 1 — Enumerate merged PRs in the window

# example: last 24h (default daily)
SINCE=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)   # macOS; Linux: date -u -d '24 hours ago' …
gh pr list --state merged --limit 100 \
  --json number,title,mergedAt,url \
  --search "merged:>=$(date -u -v-1d +%Y-%m-%d)"   # broaden day then filter client-side

Filter client-side: mergedAt >= SINCE. With --open-too, also list open PRs.

Step 2 — Collect Codex inline comments

For each PR:

gh api repos/{owner}/{repo}/pulls/<n>/comments --paginate \
  --jq '.[] | select(.user.login=="chatgpt-codex-connector[bot]")'

Also pull review summary shells from pulls/<n>/reviews if useful. Parse P1/P2 from badge markup (badge/P1 / badge/P2).

Step 3 — Re-validate against current main (not the merge commit alone)

For every comment:

  1. Read cited path on current tree.
  2. Decide disposition (table above). Prefer FIXED_LATER when later commits already land the fix (common after a follow-up PR wave).
  3. Accept-path discipline: if the finding is about a check, ensure a fix still has an accept-path test.

Skip already-merged follow-up PRs that only restate addressed threads once code matches FIXED_LATER (comment on tracking issue, do not re-open).

Step 4 — Act (split PRs by domain)

  • OPEN_EASY: branch from main, TDD when possible, conventional commit, the changed package's tests, push, open PR linking source Codex PR + tracking issue. One domain per PR (e.g. feeds ≠ security-headers ≠ a11y).
  • OPEN_HARD: append to a tracking issue (or open one chore: Codex review backlog — <window>); do not block the daily run.
  • REJECT / FIXED_LATER: record in the tracking comment only.

Max scope per daily run (bounded): ≤3 OPEN_EASY findings or 2 fix PRs, whichever comes first; leave the rest for the next day. Prefer P1 over P2.

Step 5 — Tracking comment (idempotent)

Post one upsertable comment on a tracking issue (open or create chore: Codex review backlog — daily) with marker:

<!-- codex-backlog-report window=<ISO>.. <ISO> -->

Table: PR · finding · disposition · follow-up PR# if any.

Identity line via:

bash scripts/agent-identity.sh --header "" --skill codex-review-backlog

Step 6 — When to stop / quiet

Quiet if:

  • No Codex comments in the window, or
  • All dispositions are FIXED_LATER / REJECT / OPEN_HARD (none OPEN_EASY left).

Then the daily comment is a one-liner: Codex backlog quiet — window …, 0 OPEN_EASY.

Do not run a multi-hour (or even 45-minute) poll loop in the open-PR path. Pre-merge: bot comments present at review time are review input; silence is not a blocker. Post-merge lag and anything that arrives after you already advanced is this skill's job (daily cron or manual). Pair with pr-sweep / epic-conductor for pre-merge.

Relationship to other skills

| Skill | When | |---|---| | pr-review / pr-sweep | Open PRs before merge; bot comments are review input | | epic-conductor | Epic PRs: same; never stall waves on bot lag | | codex-review-backlog | After merge lag + optional open late comments | | land | Every fix PR you open: package tests + one review |

Unattended rules

Same as issue-sweep / pr-sweep: no AskUserQuestion / Workflow / EnterPlanMode. Escalate OPEN_HARD or ambiguous REJECT on the tracking issue and continue.

Key principles

  1. Validate on tip of main — comments are historical; code may have moved.
  2. Split PRs — never one mega-PR across unrelated domains.
  3. Bounded daily work — leave remainder for the next run.
  4. FIXED_LATER is success — do not re-implement merged fixes.
  5. P1 before P2; security/correctness before test polish.