Hunt Bugs Adversarially Across Any Codebase

Bugs Are Annoying guides an adversarial QA pass that actively looks for failure conditions in code. It applies across languages and focuses on functional, security, and correctness problems rather than formatting or style preferences. The process examines actual code and traces interactions across file boundaries, where a changed function, field, or type can disagree with its callers.

The hunt starts by defining scope. A named file or folder establishes the boundary; otherwise the reviewer confirms whether to inspect the whole codebase, changes against the main branch, or a specific area. It maps entry points, data flow, and call relationships before reading relevant files in full. Critical paths are traced from input to output, followed by mental simulation with nulls, empty values, negative numbers, large inputs, duplicates, concurrency, malformed inputs, and missing fields.

The taxonomy covers logic, null and type safety, edge cases, error handling, concurrency, security, resource leaks, cross-file consistency, API contracts, state management, unreachable code, performance, dependencies, and documentation that disagrees with behavior. Every category is checked actively. A discovered pattern prompts a search for repeated instances rather than assuming it occurs only once.

Use this skill for requests to find bugs, audit correctness, check errors, or assess whether code is solid. It is a static-analysis and mental-tracing workflow: it cannot execute code or infer undocumented business intent. Reviewed coverage is bounded by inspected files and available requirements, and a clean report cannot establish that no bugs exist.

Generated and dependency directories are normally excluded from the authored-code pass. Lockfiles are inspected for dependency checks, and generated or runtime evidence can still require tracing to its owning source. Before logging a finding, check nearby validators, wrappers, types, guards, and callers. If confirmation depends on code outside scope, record that uncertainty. Keep secrets and personal information out of the report.

The output is bugs.md at the project root or relevant audited scope. It records summary counts, severity groups, sequential bug identifiers, exact file-and-line locations, issues, triggering sequences, impact, suggested fixes, confidence where needed, and status. The entry template includes:

- **Status:** Open

Critical findings describe realistic crashes, incorrect results, data loss, or security holes. Intermediate findings cover plausible edge cases or growth-related risks. Normal findings cover smaller correctness problems and defensive gaps. Dormant candidates record activation conditions rather than presenting unreachable behavior as a current production failure.

On repeat runs, read the existing report, recheck open bugs, retain resolved entries with dates, continue identifier numbering, and update counts. A clean pass is recorded too. The hunt suggests fixes without changing code. Fix mode requires an explicit request naming bugs or a severity group; it updates only that scope and preserves original findings in the resolved history.