api-footgun-reviewer
API footgun reviewer: harvests exported function/method signatures, flags boolean-trap positions (multiple bare bool params in a row), same-type-adjacent swaps (from/to, save/loadUntil), and inconsist
SKILL.mdskills/quality/api-footgun-reviewer/SKILL.md
GitHubWhat this is for
Internal APIs are the ones we use daily and have full control of - that is
exactly why they grow footguns. Boolean trap: saveFile(overwrite, verbose)
with two bare bools. Same-type swap: send(from, to, subject) where from/to
are interchangeable by mistake. Inconsistent family: createThing(a, b, c)
versus createThingPrefixed(a, b, c, d) with different param orders that
look identical at the caller.
Spectral and API-design linters exist for public REST APIs. None of them catch in-code function-signature footguns. This skill does.
PROTECTION RULE - never ~/.claude/
Read-only skill. Guard required if write mode added later.
## What You Must Do When Invoked
During analysis, assign a confidence level to each finding: proven (confirmed by evidence), likely (strong signal, needs review), or suspected (weak signal).
Step 1
- If
-helpis passed, print the## Usageblock below and stop.
Step 2
- Confirm
-ProjectDiris provided and the path exists.
Step 3
- Run:
scripts/signature-harvest.ps1 -ProjectDir "<path>"
Step 4
- LLM reads the JSON output. For each finding:
Step 5
- Is this distinction intentional (e.g., from this library for type
Step 6
safety) or a real footgun?
Step 7
- Check call sites. How many places invoke this with the bare-bool or
Step 8
adjacent-type ambiguity? Higher count = higher severity.
Step 9
- For inconsistent family: is the order alphabetical, type-grouped,
Step 10
or just historical? Make it intentional.
Step 11
- Propose a fix per finding. For booleans, prefer options-object. For
Step 12
same-type, name the params (fromAddress, toAddress). For families,
Step 13
choose one convention.
Step 14
- Write
footgun-report.mdto the working directory.
Usage
/footguns # interactive
/footguns <dir> # scan project directory
/footguns -help # show usage
Returns JSON with signatures[], similarityGroups{}, findings[]
plus summary counts.