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.md

GitHub

What 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

  1. If -help is passed, print the ## Usage block below and stop.

Step 2

  1. Confirm -ProjectDir is provided and the path exists.

Step 3

  1. Run: scripts/signature-harvest.ps1 -ProjectDir "<path>"

Step 4

  1. 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

  1. 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

  1. Write footgun-report.md to the working directory.

Usage

/footguns                          # interactive
/footguns <dir>                    # scan project directory
/footguns -help                    # show usage

Returns JSON with signatures[], similarityGroups{}, findings[] plus summary counts.