# File Followup Issues

> Once a PR lands, open one GitHub issue for each review finding that never got fixed — SHOULD FIX, FOLLOW-UP, or a deferred MUST FIX — as captured in REVIEWED.md, SCOPE_REVIEW_*.md, PLAN_REVIEW_*.md, PR-comment.md, or pre-merge-review notes. Use when the user says "file follow-ups", "create issues for unresolved", "/file-followup-issues", "PR merged, file the leftovers", or when a ship / merge wor…

- **Type:** Skill
- **Install:** `agentstack add skill-napnap11-claude-skills-file-followup-issues`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [napnap11](https://agentstack.voostack.com/s/napnap11)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [napnap11](https://github.com/napnap11)
- **Source:** https://github.com/napnap11/claude-skills/tree/main/file-followup-issues

## Install

```sh
agentstack add skill-napnap11-claude-skills-file-followup-issues
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.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  --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.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 `.
   - Inspect the referenced file as it stands at the merge commit — `git show :`, 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):

| Review severity | Label(s) | Issue title prefix |
|---|---|---|
| MUST FIX / CRITICAL / BLOCKER | `bug`, `priority:high`, `from-review` | `[MUST FIX]` |
| SHOULD FIX / HIGH | `priority:medium`, `from-review` | `[SHOULD FIX]` |
| FOLLOW-UP / LOW / INFORMATIONAL | `priority:low`, `from-review`, `tech-debt` | `[FOLLOW-UP]` |

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.

```md
> Follow-up from merged PR # — 
> Source review: .md / etc.>

## Problem

## Location

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

## Current code

```
// exact snippet from the file as of merge commit 
```

## Proposed fix

```
// the fix from the review
```

## Context

---

_Filed automatically by `file-followup-issues` skill after PR # was 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 ``, ``, ``, ``, ``.
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  --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.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 ": 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."
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [napnap11](https://github.com/napnap11)
- **Source:** [napnap11/claude-skills](https://github.com/napnap11/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-napnap11-claude-skills-file-followup-issues
- Seller: https://agentstack.voostack.com/s/napnap11
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.