tools/find-and-fix-bugs.md

Table of Contents

find-and-fix-bugs Skill

Systematically scans a codebase, finds the first real bug/improvement/flaw, confirms with you, then branch-fix-commit-PRs the fix end-to-end.

Running Modes

By default operates in bug mode (runtime errors, data corruption, logic errors, unhandled error states).

You trigger other modes by asking explicitly during invocation:

Mode Trigger phrases What it also flags
Bug (default) (no special phrase) Runtime crashes, type/schema mismatches, logic errors, unhandled errors, dead code that misleads
Quality "code quality", "architecture", "tech debt", "code smells", "refactoring", "structural issues" God objects, circular deps, tight coupling, fragile patterns, dangerous code duplication, missing abstractions
Security "security", "vulnerabilities", "OWASP", "injection", "auth bypass", "data exposure" IDOR, injection (SQL/NoSQL/command/template), secrets in source, XSS, SSRF, weak crypto, enumeration surfaces
Performance "performance", "slow queries", "bottlenecks", "latency", "N+1", "optimization" N+1 queries, missing indexes, unbounded reads, sync blocking on server, waterfall fetches, over-fetching, missing caching/memoization

To combine modes, include both trigger phrases (e.g., "find bugs and security issues").

Workflow (9 phases)

  1. Scan — starts with a general repo analysis before diving in:
    • Reads the directory tree to understand overall structure
    • Checks for prior find-and-fix-analysis.md (if exists, skips already-analyzed areas and avoids re-flagging issues already listed — even if they still appear unfixed, since the fix likely exists in an outstanding PR)
    • Then scans in fixed order: core infrastructure (router, model schemas vs types, API client, auth layer) → service layer (create/update/delete, webhooks, background jobs) → components & pages (error states, null checks, dead code, type coercions)
    • Traces data flows end-to-end — a bug often spans types → schema → service → route handler
  2. Stop at first real finding — reports with file:line, impact, and fix summary
  3. Wait for confirmation — does NOT implement until you say yes
  4. Branch & implement — creates fix/<desc>, refactor/<desc>, or perf/<desc> branch; minimal targeted edit; self-reviews diff
  5. Tests & docs — checks for existing tests, adds new ones if needed; updates docs if misleading
  6. Build verification — runs npm run build
  7. Commit & Deploy — commits as qwestly[bot] (conventional commits: fix:, refactor:, perf:, feat:, docs:), then amends with [skip deploy] and triggers manual vercel deploy if VERCEL_DEPLOYMENT_TOKEN is set
  8. Push & PR — pushes branch, creates PR via gh-as-qwestly
  9. Record & clean up — writes find-and-fix-analysis.md (local-only, NOT committed) so future runs skip analyzed areas and don't re-flag duplicates, then checks out the base branch so the repo is ready for the next run

Prerequisites

gh-as-qwestly (required for PRs as bot)

The PR in Phase 8 is created via gh-as-qwestly so the PR author is the Qwestly GitHub App, not your personal user.

Location: /Users/dominick/bin/gh-as-qwestly or ./scripts/gh-as-qwestly/gh-as-qwestly from workspace root.

If it's missing or broken (no env vars, no key), falls back to GH_TOKEN=<your-token> gh pr create ....

Repo conventions assumed

  • Next.js App Router with TypeScript, Mongoose for MongoDB
  • ApiRouter catch-all pattern for API routes ([[...slug]]/route.ts)
  • Admin routes gated by proxy.ts — don't add redundant isAdmin() checks
  • Mongoose methods only for DB ops (no raw MongoDB updateOne/insertOne)

Vercel manual deployment

The Qwestly bot user is not a member of the Vercel team, so automated deployments from commits are not authorized. After each commit (Phase 7), the workflow:

  1. Checks if VERCEL_DEPLOYMENT_TOKEN is set in the environment
  2. If present, amends the commit message to append [skip deploy] — this tells Vercel to skip the automated deployment that would fail
  3. Runs vercel deploy --prebuilt --token=$VERCEL_DEPLOYMENT_TOKEN to trigger a manual deployment using a personal access token

This env var is user-specific and must be set by the person running the skill. If it's not set, the deploy step is simply skipped.

Key behaviors

  • Minimal user input — only pauses to confirm a finding before implementing, and only for genuinely ambiguous decisions
  • Stops at first finding — doesn't exhaustively scan; fixes one thing per run
  • Never reports: stylistic nitpicks, missing comments, trivial naming, correct-but-unfamiliar code, minor DRY violations, subjective preferences
  • Analysis record (find-and-fix-analysis.md, local-only, NOT committed) persists across runs so you can pick up where you left off. First run captures a structured repo overview (tech stack, directory layout, architectural layers, conventions) so future runs don't need to re-discover the repo structure