File Issue

file-issue

Files one or more GitHub issues end-to-end, with exactly one human approval gate — before any issue is created on GitHub. Two entry modes, chosen by what's passed to the trigger:

• No argument, or a repo name → Audit mode: scan every in-scope repo across six

lenses (security, scalability, robustness, bugs, deployment risk, best practices) and file an issue for each confirmed finding.

• A description of a suspected problem → Verify mode: check whether that specific

problem actually exists in the code before filing anything for it.

Do not run this unattended. If the person who invoked /file-issue is not present to approve the drafted issues at Step 8, stop and wait there.

Never file a finding you can't back with a real file:line citation and a concrete failure scenario. A plausible-sounding guess is not a finding — see Step 4.

Announce at start: "Using file-issue to [audit `|verify `]."

Step 1: Resolve mode and scope

Find every local git repo directly under the directory this skill was invoked from:

for d in */; do
  [ -d "$d/.git" ] || continue
  repo_dir="${d%/}"
  remote=$(git -C "$repo_dir" remote get-url origin 2>/dev/null)
  slug=$(echo "$remote" | sed -E 's#\.git$##; s#.*[:/]([^/]+/[^/]+)$#\1#')
  printf '%s\t%s\n' "$repo_dir" "$slug"
done

$repo_dir (the local path, no trailing slash) and $slug (owner/repo) are the two values every later step needs — keep both around per in-scope repo.

If this finds nothing, stop and tell the user — do not guess at a repo location.

Then classify the trigger argument:

• No argument → Audit mode, scope = every repo found above.
• Argument matches one of the directory names found above → Audit mode, scope = that

repo only.

• Argument is a GitHub issue URL → wrong skill. Tell the user this files new issues;

fixing an existing one is fix-issue. Stop.

• Anything else → Verify mode, problem_description = the argument text. Search across

all repos found above for the code paths it plausibly implicates (grep for the symptom, the component name, error text) to identify which repo(s) are actually in scope — don't assume the first repo that matches a keyword.

Step 2: Sync in-scope repos

For each in-scope repo:

git -C "$repo_dir" status --short

If this prints anything, stop and ask the user how to proceed (uncommitted work could mean a finding is about to be fixed, or that WIP itself needs eyes) — never silently include or discard it.

Once clean:

default_branch=$(git -C "$repo_dir" remote show origin | grep "HEAD branch" | awk '{print $NF}')
git -C "$repo_dir" checkout "$default_branch"
git -C "$repo_dir" pull

Step 3: Find candidates

Verify mode

Read the code paths identified in Step 1 on the just-synced default branch. This is code-read only — never start services or run the app to check this. Reason explicitly about whether the described problem is real given what the code does today.

• Doesn't reproduce / already handled → state clearly why, and **stop the pipeline

entirely** — file nothing. Report this as the final output of this run.

• Confirmed → you now have one candidate with a known root cause. While you're in this

code path, also check whether it carries security, scalability, robustness, or deployment implications beyond the original description — fold those into the same finding's Impact section rather than filing separate issues for the same root cause. Continue to Step 4.

Audit mode

For each in-scope repo, search for concrete, evidence-backed problems across six lenses:

| Lens | Look for | |---|---| | Security | injection, auth/authz bypass, secrets in code/logs, missing tenant-boundary checks, unsafe deserialization | | Scalability | unbounded loops/queries, missing pagination, N+1 queries, synchronous work that should be async, no backpressure | | Robustness | unhandled errors swallowed silently, missing timeouts/retries, race conditions, unvalidated external input | | Bugs | logic that contradicts its own docstring/tests, off-by-one, wrong comparison, dead code paths that should be reachable | | Deployment | missing env var validation, no migration rollback, hardcoded config, missing health checks, undocumented required infra | | Best practices | untested critical paths, missing TDD coverage on new logic, duplicated logic that should be shared, unclear naming that hides a bug |

If the scope is more than one or two repos, dispatch one subagent per repo (Agent tool, Explore or general-purpose) rather than reading every repo yourself — see superpowers:dispatching-parallel-agents. Give each subagent the six lenses above and this explicit instruction: "Only report a finding if you can cite the exact file and line and describe a concrete input/state that triggers a concrete wrong outcome. Do not report stylistic opinions or things you merely suspect." Collect their findings before continuing.

Step 4: Quality bar — verify every candidate yourself

For each candidate (from either mode), before drafting anything:

1. Open the cited file at the cited line yourself and confirm the code actually does what

the finding claims — subagents and your own first pass can misread code.

1. Confirm you can state the failure as "given `, `" — not "this could cause issues" or "this seems risky."

If either check fails, drop the candidate. Do not soften it into a lower-priority issue — an unverified finding gets filed nowhere, not filed as "low priority."

Step 5: Check for duplicates

For each surviving candidate, search the target repo's open issues before drafting:

gh issue list --repo "$slug" --state open --search "" --json number,title,url

If an existing open issue clearly covers the same root cause, drop the candidate and note the existing issue's number/URL in your final report instead of drafting a new one.

Step 6: Classify type and priority

Type (pick exactly one):

| Type label | When | |---|---| | security | Lens = security, or any finding with a real exploit/data-exposure path | | bug | Code produces a wrong result or crashes today, under realistic conditions | | enhancement | Works today but a gap becomes a problem at higher scale/load/usage | | tech-debt | No incorrect behavior yet — missing tests, duplicated logic, unclear deployment story |

Priority (pick exactly one):

| Priority label | Criteria | |---|---| | priority: critical | Exploitable now, or breaks production for all/most tenants, or causes data loss/cross-tenant leakage | | priority: high | Real security weakness or bug hitting a critical path / many tenants, or an outage under realistic (not extreme) load | | priority: medium | Affects a subset of tenants/edge cases, or degrades robustness/deployability without breaking things today | | priority: low | Best-practice/tech-debt gap, missing coverage, minor logging/UX issue |

Step 7: Draft each issue

Write drafts to $repo_dir/docs/filed-issues/-findings.md (one file per repo with findings, one numbered section per issue — create the directory if needed). Use this body template for every issue so a coding agent (e.g. fix-issue) and a human reviewer can both act on it without asking follow-up questions:

````markdown

Problem

Root cause

Evidence

path/to/file.ext:line

Impact

Proposed fix

Affected files

• path/to/file.ext —

Test plan

Deployment notes

````

Title format: : (e.g. Security: JWT signature check skipped on token-refresh path). Never leave a section empty — if it genuinely doesn't apply, say why in one sentence.

Step 8: Gate — get approval before filing (STOP AND WAIT)

Call EnterPlanMode. Inside plan mode, write a compact table — one row per drafted issue: repo, title, type, priority, one-line problem — plus a pointer to each repo's docs/filed-issues/-findings.md for full bodies. Then call ExitPlanMode.

• Approved as-is → continue to Step 9.
• Changes requested (drop some, reprioritize, edit wording) → revise the relevant draft

file(s), re-present through this same gate. Repeat until approved or the user stops.

• User aborts → end here. File nothing.

Never proceed past this step without an explicit approval from ExitPlanMode.

Step 9: Ensure labels exist, then file

ensure_label() {
  local repo="$1" name="$2" color="$3" desc="$4"
  gh label list --repo "$repo" --limit 200 | cut -f1 | grep -qxF "$name" || \
    gh label create "$name" --repo "$repo" --color "$color" --description "$desc"
}

ensure_label "$slug" "security"          "b60205" "Security vulnerability or weakness"
ensure_label "$slug" "tech-debt"         "fbca04" "Best-practice / clean-code / test-coverage gap"
ensure_label "$slug" "priority: critical" "b60205" "Critical — urgent, active risk or production-breaking"
ensure_label "$slug" "priority: high"     "d93f0b" "High — significant risk, fix soon"
ensure_label "$slug" "priority: medium"   "fbca04" "Medium — real gap, not urgent"
ensure_label "$slug" "priority: low"      "c5def5" "Low priority — not urgent, safe to defer"

(bug and enhancement are GitHub's default labels — ensure_label still works if a repo happens to lack them.) Then, for each approved draft:

gh issue create --repo "$slug" --title "" --body "$(cat 
EOF
)" --label "" --label ""

Step 10: Report

List every created issue's URL grouped by repo. Separately list any candidates dropped in Step 4 (unverifiable) and Step 5 (duplicate, with the existing issue's URL).

Error handling

| Situation | Behavior | |---|---| | No local git repos found under the invocation directory | Stop, tell the user | | Uncommitted changes in an in-scope repo | Stop, ask — never silently include or discard | | Verify mode: problem doesn't reproduce | Stop after Step 3, report, file nothing | | A candidate fails the Step 4 quality bar | Drop it — never file it at a lower priority instead | | A candidate duplicates an existing open issue | Drop it, note the existing issue's URL | | User requests changes at Gate (Step 8) | Revise drafts, re-present; loop until approved or aborted | | gh label create fails (permissions) | Stop that repo's filing, report the error — don't file unlabeled issues |

Source & license

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

• Author: gssajith
• Source: gssajith/claude-skills
• License: MIT

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