Read-only review lens for latent misuse hazards: APIs, defaults, flags, fallbacks, examples, config, state, cleanup, permissions, and workflows where the easy or obvious use is unsafe, surprising, irreversible, or likely to be copied wrong. Use for `$footgun-finder`, footguns, sharp edges, dangerous affordances, trap doors, misleading names, unsafe defaults, partial-success ambiguity, hidden coupling, or review requests focused on future misuse. Not for generic bugs, invariant ownership, or local simplification unless the hazard is a misuse trap.
Read-only review lens for latent misuse hazards: APIs, defaults, flags, fallbacks, examples, config, state, cleanup, permissions, and workflows where the easy or obvious use is unsafe, surprising, irreversible, or likely to be copied wrong. Use for `$footgun-finder`, footguns, sharp edges, dangerous affordances, trap doors, misleading names, unsafe defaults, partial-success ambiguity, hidden coupling, or review requests focused on future misuse. Not for generic bugs, invariant ownership, or local simplification unless the hazard is a misuse trap.
Footgun Finder
Mission
Find code and interface shapes where a reasonable future caller, maintainer, user, or reviewer can do the wrong thing easily and believe they did the right thing.
available affordance
+ plausible user/caller belief
+ surprising or dangerous consequence
= footgun candidate
This skill is a read-only review lens. It does not implement fixes, resolve comments, create tickets, or certify closeout. It produces a ranked footgun ledger, mitigation candidates, and handoff routes.
Definition
A footgun is not merely a bug. A footgun is a design or implementation surface that makes misuse likely:
wrong path is easy
right path is non-obvious
failure is silent, late, misleading, or expensive
copy/paste or default use preserves the trap
If no plausible actor and action exist, classify the candidate as not_a_footgun even if the code looks odd.
Boundary with companion skills
Use this skill with, but do not replace:
$invariant-ace when the hazard is an illegal state that needs an owned invariant, counterexample trace, enforcement boundary, or witness parity gate.
$complexity-mitigator when the hazard is primarily local comprehension cost, dominated branches, duplicated factors, or incidental complexity.
$review-fold when the input is review pressure that must be classified before mutation or resolution planning.
The owning implementation workflow only after this review emits a concrete mitigation handoff.
If a finding is both a footgun and an invariant failure, classify the footgun surface here, then hand off the invariant proof to $invariant-ace.
If a finding is both a footgun and inessential complexity, classify the trap here, then hand the clarity cut to $complexity-mitigator.
Use when
APIs, CLIs, config, examples, docs, defaults, flags, fallbacks, retries, cleanup, permissions, persistence, or state machines seem easy to use incorrectly.
Review asks for sharp edges, dangerous defaults, future misuse, trap doors, hidden coupling, gotchas, unsafe examples, or accidental privilege.
A change looks technically correct but may create a misleading affordance.
A successful path and a degraded path are too easy to confuse.
A partial-success or fallback path looks like success to the caller.
Tests prove current behavior but do not protect plausible misuse.
Do not use for generic style review, broad architecture essays, pure performance work, or bugs with no plausible misuse surface.
Rank by expected harm and likelihood, not by how annoying the code looks.
P0 likely data loss, security or privacy exposure, irreversible destructive action, production outage, or policy bypass from plausible normal use
P1 high-probability misuse causing wrong behavior, false proof, lost work, persistent state corruption, or expensive recovery
P2 plausible misuse with bounded impact, confusing degraded behavior, or costly debugging
P3 minor sharp edge, confusing naming, or low-likelihood trap with easy recovery
A low-LOC issue can be P0. A large messy module can be no footgun if misuse is not plausible.
Review workflow
1. Establish the reviewed surface
Record:
artifact state:
repo/ref/head or supplied file version
surface:
API | CLI | config | docs/example | workflow | state machine | policy boundary | test fixture | internal helper
principal user/caller:
end user | maintainer | integrator | future implementer | test author | automation
Name the expected reasonable belief for that principal.
2. Scan for affordance traps
Ask:
What is the easiest call, flag, default, example, or copied pattern?
What would a reasonable user infer from the name or docs?
What hidden precondition, freshness rule, authority boundary, cleanup, or version assumption must be true?
Does degraded or partial success look like success?
Is the dangerous path easier than the safe path?
Does a test or example teach an unsafe real-world pattern?
What happens if this is retried, run twice, interrupted, or copied to another context?
3. Require a misuse trace
Every material footgun needs a concrete misuse trace:
actor -> action -> reasonable belief -> hidden fact -> consequence -> why current surface permits it
4. Separate hazard class from remedy class
For each accepted footgun, choose the smallest truthful mitigation class:
