Issues

/issues — the project's to-do list and memory, in GitHub issues

Every problem worth fixing becomes an issue: a claim in the paper that misleads, a table that disagrees with the code, a bug, an improvement for later. The open issues are the to-do list. When a fix lands, the issue is closed with a comment that says what was wrong, what was tried — including what did not work — and how it was fixed. Read back months later, the closed issues are the project's memory: auditable, searchable, and the same on every machine and for every co-author, which a chat transcript or a local notes file is not.

This skill makes the habit cheap. It never posts anything without showing the draft first and getting a yes.

When to use

• After a review — /review-paper, /seven-pass-review, /adjudicate-review, or findings you list yourself — to turn each confirmed problem into its own issue.
• When starting or resuming work — to see what is open for the paper, section or files at hand, and pick the next thing.
• When a fix has landed — to close its issue with a record of what happened.

Modes

file <report|text> — turn findings into issues

The input is a findings JSON from the review runtime, a review report, or problems described in the conversation.

1. Pre-flight. gh auth status must succeed. Then gh repo view --json visibility,nameWithOwner: on a PUBLIC repository, say plainly that every issue will be public — unpublished results, referee-sensitive weaknesses and co-authors' drafts would be visible to anyone — suggest a private repository for paper work, and create nothing without an explicit yes to that.
2. One issue per root cause, for problems that matter. Merge findings that share a cause; split a finding that bundles two problems. File confirmed findings that affect correctness or a stated requirement; list the rest to the user as optional rather than filling the tracker with reviewer noise.
3. Deduplicate against open and closed issues — this is enforced, not optional. Every new issue is created through scripts/file-issue.py (step 5), which runs several searches first: the title's most distinctive words together, the top three alone in titles, every --search term you pass (a section name, a table label, a function), and up to three file paths the issue names — at most eight searches, and any dropped are reported. A match gets a comment on the existing issue (reopen it if the problem is back), not a new issue.
4. Draft each issue.
   • Title: the problem as a checkable statement — "Intro overstates the sample: 3,412 in §1 vs 3,142 in Table 1", not "Fix intro".
   • Body: What's wrong (file:line or section, with the exact quote), Why it matters, Done when (the acceptance test), Source (the report path and git rev-parse --short HEAD).
   • Labels: bug, documentation or enhancement, plus an area label such as paper, code or slides if the project uses them (create one on first use with gh label create).
5. Show every draft as one numbered list, then create only the ones the user approves, each with python3 scripts/file-issue.py --title "…" --body-file <draft> [--label …] [--search "…"]. Exit 3 means it found possible duplicates and created nothing: read each (gh issue view N), comment on the one that is the same problem, or — if the new issue is distinct from all of them — re-run with --checked N,M. The issue body then records which searches ran and which candidates were judged distinct. Exit 2 means the search could not run, and nothing was created. A raw gh issue create is denied by the issue-guard hook for the same reason. Report the new numbers.

list [topic] — what is open

gh issue list --state open --limit 100 --json number,title,labels,updatedAt, filtered to the topic, section or files at hand, oldest first. End with a suggestion of which issue to take next and why (blocking others, oldest, smallest). Read-only.

To have every new session start with the open list, set CLAUDE_ISSUES_AT_START=1 (under env in .claude/settings.local.json for your machine only). The open-issues hook then lists open issues' numbers and titles — by the owner and collaborators only — at startup. It is off by default because it calls GitHub on every startup.

close <#N> — close with a record

1. Gather: the issue (gh issue view N --comments), the commits that mention it (git log --oneline --grep "#N"), and what they changed.

2. Draft the closing comment:

   • What was wrong — the diagnosis as it turned out, if it differs from the report.
   • What was tried — including what did not work, and why. This is the part a future reader cannot reconstruct and most needs.
   • What fixed it — the commits.
   • How it was checked — the test, render, or re-run that shows it fixed.
   • What remains — anything deferred, with its own issue number.

   A small fix (a typo, a stale sentence) gets the short form: what was wrong, the commit, how it was checked. A defect that can move a result or a number gets the full seven sections of issue-ledger.md.

3. After the user's yes: gh issue comment N --body-file <draft>, then gh issue close N. For a problem that turned out not to be one, gh issue close N --reason "not planned", with the evidence in the comment.