resolve-follow-ups

Files (6)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• test-resolve-follow-ups.sh · evals/
• trigger-evals.json · evals/
• resolve-follow-ups.sh · scripts/

SKILL.md (first lines)

# Resolve Follow-ups

Turn a bounded set of recorded follow-ups into independently verified pull
requests. Preserve every item that cannot pass the reproduction and authority
gates.

This skill requires `project-knowledge`. Before doing any work, confirm it is
installed. When it is missing, stop and report it with its install command,
`npx skills@latest add toy-crane/skills --skill project-knowledge`, using the
project's package manager runner where it pins one.

## Choose the execution mode

- Treat an invocation without a specific follow-up path as a **sweep**. Select
  workers from the repository backlog and return one combined report.
- Treat an invocation carrying one follow-up path, base SHA, attempt identity,
  owner token, branch, and worktree as a **worker**. Resolve only that item and
  return one terminal outcome.
- Keep Schedule or Routine frequency outside this skill. One invocation is one
  sweep, never one recurring schedule per follow-up.

## Sweep the backlog

Resolve this skill's directory, then use
`scripts/resolve-follow-ups.sh` from that directory. The script is the
deterministic boundary for ordering, fresh-base identity, worktree creation,
attempt suppression, and cleanup.

1. Run `list --repo <root>` to fetch the remote default branch and obtain every
   valid candidate in discovery order plus every `invalid-follow-up`. Report
   invalid files without filling in their missing evidence. Do not enumerate a
   possibly stale coordinator checkout.
2. For each candidate in order, run
   `identity --repo <root> --follow-up <path>`. Continue until three eligible
   workers have been started or the ordered backlog is exhausted.
   `eligible` is only a snapshot, not a reservation. The platform adapter must
   win the attempt's atomic `claim` or `prepare` result before launching a
   worker; `skipped-unchanged ... claimed <owner> [<worktree> <branch>]` means
   another sweep already owns the unchanged follow-up content. That active
   ownership and a recorded pull request survive unrelated default-branch
   advancement; terminal non-PR results become retryable after that advance.
3. For `skipped-unchanged`:
   - When the result carries `claimed` and an owner, do not dispatch it again;
     another worker already owns the exact content and base identity. If the
     adapter proves that owning process has ended without a terminal result,
     clean up its exact bound worktree when one is reported, then run `recover
     --repo <root> --attempt-key <key> --owner <owner>`. Never recover an active
     or uncertain worker merely because its claim is old.
   - Preserve a prior `not-reproduced`, `needs-shaping`, or `blocked` result
     until the follow-up content or remote default-branch SHA changes. Terminal
     identity output retains `owner <owner> [<worktree> <branch>]`; if that
     worktree still exists after its worker ended, use those exact coordinates
     for `cleanup` before starting the base-change retry. A base advance does not
     hide an outstanding terminal worktree.
   - When the result carries `pull-request` and a URL, check that pull request.
     Keep it skipped while open. After an unmerged close, run `clear` for that
     exact base identity before retrying. A merged pull request should remove
     the follow-up on the updated default branch; report a mismatch instead of
     opening a duplicate. If the path was deleted and later re-created, treat it
     as a fresh follow-up lifetime even when its Markdown matches the old item.
4. Establish whether candidate scopes are independent before running workers
   concurrently. Process uncertain or overlapping scopes separately while
   retaining a distinct worktree and pull request for each item.
5. A failed worker does not cancel other independent workers. Never exceed
   three actual workers in one sweep.

## Launch one isolated worker per item

Give every worker only its follow-up path, verified base SHA, attempt identity,
owner token, branch, worktree, and the worker contract below. The owner token is
required when binding the checkout, recording the outcome, and cleaning up, so
one worker cannot overwrite or remove another worker's attempt. The dispatcher
also reserves each canonical worktree path repository-wide; never bypass a
reservation failure by reusing another attempt's checkout.

### Claude Routine

Use a subagent with `isolation: worktree` when the active installation has a
creation-time `WorktreeCreate` policy or equivalent check that stops on fetch
failure and guarantees the identity base SHA. Require the subagent to compare
its `HEAD` with that SHA before editing.

Before dispatch, run `claim --repo <root> --follow-up <path> --base-sha <sha>`.
Dispatch only a `claimed <attempt-key> <owner>` result. As the worker's first
action, run `bind --repo <root> --attempt-key <attempt-key> --owner <owner>
--worktree <worktree> --branch <branch>` from the native checkout. A bind
failure stops the worker before editing. Claude owns removal of a native
worktree after the coordinator records the terminal outcome.

When native creation cannot make that guarantee, run `prepare` to create and
verify the worktree, then start a top-level headless Claude worker from that
directory. Do not nest a Claude CLI process merely to duplicate isolation the
native subagent already guarantees.

### Codex Scheduled task

Treat the scheduled task as coordinator only; its background worktree does not
isolate item workers. For each eligible item:

1. Choose a unique worktree path and branch whose name includes the follow-up
   slug and a short attempt-identity suffix.
2. Run `prepare --repo <root> --follow-up <path> --worktree <path> --branch
   <branch>`. Continue only for `prepared <worktree> <branch> <base-sha>
   <attempt-key> <owner>`; a concurrent sweep can instead return
   `skipped-unchanged` without creating a checkout. The dispatcher persists the
   canonical worktree target before creation, so an interrupted prepare is
   reported with the same claim owner, worktree, and planned branch for exact
   cleanup rather than becoming an anonymous checkout.
3. Start a top-level non-interactive Codex worker with `codex exec -C
   <worktree> --sandbox workspace-write <prompt>`. Configure only the network
   and approval capabilities needed to verify, push, and open the pull request.

Do not use a writing subagent that inherits the coordinator's working
directory as a substitute for per-item isolation.

## Apply the worker contract

### Verify the boundary

From toy-crane/skills, MIT.

More from toy-crane/skills