# File Issue

> Audit this workspace's repos for security, scalability, robustness, bugs, deployment risk, and best-practice (TDD/clean-code) gaps, or verify one specific suspected problem against the code, then file well-labeled, actionable GitHub issues for whatever is confirmed. Trigger: /file-issue [repo-name | description of a suspected problem]

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

## Install

```sh
agentstack add skill-gssajith-claude-skills-file-issue
```

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

## About

# 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:

```bash
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:

```bash
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:

```bash
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.
2. 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:

```bash
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

```bash
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:

```bash
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](https://github.com/gssajith)
- **Source:** [gssajith/claude-skills](https://github.com/gssajith/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-gssajith-claude-skills-file-issue
- Seller: https://agentstack.voostack.com/s/gssajith
- 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%.