bug-prospector

Bug Prospector

Mine for hidden bugs that pattern-based auditors miss.

What It Does

Code auditors check how your code is written — they find force unwraps, missing @MainActor, retain cycles, and deprecated APIs. If the syntax breaks a rule, they flag it.

Bug Prospector checks what your code assumes — it finds logic that compiles and runs fine today but breaks when a real user does something unexpected. 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?

Auditors find code that looks wrong. Bug Prospector finds code that looks right but behaves wrong.

7 Analysis Lenses

#	Lens	What It Finds
1	Assumption Audit	Implicit assumptions that break under real-world conditions
2	State Machine Analysis	Unreachable states, simultaneous states, interrupted transitions
3	Boundary Conditions	Zero/one/max values, empty collections, off-by-one errors
4	Data Lifecycle Tracing	Data created but never cleaned up, stale displays, orphaned references
5	Error Path Exerciser	Error paths that leave UI stuck, swallow errors, or lose user data
6	Time-Dependent Bugs	Timezone issues, rapid-tap duplicates, slow network, first-launch-after-weeks
7	Platform Divergence	Code that works on Apple Silicon but fails on Intel, OS version gaps

Install

claude plugin add Terryc21/bug-prospector

Or clone and install locally:

git clone https://github.com/Terryc21/bug-prospector.git
claude plugin install ./bug-prospector

Usage

/bug-prospector                    # Interactive — choose scope and lenses
/bug-prospector all                # Full 7-lens scan on recent changes
/bug-prospector quick              # Quick 3 lenses (Assumptions + Errors + Boundaries)

Output

Reports are written to .agents/research/YYYY-MM-DD-bug-prospector-*.md with:

• Issue Rating Table (Urgency, Risk, ROI, Blast Radius, Fix Effort)
• Detailed findings with current code and suggested fixes
• Fragile code warnings (works now, may break later)
• Already-guarded instances (reference)

Terminal-adaptive tables: Detects terminal width before rendering. Wide terminals (160+ columns) get the full 8-column table inline. Narrow terminals get a compact 4-column table with the full table written to the report file.

Fix Workflow

After the report, you can fix bugs immediately. Fixes are grouped into phases:

• "Fix all bugs now" — Phase-by-phase with a confirmation gate before each phase. Opt out of remaining gates at any time.
• "Fix selected bugs" — Pick specific bugs, confirm once, then all selected are fixed.
• "Create implementation plan" — Phased plan without code changes.
• "Report is sufficient" — Just the report.

When to Use

Situation	Recommended Lenses
Pre-release audit	All 7
After adding a new feature	Assumptions + State + Errors
After a crash report	Boundaries + Errors + Platform
Debugging intermittent failures	State + Time
New platform support	Platform + Boundaries
Data model changes	Data Lifecycle + Assumptions

How It Works

For how Bug Prospector differs from pattern-based tools (linters, compiler warnings, code review), and how it pairs with Workflow Audit, see How It Works.

See Also

• Workflow Audit — Audit SwiftUI user workflows for dead ends and UX friction
• Xcode Workflow Skills — Full 22-skill suite (includes both)

License

MIT