issue-sanity-check

A pessimistic go/no-go the moment you pick up a GitHub issue — read it skeptically and hunt for reasons NOT to do it (already done? obsolete? duplicate? premise wrong? cheaper way? net-negative?), ret

SKILL.md

GitHub

Issue Sanity-Check — should this even be done? (pickup gate)

Claiming an issue and starting to build is a reflex. This skill inserts a deliberately skeptical pause first: a stale, obsolete, duplicated, or wrong-premise issue is cheapest to catch before a build is sunk into it. It's the pickup-time half of the dedup gate; /issue-dedup is the create-time half. Both are sub-issues of epic #297.

This is a skeptic's checklist, not a rubber stamp. Your job here is to find a reason not to do the work. If you can't find one, that's the proceed signal.

When this fires

Step 1 of the Task Execution Workflow — the moment you claim an issue, before doing the work. Also on demand: /issue-sanity-check #NN.

The checklist (hunt for a reason to STOP)

Read the issue, then ask each — answer with one line of evidence (a link, a path, a date):

  1. Already done? — search closed issues/PRs and the code for the change. Did a later commit/PR already ship this? (git log --oneline -S'<symbol>', search_issues state:closed.)
  2. Obsolete / overtaken? — has the architecture moved past it? (e.g. it targets Pages but we're on Workers; it patches a file that's been deleted/rewritten.)
  3. Duplicate / colliding? — is there an open issue or epic for the same thing? (Reuse the /issue-dedup search. If yes, this is a merge, not two builds.) 3b. Already being worked — right now? — the one an issue search misses, because the collision isn't another issue, it's another runner. Check all three:
    • the issue is closed (someone finished while you were reading it),
    • an open or merged PR references it (search_pull_requests "<N> in:body", then confirm a Closes #N-style keyword — Follow-up to #N is not a claim),
    • status:in-progress is on it and was stamped recently (check the label's event timestamp, not just its presence — a crashed run leaves a stale one).

      Any of those → 🛑 Drop (or 🔁 into "review/finish the existing PR"). This cost three duplicate builds on 2026-08-05 alone: #1478 started 8 min after #1473 closed its issue, and #1889 opened while #1888 was already open. The pipeline half of this gate is the claim-guard in scripts/pipeline-loop-guard.mjs (#1890) — it cannot see interactive sessions, which is exactly how #1622 and #1889 happened. You are that half.

  4. Premise still true? — does the "we think that…" hypothesis still hold, or did reality change? A wrong premise makes a perfectly-built feature worthless.
  5. Cheaper alternative? — is there a smaller change, an existing composable/skill, or a config flip that gets 90% of the value? (KISS — CLAUDE.md core principle.)
  6. Net-negative? — does it add surface/complexity we'll regret, contradict a current pattern, or block something more valuable? Sometimes the right move is to close it.
  7. Target reachable? — do the files the issue names actually render or execute? Run node scripts/check-issue-targets.mjs <issue-number>. An issue can name dead code, and building exactly to spec then ships something nobody can reach while satisfying every acceptance criterion — #1657 specified an Import button in ProductsTab.vue, a component mounted in no template.

    ⚠️ Flag, never drop. Zero references is a hypothesis (the #1149 deletion protocol, in reverse): this repo mounts things dynamically — directory scanners, the croutonBlocks/croutonLayoutBlocks registries, @nuxt/kit resolver paths. The probe already excuses file-routed paths (server/api/**, app/pages/**, auto-imported utils/composables) and registry entries, but verify before acting. The right verdict is 🔁 Reshape — "build it, somewhere reachable; confirm where" — not 🛑.

The verdict (REQUIRED output)

End with exactly one of:

  • ✅ Proceed — no blocker found. One line on why it still makes sense, then go.
  • 🔁 Reshape — the goal is valid but the framing/scope is wrong. State the smaller/changed scope, update the issue body, then proceed on the reshaped version.
  • 🛑 Drop — there's a real reason not to do it. Name it with evidence, and (interactive) recommend closing not_planned / merging into the duplicate — ask the owner before closing, don't unilaterally bin their issue.

Keep it tight — seven one-line checks and a verdict, not an essay. The value is the pause, not a long report.

Recording it

  • Interactive → state the verdict in chat. For 🔁/🛑, ask the owner before reshaping or closing (use AskUserQuestion). For a 🛑 you act on, post a comment with the evidence so the close is explained (lead with the 🤖 provenance header — see CLAUDE.md).
  • Autonomous / pipeline → post the verdict as a comment on the issue (provenance header) so the chain is auditable, and for 🛑 set status:blocked + @mention rather than closing silently.

What this is not

  • Not the create gate — that's /issue-dedup (don't mint a duplicate).
  • Not bug-archaeology — that's the "how/when was this introduced" gate for bugs (#424).
  • Not a license to skip work you simply don't feel like doing — the verdict needs evidence, not vibes.