File Follow-up Issues Skill

When a PR merges, the review findings that didn't get addressed tend to evaporate. This skill captures them: it opens one GitHub issue per unresolved finding so review debt becomes tracked work instead of quietly disappearing in the gap between "merged" and "next sprint."

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Where the review findings live — this skill defaults to REVIEWED.md, PR-comment.md, SCOPE_REVIEW_*.md, PLAN_REVIEW_*.md, and other *_REVIEW_*.md at the repo root, but your project may keep them under a different name or directory. If none turn up at the root, ask where they are rather than reporting "nothing to file."
• The label scheme — whether the repo already has an issue-label convention to reuse, or whether to propose and create the default from-review / priority:* labels.
• Issue granularity — one issue per finding (default) versus folding related findings in the same file/area into a single checklist issue.
• File vs. preview — whether to file the issues directly or first show the surviving list for sign-off (default: show and wait unless the user passed --yes / "file them all").
• Where to write the audit trail — the summary file defaults to FOLLOWUP_ISSUES_PR<n>.md at the repo root; confirm if the user wants it elsewhere or not written at all.

Inputs

Expect either a PR reference (e.g. PR #483) or nothing at all.

1. Figure out which PR to work from:
   • Use the number if the user named one.
   • Otherwise pull recent merges with gh pr list --state merged --limit 5 and ask the user to pick when it's not obvious.
2. Confirm it actually merged: gh pr view <n> --json state,mergedAt,title,url,headRefName. If the state isn't merged, stop and say so.
3. Gather the review artifacts — read every one that exists. Check the repo root first for the standard names:
   • REVIEWED.md
   • PR-comment.md
   • SCOPE_REVIEW_*.md (prefer the one matching the PR number, e.g. SCOPE_REVIEW_PR<n>.md)
   • PLAN_REVIEW_*.md
   • Any other *_REVIEW_*.md

If none of these turn up at the root, don't conclude there's nothing to file — this project may keep review notes under a different name or directory. Ask the user where the findings live before stopping.

What counts as "unresolved"

A finding is unresolved when a review file raised it and no commit in the merged PR actually fixed it. Work it out like this:

1. Assemble candidates: every finding across every review file, collapsed to one entry per file + line_range + concern.
2. Test each candidate against what the PR shipped:
   • Pull the merged diff with gh pr diff <n>.
   • Inspect the referenced file as it stands at the merge commit — git show <merge-sha>:<path>, or just Read the file on the merged branch.
   • Problematic code removed, or the change matches the review's "After" snippet → resolved, drop it.
   • Code untouched or only half-fixed → unresolved, file it.
3. When you genuinely can't tell, file it. Closing a needless issue is cheap; a dropped follow-up is work that's just gone.

Don't take a "fixed" note in the review file at face value — confirm it against the code every time.

Severity → issue labels

First check what labels the repo already uses (gh label list) and map onto its convention where one exists. Otherwise translate review severity into the default labels below (run gh label create for any that don't exist yet — confirm before creating new labels in a repo that already has its own scheme):

Always attach from-review so the whole batch stays filterable in one query.

Issue body template

Each issue has to stand on its own — someone reading it later should never need to open the original PR to make sense of it.

> Follow-up from merged PR #<num> — <PR title>
> Source review: <REVIEWED.md / PLAN_REVIEW_PR<n>.md / etc.>

## Problem

<1-3 sentence explanation of what is wrong and why it matters.>

## Location

`path/to/file.go:LINE_START–LINE_END`

## Current code

```<lang>
// exact snippet from the file as of merge commit <sha>

Proposed fix

// the fix from the review

Context

<Any extra reasoning, failure mode, user-visible impact, or related issues from the review.>

Filed automatically by file-followup-issues skill after PR #<num> was merged at <merged_at>.

Rules:
- **Take the "Current code" snippet from the file at the merge commit**, never from the review file — line numbers drift, so re-confirm the range against the live file.
- Put the exact path and line range in the issue body so it stays grep-able.
- If several findings hit the same file and area and are clearly related, you MAY fold them into one issue with a checklist. The default stays one issue per finding.

## Process

1. Confirm the merge. Record `<num>`, `<title>`, `<url>`, `<merged_at>`, `<merge_sha>`.
2. Read every review file end to end.
3. Build the deduped candidate list, carrying severity, file, line range, concern, before/after snippet, and source file for each.
4. Verify each candidate against the merge commit and drop whatever already shipped a fix.
5. Show the user the surviving list — one line each: `[SEVERITY] file:lines — short title` — and get a go-ahead before filing. Skip the confirmation only when the user passed `--yes` or said "file them all".
6. File each survivor with `gh issue create --title "..." --body-file <tmp> --label ...`. Back the body with a heredoc temp file so the formatting survives.
7. Keep the issue URL each call returns.
8. Write the audit trail — `FOLLOWUP_ISSUES_PR<n>.md` at the repo root by default, or wherever the user prefers: every issue filed, with URL, severity, and a one-line description.
9. Report to the user — counts by severity, the summary file path, and the issue URLs — in under 150 words.

## Safety rules

- **Never file before confirming the PR merged.** While it's still open, the fix belongs in the branch, not in a new issue.
- **Never file a duplicate.** Search first: `gh issue list --search "<file>:<line> in:body" --state all`. If something already covers it (open or closed), skip and note that in the summary.
- **Respect explicit dispositions.** Anything the user marked "won't fix" or "by design" in a review file stays unfiled.
- **Confirm the batch before looping `gh issue create`.** The user may want to cut some findings or reword titles.
- This skill only creates. Never `gh issue close` anything.
- Leave the source review files untouched — they're the historical record.

## When not to use

- PR hasn't merged yet → post the consolidated review with `/pr-comment` instead.
- No review files on disk → run `/code-review` first.
- One trivial finding the user wants gone now → just fix it rather than filing.
- No `gh` auth, or not a GitHub repo → say so and stop.

## Example invocation

user: PR #483 just merged. File the leftovers.

assistant:

1. gh pr view 483 → confirm merged
2. Read REVIEWED.md, PR-comment.md, SCOPE_REVIEW_PR483.md, PLAN_REVIEW_PR483.md
3. Build candidate list: 39 findings
4. Verify against merge commit: 12 were fixed in the final diff → drop
5. Dedupe overlaps: 27 → 22 unique
6. Check existing issues: 2 already tracked → drop
7. Show user list of 20 to file
8. User confirms
9. gh issue create × 20
10. Write FOLLOWUP_ISSUES_PR483.md
11. Report: "Filed 20 issues (4 MUST FIX, 11 SHOULD FIX, 5 FOLLOW-UP). See FOLLOWUP_ISSUES_PR483.md."