Find and Fix Bugs

Contract

Prereqs:

• Run inside the target git repo.

• rg

  available on

  PATH

  for codebase scanning.

• git

  and

  gh

  available on

  PATH

  , and

  gh auth status

  succeeds.

• $AGENT_KIT_HOME/scripts/kit-tools.sh

  available for helper commands (recommended).

Inputs:

• Optional bug report (repro steps, expected vs actual, environment); otherwise autonomous discovery.

Outputs:

• An issues list (per

  references/ISSUES_TEMPLATE.md

  ), a fix branch, commits, and a GitHub PR.

Exit codes:

• N/A (multi-command workflow; failures surfaced from underlying commands)

Failure modes:

• Cannot reproduce or insufficient input to confirm impact (record as uncertainty rather than guessing).
• High-risk changes (auth/billing/migrations) should halt or be skipped per guardrails.
• Missing tooling (

  rg

  /

  git

  /

  gh

  ) or insufficient repo permissions.

Setup

• Load commands with

  source $AGENT_KIT_HOME/scripts/kit-tools.sh

Trigger

Use this skill when the user asks to find or fix bugs, or when no concrete issue is provided and you are asked to proactively discover issues.

Intake rules

• If the user provides a bug report: ensure reproduction steps, expected vs actual, and environment. Ask only for missing details.
• If the user provides no input: do not ask; proceed autonomously.

Discovery

• Scope scanning to tracked files only (ignore untracked files).
• Use

  rg

  to scan for bug-prone patterns (TODO, FIXME, BUG, HACK, XXX, panic, unwrap, throw, catch, console.error, assert).
• Exclude generated, vendor, or codegen directories when present (node_modules, dist, build, vendor, .git, gen, generated, codegen).
• Keep scan rules general; do not add repo-specific patterns.
• Do not rely on grep results alone; use LLM analysis to confirm plausibility and impact.
• Produce an issues list using

  references/ISSUES_TEMPLATE.md

  .
• Use the ID format

  PR-<number>-BUG-###

  (example:

  PR-128-BUG-001

  ). If the PR number is not known yet, use

  PR-<number>

  as a placeholder and update after PR creation.
• For project-specific skills, consider adding a minimal repro script requirement; see

  references/REPRO_GUIDE.md

  .

Context window management

• Prioritize scanning changed files and adjacent code before wider searches.
• If

  rg

  results are large, process in batches (for example: 20-50 hits per batch).
• Stop after enough high-confidence issues are identified to proceed with a fix.

Selection

• If user input exists, fix that issue.
• If autonomous, fix the single most severe or highest-confidence issue.
• Only fix multiple issues when they share the same root cause and the diff remains small.
• Severity levels are fixed: critical, high, medium, low.

Severity rubric

• critical: security exploit, auth bypass, data loss/corruption, or production outage
• high: frequent crash, major feature broken, or incorrect core outputs
• medium: incorrect behavior with workaround, edge cases, or performance regression
• low: minor bug, UX issue, or noisy logs without functional impact

Confidence rubric

• high: clear reproduction or strong evidence, root cause identified, fix is validated
• medium: likely issue with partial evidence, root cause inferred, fix is plausible
• low: speculative issue, weak evidence, or no repro path

High-risk guardrails

• Do not auto-fix changes involving auth, permission/authorization, payment/billing, migration, or infrastructure/deployment.
• If autonomous and the top issue is high-risk, record it and move to the next eligible issue. If all issues are high-risk, stop after reporting.

Fix workflow

1. Create a new branch:

   fix/<severity>-<slug>

   using the fixed severity levels.
2. Implement the fix with minimal scope; avoid refactors.
3. Add or update tests when possible; run lint/test/build commands when present (see Validation commands). If validation fails, follow Retry policy.
4. Update the issues list with status.

Validation commands

• package.json scripts:

  lint

  ,

  test

  ,

  build

  (npm, pnpm, yarn, or bun)
• Makefile targets:

  lint

  ,

  test

  ,

  build

• Justfile targets:

  lint

  ,

  test

  ,

  build

• Taskfile targets:

  lint

  ,

  test

  ,

  build

• Language defaults when applicable:

  go test ./...

  ,

  pytest

  ,

  cargo test

  ,

  mvn test

  ,

  gradle test

  ,

  dotnet test

Retry policy

• If validation fails, fix based on error output and retry up to 2 times.
• After 2 failed attempts, stop and report the failure with the last error output.

Commit

• Use the

  semantic-commit

  skill to generate a Semantic Commit message.
• Prefer a single commit unless there is a clear reason to split.

PR

• Use

  gh pr create

  and write the body using

  references/PR_TEMPLATE.md

  .
• Set the PR title to the primary issue or a short summary of the fix. Do not reuse the commit subject. Capitalize the first word.
• Replace the first H1 line in

  references/PR_TEMPLATE.md

  with the same PR title.
• The PR must include:
  • Issues found (including those not fixed)
  • Fix approach
  • Testing results or "not run"
• Include the issues list in the PR body.
• Use

  scripts/render_issues_pr.sh --pr

  (or

  --issues

  ) to generate templates quickly.

Output and clarification rules

• Use

  references/OUTPUT_TEMPLATE.md

  as the response format.
• The response must include, in order:
  1. Issues list

  2. git-scope

     output
  3. Tests run (commands and results)
  4. PR link