defer-issue

When the user decides to push something out of the current scope, file a new issue in the appropriate forge that captures the deferred work cleanly enough for them (or a future Claude) to pick it up cold.

When this fires

User says something like:

  • “let’s defer this”
  • “defer this for later”
  • “create a followup issue for X”
  • “we’ll handle that in a separate PR”
  • “make this its own issue”

Don’t fire just because something looks unfinished. The user must explicitly defer.

One standing exception, which is a grant rather than a loophole. issue-first’s deferral section licenses deferring a request the user made but that is out of scope for the change in flight, on your own judgment, so long as the deferred item is filed in the same reply. Run this skill’s procedure for that case too, since the filing mechanics are identical and only the trigger differs. Read that section’s boundary first: a defect inside your own diff is never deferrable, however cleanly the issue is written.

Procedure

1. Identify the forge

git remote get-url origin
Host CLI
github.com gh issue create
gitlab.com / self-hosted GitLab glab issue create
Bitbucket / Gitea / other ask the user how to file

If the matching CLI isn’t installed, surface that and stop — don’t try to file via the raw HTTP API without confirming.

2. Gather context

From the current conversation, identify:

  • What is being deferred (one sentence — becomes the title)
  • Concrete work needed (what change, which files, what “done” looks like)
  • Why deferring (out of scope, needs design discussion, blocked on X)
  • Where the deferral was raised (PR number, commit SHA, file:line, review thread)

If any of these are unclear from context, ask the user briefly before filing. A vague follow-up issue is worse than no issue.

2b. Search for an existing issue first — including CLOSED ones

Before filing, check the tracker so you don’t create a duplicate. Search both open and closed issues by keyword — deferred review findings are often pre-filed by an earlier session or the review bot and may already be closed (e.g. as a duplicate, or decided), which an open-only search misses:

gh issue list --state all --search "<keywords>" --json number,title,state   # SEARCH_ISSUES
# GitLab: glab issue list --all --search "<keywords>"   # --all (-A) = open + closed
  • If an open issue already covers it, link that one instead of filing — report its URL and stop.
  • If a closed issue covers it, surface it to the user (it may have been closed as a duplicate pointing elsewhere, or closed as decided) and confirm whether to reopen it, file fresh, or treat the matter as settled — don’t blindly file a second one.

This is the never assume; always verify rule applied to issue filing: a quick search beats leaving two issues tracking the same work.

3. Compose the issue

Title: short, imperative, specific. Good: Refactor session_env merge logic to handle nested overrides. Bad: Followup, TODO from PR #42.

Body template:

## Context

Deferred from <source: e.g., PR #42, commit abc1234, review on path/to/file.R:120>.

<1–2 sentences on why this work is being split off from the current change>

## What to do

<concrete description: what change, which files, what success looks like>

## Why not now

<reason for deferring — out of scope, needs design, blocked, etc.>

4. Create the issue

GitHub:

gh issue create \
  --title "..." \
  --body "$(cat <<'EOF'
...
EOF
)"   # CREATE_ISSUE
  • Defaults to the current repo (whatever gh resolves from remotes / gh repo set-default).
  • If filing into a different repo than the current one, pass --repo <owner>/<repo> and confirm with the user first.
  • Check gh label list for an existing followup, deferred, or tech-debt label and add it with --label. Don’t fabricate labels that don’t exist — gh will fail and you’ll have to retry.
  • Don’t add 🤖 Generated with Claude Code attribution to the issue body unless the user asks. Issue attribution isn’t covered by the global attribution setting. This is not an exemption from the agent-disclosure rule, which governs comments rather than issue bodies and uses a different, deliberately emoji-free marker — see disclose-agent-authorship. So a comment this skill posts on the deferring PR carries the marker, while the filed issue’s own body stays unattributed.

GitLab:

glab issue create --title "..." --description "$(cat <<'EOF'
...
EOF
)"

Edge cases

  • Not in a git repo / no remote: stop and tell the user. Don’t try to invent a target repo.
  • Forked PR (head repo != base repo): file the issue in the base repo by default — that’s where the work will actually land — and confirm if it’s ambiguous.
  • Different tracker entirely (Linear, Jira, repo-specific issue tracker): ask the user where to file. Don’t assume GitHub/GitLab just because the source is hosted there.
Back to top