tkersey/footgun-finder

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.

Footgun taxonomy

Classify each candidate with one primary type:

unsafe_default
misleading_name_or_shape
silent_degradation
ambiguous_authority
irreversible_or_expensive_easy_path
copy_paste_trap
state_or_lifecycle_trap
validation_gap
observability_gap
concurrency_or_idempotency_trap
security_or_privacy_trap
compatibility_trap

Severity model

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:

make_safe_default
require_explicit_opt_in
rename_or_retype
split_safe_and_dangerous_paths
fail_closed_or_block
surface_degraded_state
bind_to_owner_or_policy
validate_at_boundary
add_idempotency_or_freshness_guard
add_dry_run_or_preview
repair_example_or_docs
add_diagnostic_or_next_action
handoff_to_invariant_ace
handoff_to_complexity_mitigator
handoff_to_review_fold
no_change

Do not jump from hazard to implementation. The output is a mitigation agenda, not a patch.

5. Check companion-lens overlap

Before final ranking, classify whether each candidate is primarily:

footgun
invariant
complexity
review_claim
ordinary_bug
non_issue

A footgun can overlap, but one lens should own the next step.

Footgun ledger

| id | priority | type | surface | actor | easy path | reasonable belief | hidden hazard | consequence | evidence | mitigation | owner/handoff | |---|---|---|---|---|---|---|---|---|---|---|---|

Rules:

• Use stable IDs: FG-001, FG-002, ...
• Evidence should cite the smallest path, symbol, command, example, config key, or test scope available.
• Each accepted row must include both the easy path and the hidden hazard.
• Do not mark something P1/P0 without a plausible normal-use trace.

Output modes

Compact review

Footgun Review:
- surface:
- accepted footguns:
- top hazard:
- not footguns:
- handoffs:
- bottom line:

Full review

1. Review Basis
2. Surface Map
3. Footgun Ledger
4. Misuse Traces
5. Rejected / Downgraded Candidates
6. Companion-Lens Handoffs
7. Mitigation Agenda
8. Proof / Validation Signals
9. Footgun Bottom Line

Review companion mode

When used alongside $invariant-ace and $complexity-mitigator, output only:

Footgun Lens:
- P0/P1 hazards:
- easy path -> hidden hazard traces:
- overlap with invariant/complexity:
- mitigation handoff:

Mitigation agenda

The agenda must be an exact projection of accepted ledger rows:

| id | mitigation class | proposed change shape | proof signal | handoff owner | |---|---|---|---|---|

Good proof signals include:

• misuse test that now fails closed;
• example updated so unsafe pattern is no longer copyable;
• degraded state visible in structured output;
• dangerous path requires explicit opt-in;
• fallback result is distinguishable from primary success;
• stale/duplicate/partial state is blocked before side effects;
• policy owner validates or denies the exception.

Guardrails

• Do not implement.
• Do not inflate every bug into a footgun.
• Do not demand maximal safety when the hazard is low-impact and well signposted.
• Do not hide behind documentation if the surface can cheaply prevent misuse.
• Do not add ceremony when a rename, explicit flag, type split, or fail-closed check would remove the trap.
• Do not use broad words like unsafe without a misuse trace.
• Do not count merely surprising implementation internals unless a caller can reasonably touch or copy the hazard.

Final report

End with:

Footgun Bottom Line:
- highest-risk footgun:
- easiest wrong path:
- smallest mitigation:
- companion handoff:
- proof signal:

Hard rules

• The easy path must be named.
• The reasonable belief must be named.
• The hidden hazard must be named.
• The consequence must be plausible.
• The mitigation must reduce misuse likelihood, not merely explain the code.
• If the right fix is an owned invariant, hand off to $invariant-ace.
• If the right fix is local winnowing, hand off to $complexity-mitigator.
• If the right fix is review pressure classification, hand off to $review-fold.