bug-prospector

bug-prospector

A Claude Code skill that finds bugs in code that compiles fine, passes tests, and looks right but breaks the moment a real user does something unexpected.

Companion: bug-echo — runs after a fix to find sibling instances of the same bug pattern. The two skills cover opposite halves of the bug-finding loop.

bug-prospector and pattern-based linters are complementary, not competitive: linters check how your code is written against a rule catalog; bug-prospector checks what your code assumes against 7 forward-looking lenses. A thorough audit uses both.

Built while shipping Stuffolio, an iOS/macOS app currently at build 33. Free, open source, Apache 2.0.

~6 min read · scan the TL;DR if you only have 30 seconds

TL;DR

• What: 7 forward-looking analysis lenses (assumptions, state machines, boundaries, lifecycle, errors, time, platform) that find behavioral bugs in code that compiles fine and passes tests.
• Why: Linters find code that looks wrong (force unwraps, deprecated APIs, retain cycles). bug-prospector finds code that looks right but behaves wrong — quiet assumptions that turn out not to hold under real-world conditions.
• Install: Two /plugin commands in Claude Code; then /bug-prospector is available in any project.
• Try first: /bug-prospector quick runs 3 of 7 lenses (Assumptions + Errors + Boundaries) on your recent changes. Light, fast, real report.
• Example output: a real backup-manager audit on Stuffolio (4 BUG findings, 4 lenses). Also: quick-scan on TypeScript.
• Maturity: Used through real App Store submission cycles; works on any language, with extra Swift/SwiftUI lens depth.

What is this, and why might I want it?

If you're newer to Claude Code and unsure what an "audit skill" does, here's the short version.

A skill is a markdown file Claude Code knows how to run. When you type /bug-prospector, Claude follows the instructions in that skill, looks at your code, and writes you a report. You don't have to memorize anything. The skill tells Claude what to do; you read the report.

What bug-prospector is for vs what linters are for

bug-prospector and linters are complementary — they catch different bugs at different layers.

Pattern-based tools (SwiftLint, ESLint, custom rule sets, single-file linters) check how your code is written. They flag force unwraps, missing @MainActor, retain cycles, deprecated APIs. If the syntax breaks a known rule, they catch it. They're fast, run continuously, and catch a real class of bugs cheaply. They will find issues bug-prospector won't — anything expressible as a single-file pattern.

bug-prospector checks what your code assumes. Things like:

• What happens when that array is empty?
• What if the user double-taps Save before the first save finishes?
• What if the network call completes after the view disappears?
• What if they open the app for the first time in 3 months?

These are bugs that compile fine, pass tests, and look right. The bug isn't in any single line. It's in a quiet assumption that turns out not to hold under real-world conditions. bug-prospector will find issues linters won't — assumption bugs have no code signature to search for.

The short version: linters find code that looks wrong. bug-prospector finds code that looks right but behaves wrong.

What linters do better	What bug-prospector does better
Run on every save (cheap, continuous)	Run before release or after a crash (deeper, slower)
Catch style and pattern violations	Catch behavioral and assumption bugs
Mechanical, deterministic	Asks questions the rule catalog doesn't cover
Mature ecosystem	7-lens forward-looking analysis

A useful analogy: a linter is the building inspector confirming every wire is up to code. bug-prospector is the home inspector asking "what happens if the dishwasher and the microwave are running at the same time?" Different layer, different bugs. The inspection isn't complete without both.

bug-prospector vs. bug-echo — which should you use?

Both have "bug" in the name; they answer different questions and run at different times.