# Repo Bug Finder

> Use when asked to find Bugs, uncover more repository defects, audit one or many repos for security, reliability, data-integrity, recovery, permission, or architecture risks, or continue high-recall static Bug discovery.

- Skill: `aiden0z/repo-bug-finder` (Agent Skill, multi-file: 55 files)
- Install (CLI): `npx skillmds@latest add aiden0z/repo-bug-finder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aiden0z/repo-bug-finder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: aiden0z (https://skillmd.com/u/aiden0z)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aiden0z/repo-bug-finder

---


# Repo Bug Finder

## Purpose

Find more real Bugs by giving the LLM the densest useful code surface, then labeling evidence strength honestly. This skill is discovery-only: it builds profiles, probes, context packs, triage records, and readiness data. Final Bug records and HTML reports belong to the `package` subskill.

## Core Principle

Scripts retrieve facts; the LLM judges semantics. Do not grow a large hard-coded vulnerability library. Use scripts to expose repository shape, entry points, risky primitives, siblings, and local context, then ask the LLM to plan repo-specific probes from that profile.

Discovery is mode-driven. The agent must not stay in the same discovery mode for more than two consecutive rounds unless that mode yields a new confirmed/probable finding family. Grep, optional local Semgrep-compatible scanning, context packs, and direct reads are tools inside modes, not modes by themselves.

Semgrep is an optional third-party local CLI accelerator, not a dependency. Use only local `semgrep scan` with skill-owned rules when it is already installed and allowed by the user's policy. Do not require Semgrep, do not log in, do not use Semgrep AppSec Platform, `semgrep ci`, Registry rules, Pro rules, managed policies, or result upload. If Semgrep is unavailable or inappropriate, continue with grep/Python AST fallback and Deep Flow analysis.

## Methodology Contract

The required discovery method is now a three-layer state machine:

```text
Profile
-> State machine selects mode
-> Harvest / Amplify / Deep Flow / Evidence Hardening
-> Discovery Readiness
-> Next mode recommendation
-> Package only when requested or required modes are complete
```

The layers are:

- **Harvest**: early Bug harvest, Fast Scout, optional local Semgrep Scout when available/policy-approved, direct-read anchors, low-hit precise packs, and config/CLI/deploy/frontend/scheduler quick passes. Output candidates freely; do not wait for perfect package evidence.
- **Amplify**: candidate upgrade, zero-record repo or zero-surface sweep, pattern amplification across sibling endpoints/repos, optional local Semgrep-compatible family scans, and R2 hardening. A confirmed/probable family should trigger amplification.
- **Deep Flow**: mandatory business-flow analysis for money, lifecycle, permissions, files, async jobs, retries, cleanup, and state machines. Grep or local scanner anchors may locate entry points, but the LLM must read and explain the flow.

Architecture signal, pattern seed, family, optional scanner anchors, and evidence debt synthesis are recall amplifiers. They preserve high-recall leads without replacing Bug discovery, skipping LLM planning, or creating final Bugs by themselves.

This is not a loose suggestion. Do not replace it with free-form browsing, a grep-first checklist, direct agent exploration, or final report writing. Universal patterns may seed retrieval only after profiles exist and the LLM has turned them into repo-specific probes. Fast Scout and optional local scanner scout are allowed early because they produce untriaged anchors, not Bug verdicts.

## Workflow

1. Initialize a clean dated workspace with `scripts/init_bug_workspace.py --project <name> --base-dir <parent-dir>`. Use `--workspace <workspace>` only when the user explicitly wants a custom or existing workspace path.
2. Freeze the repository roster with `scripts/discover_repositories.py /path/to/repos --workspace <workspace>`. `--base-dir /path/to/repos` is accepted as a compatibility alias for the source root.
3. Build repository profiles with `scripts/profile_repositories.py`, including neutral `structure_map` observations plus compact `work/repo-profiles/summary.json` and `index.md` for large-repo planning. Immediately run `scripts/update_progress_ledger.py --phase profiling --workspace <workspace>` so later quality gates have the required phase history.
4. Read `references/llm-risk-planning.md`; perform Native Semantics Fanout from detected languages/frameworks/surfaces. The LLM should derive repo-specific invariants and falsifiers from profile facts, not from a hard-coded vulnerability library.
5. Run `scripts/generate_fast_scout_plan.py --workspace <workspace>` after profiles and before broad packs. Fast Scout outputs `work/risk-plans/fast-scout.json` anchors with `verdict: untriaged-anchor`; anchors are selected round-robin across repos so early attention is broad.
6. Run `scripts/plan_invariant_matrix.py --workspace <workspace>` to create profile-derived untested invariant rows. Matrix rows are planning prompts, not Bug verdicts.
7. Run `scripts/run_semgrep_scout.py --workspace <workspace>` only when Semgrep is installed and local policy allows third-party CLI use. If it is unavailable or not allowed, note the optional install path only as policy-dependent and continue with grep/Python AST fallback. Scanner hits are untriaged anchors only.
8. Run `scripts/deep_flow_plan.py --workspace <workspace>` and reserve early attention for required deep flows. For <=3 repos, deep flow starts in round 1 or 2; for larger groups, sample the highest business-priority repos.
9. For promising Fast Scout, local scanner, or direct-read anchors, create real ad-hoc packs with `scripts/create_ad_hoc_context_pack.py`; do not use `direct-read::...` pseudo refs for package-ready evidence.
10. Have the LLM mine repo-specific structure patterns from the profiles, Fast Scout anchors, invariant matrix, architecture signals, and prior sufficiency gaps, then write repo-specific probes with `profile_coverage`. Load `references/probe-schema.md` before writing probe JSON. For repo groups or bounded test rounds, `profile_coverage` must include per-repo `repos_without_probe_reasons` and, when applicable, `repos_without_context_pack_reasons`; a single generic `coverage_notes` sentence is not enough. Structure patterns are hypotheses for retrieval, not Bug verdicts.
11. Write round probes to a named file such as `work/risk-plans/probes-<round>.json` (for example, `probes-round-1.json` or `probes-test-round-1.json`), then run `scripts/build_context_packs.py --probes <that-file> --round-id <round>`. `work/risk-plans/probes.json` is allowed only as a temporary scratch alias. Use `repo` for one target repo or `repos` for a bounded multi-repo probe; omit both only when intentionally running across the whole roster. Probe `queries` are case-insensitive literal substrings by default; prefix a query with `regex:` when using regex syntax such as `|`, `\s`, `.*`, or escaped characters. If every pack has zero hits, or if the builder prints query/probe warnings, fix the probe file and rerun the same round with `--replace-round` before triage. Keep probe files compact: for bounded tests or early rounds, prefer 8-20 high-value probes and split additional work into the next named round instead of hand-writing a huge JSON file. `work/context-packs/index.json` is cumulative by default. If re-running the same round/probe file after an interrupted or bad run, use `--replace-round` instead of creating duplicate suffixed packs.
12. Run `scripts/score_context_packs.py --workspace <workspace>` before each triage pass. Use the scored queue to choose high-utility, diverse packs; do not discard low-scoring packs.
13. Triage context packs using `references/triage-readiness.md` and `references/proof-bundle.md`; cite packs with `source_packs`, or add `pack_reviews` for reviewed packs with no findings. Use the exact triage schema keys from the reference (`id`, `priority`, `status`, `confidence`, `missing_gates`, and the five core evidence fields). Do not substitute `record_id`, `priority_hint`, `evidence_level`, or other ad-hoc aliases in triage files. Write small triage batches, normally no more than 8-12 reviewed packs per file, run `scripts/lint_triage_files.py --workspace <workspace>` on the batch, then merge and validate before continuing.
14. Run adversarial R2 for P1/P2 confirmed, probable, and candidate records before promoting them into clean package-ready status. If R2 is written inside `false_positive_review`, run `scripts/normalize_r2_evidence.py --workspace <workspace>` before merge.
15. Run an almost-missed recall pass: recover candidates hidden in `pack_reviews`, split variants by endpoint/repo/resource/fix boundary, and sweep P3/P4 reliability, leakage, DoS, config, logging, frontend sink, and business-flow leads.
16. Run `scripts/update_progress_ledger.py --phase <phase> --workspace <workspace>` before the first quality gate if the current phase has not been recorded. The ledger needs at least profiling and triage/recall snapshots for validation to pass.
17. Run `scripts/run_discovery_quality_gate.py --workspace <workspace>` after triage and again after any post-gate edit to triage, packs, probes, or evidence fields. This sequentially merges readiness, consolidates families, runs zero-record/candidate/pattern/aggregate checks, synthesizes architecture signals, extracts pattern seeds, builds evidence debt, validates, reviews sufficiency, and recommends next mode. The last quality-gate JSON must reflect the final artifact state. Do not run these quality scripts as parallel tool calls; some agent runtimes cancel sibling calls after one warning/error.
18. If you run the quality scripts manually instead of the helper, run them sequentially in the same order as `run_discovery_quality_gate.py`, and continue through sufficiency and next-mode even if validation reports recall/evidence debt.
19. Validate discovery with `scripts/validate_discovery.py --require-readiness`; use `--strict-evidence` only before packaging and `--require-complete-coverage` only before claiming complete coverage.
20. The next-mode recommendation from `scripts/recommend_next_discovery_mode.py` is the default next action when the user says "continue".
21. Tell the user whether readiness is a partial snapshot or complete coverage, include scope, package-ready-by-status, clean package-ready, family/backlog counts, architecture-signal counts, pattern-seed counts, evidence-debt counts, deep-flow coverage, and the human-readable sufficiency recommendation. Use the machine decision code only as supporting detail when useful.
22. Use `subskills/package` only after discovery readiness exists and the user wants final Bug files, indexes, handoff materials, or an HTML report.

Run `scripts/update_progress_ledger.py --phase <phase>` after every major phase and relay the printed counts to the user.

## Discovery Artifacts

The discovery workspace uses this shape:

```text
<workspace>/
  work/
    repo-roster.json
    repo-profiles/
    risk-plans/
      fast-scout.json
      fast-scout.md
      invariant-matrix.json
      invariant-matrix.md
      pattern-seeds.json
      pattern-seeds.md
    context-packs/
      triage-queue.json
      triage-queue.md
    triage/
    discovery-readiness.json
    discovery-readiness.md
    finding-families.json
    finding-families.md
    architecture-signals.json
    architecture-signals.md
    evidence-debt.json
    evidence-debt.md
    discovery-next-mode.json
    discovery-next-mode.md
    zero-record-repos.json
    candidate-upgrade-queue.json
    pattern-amplification-plan.json
    quality/
      discovery-quality-gate.json
      discovery-quality-gate.md
      aggregate-finding-validation.json
    semgrep/
    progress-ledger.jsonl
  submit/
    quality/
```

Discovery must not write `submit/findings/BUG-*` files or `submit/bug-audit-report.html`.

## Evidence Levels

- `confirmed`: code evidence, trigger path, failure mode, affected resource, and impact are concrete.
- `probable`: code evidence, failure mode, affected resource, and impact are concrete; only trigger path may be hypothesized.
- `candidate`: any non-trigger core field is missing, or more than one field is missing.
- `refuted`: the code path is unreachable, generated-only, sanitized, test-only, or otherwise contradicted by evidence.

Confirmed and probable records are package-ready by status. Candidates stay visible in readiness/backlog. Refuted records stay visible long enough to explain why they were dropped.

Readiness reports two package-ready counts:

- `package_ready_by_status`: all confirmed + probable records.
- `package_ready_clean`: confirmed/probable records whose source packs are indexed, whose schema/package-blocking debt is absent, and whose P1/P2 records have adversarial R2 evidence. Use this count for packaging decisions.

## Completion Handoff

When `validate_discovery.py --require-readiness` passes, do not end with only "discovery complete." Give the user a short handoff:

- `work/discovery-readiness.json` is ready.
- `work/discovery-sufficiency.json` is ready.
- Context pack coverage is partial or complete.
- Report scope: repos in scope, probe repos, context-pack repos, triaged packs, saturated packs, and uncovered repos when present.
- Count confirmed, probable, candidate, refuted, package-ready records, and recall backlog.
- Distinguish `package_ready_by_status` from `package_ready_clean`.
- Count architecture risk signals and name the highest-value next probes when signals exist.
- Count pattern seeds and remind the user that seeds must be turned into repo-specific probes by LLM planning.
- Count evidence debt separately from package-ready findings. Evidence debt does not block continued discovery; it only names work needed before packaging affected records.
- State whether the almost-missed recall pass recovered candidates or variants.
- State required/completed deep-flow count. If required deep flows are incomplete, call the snapshot a pattern-scan snapshot, not sufficient discovery.
- State the next forced mode from `work/discovery-next-mode.json` when the user wants to continue.
- State the human-readable sufficiency recommendation from `review_discovery_sufficiency.py` first. Avoid leading with raw machine codes like `continue-high`; those belong in `work/discovery-sufficiency.json`.
- State validation as one of: `passed without warnings`, `passed with recall/evidence debt`, or `failed`. Do not collapse warnings into "success"; name the debt that blocks packaging.
- If the recommendation says more discovery is strongly recommended or likely worthwhile, lead with the next recall round before asking about packaging.
- Say that final Bug records and HTML report are generated by `repo-bug-finder:package`.
- Ask whether to continue recall or run the package subskill now.

Do not auto-package unless the user already requested final reports or packaging.

## ⛔ BLOCKING GATES

- Do not package during discovery.
- Do not skip the method contract: profile, LLM plan, retrieval/context packs, triage, R2, readiness.
- Do not run Fast Scout before profiles exist, and do not treat Fast Scout anchors as Bug verdicts.
- Do not start from a fixed vulnerability checklist before repo profiles exist.
- Do not embed Bug verdicts in profiles; scripts expose neutral structure and the LLM infers repo-specific patterns.
- Do not call a scanner hit a Bug without LLM triage.
- Do not use generic pattern volume as proof of risk.
- Do not claim thorough codebase understanding from profile reads alone; call it profile-level planning coverage until context packs and triage support stronger claims.
- Do not hide missing gates; name them.
- Do not claim complete coverage unless every context pack is covered by `source_packs` or `pack_reviews`.
- Do not shrink exploration just to make validation pass; untriaged packs are allowed as visible recall backlog.
- Do not treat "not package-ready" as "not a lead"; preserve code-anchored candidates.
- Do not treat a low triage score as a reason to discard a pack; scores only order attention.
- Do not drop direct-read or incomplete leads solely because they have evidence debt; record the debt and keep exploring.
- Do not keep chasing one family by inertia; use finding families, invariant matrix, and triage queue to reserve attention for new Bug families.
- Do not use `direct-read::...` pseudo refs as clean package-ready evidence; create an ad-hoc context pack or attach an existing indexed pack.
- Do not mark P1/P2 records clean package-ready without adversarial R2 evidence.
- Do not over-merge variants across repos, endpoints, affected resources, owners, or fix boundaries.
- Do not present architecture risk signals as standalone Bugs; every signal must cite readiness record IDs, code anchors, or source packs.
- Do not feed pattern seeds directly into `build_context_packs.py`; the LLM must convert seeds into repo-specific probes first.
- Do not claim complete process execution unless `validate_discovery.py` passes and `work/progress-ledger.jsonl` has phase snapshots.
- Do not run readiness, validation, sufficiency, and next-mode scripts as parallel tool calls. Use `scripts/run_discovery_quality_gate.py` or sequential commands so one validator warning does not cancel the rest.
- Do not rely on generic `coverage_notes` to explain unprobed repos. Large or bounded multi-repo runs need per-repo skip reasons in `profile_coverage.repos_without_probe_reasons` and, if context packs are intentionally omitted, `profile_coverage.repos_without_context_pack_reasons`.
- Do not write probes made only of broad signatures like `def `, `class `, `import`, `ViewSet`, `APIView`, or `return`. Pair source/sink/state/guard terms or use narrower globs before building packs.
- Do not read historical audit packages as comparison data unless the user explicitly asks. Current source is the authority.
- Do not stay in one discovery mode for more than two consecutive rounds unless it yields a new confirmed/probable family.
- Do not keep using grep/rg as the main action for three consecutive steps; switch to optional local scanner scout when allowed, candidate upgrade, pattern amplification, or deep-flow analysis.
- Do not call Semgrep or any scanner hits Bugs. Scanner output is only anchors that require LLM data-flow review and R2 before promotion.
- Do not require Semgrep installation, account login, cloud upload, Registry rules, Pro rules, or managed platform features.
- Do not mark aggregate/systematic findings confirmed/probable without representative trigger chains.
- Do not recommend packaging as the primary next action while required deep-flow analysis is incomplete, unless the user explicitly asks to package a partial snapshot.

## Read Next

- `references/discovery-workflow.md`
- `references/repo-profile.md`
- `references/llm-risk-planning.md`
- `references/probe-schema.md`
- `references/context-packs.md`
- `references/proof-bundle.md`
- `references/architecture-signals.md`
- `references/triage-readiness.md`
- `references/evidence-levels.md`
- `references/risk-taxonomy.md`
- `references/process-compliance.md`
- `scripts/summarize_profile_patterns.py` when compact profile summaries need regeneration
- `scripts/recommend_next_discovery_mode.py` after each readiness merge to decide the next mode
- `scripts/deep_flow_plan.py` before claiming discovery sufficiency
- `subskills/package/SKILL.md` when packaging is requested