Bug Hunt

Fix-and-verify loop with atomic commits, regression test generation, and tiered verification.

Before anything else: read $HOME/.agentic-workflow/toolkit/skills/_preamble.md and follow it (skill index, provider capability map, bootstrap check, session context). Run its Session Close section when this skill finishes.

Step 1: Parse Arguments

Parse the argument string for:

• Tier flag: --tier quick, --tier standard, or --tier exhaustive. Default: standard.
• --from-report <path> --item N — entry from a /bugReport report: Read <path> and take row N of its ## Bugs table as the bug description (severity, file, line, description). No manual re-description needed.
• --from-investigation <path> — entry from a /rootCause handoff (investigations/<slug>/handoff.md): Read <path> and adopt its root cause, module boundary, and repro command/journey. Skip re-deriving anything the handoff already answers in Steps 2–3.
• --depth N — dispatch-chain depth guard (default 0). If N ≥ 2, do not dispatch any sub-skill from this run — report instead. When dispatching, pass --depth N+1.
• Bug description or test command: Everything after the flags (or the entire argument if no flag).

Tier definitions:

Tier	Verification scope
quick	Lint + typecheck only
standard	Specific test file + related test files
exhaustive	Full test suite + additional edge case tests

Step 2: Reproduce

Confirm the bug exists before attempting a fix.

1. Detect the runner per skills/_shared/test-runner-detection.md (sets TEST_CMD). An undetected runner is "n/a" — fall back to the app path below; missing tooling is never itself the bug.
2. If argument contains a test command (e.g., npm test -- path/to/test), run it directly.
3. If argument is a description, search files to find related test files and list every candidate test first (file + why it matched) before running any. Then run the candidates, best match first.
4. Capture the failure output. If no candidate fails, do NOT conclude non-reproduction yet:
   • Show the full candidate list you tried.
   • For user-facing symptoms, try the app path: Invoke skill verify-app with args --yes --journey <repro steps from the description>.
   • Only after both routes pass, Ask the user whether they can provide more detail / a failing command, or wants to stop.

Step 3: Locate

Find the bug in the source code.

1. Search files for code related to the failure — error messages, function names from stack traces, relevant module paths.
2. Spawn a subagent (explore) to search the codebase if the initial search is insufficient.
3. Read all relevant source files. Trace the logic to identify the defect.

Step 3.5: Dark Factory (optional)

Follow skills/_shared/dark-factory.md — the gate (CD12), the route/infer/verify flow, and the bugHunt fix objective template are all preserved there. Fill the template with the root cause from Step 3 and the failing command from Step 2:

SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
cat "$SHARED_DIR/dark-factory.md"

• Gate disabled or config absent ⇒ skip silently to Step 4 (don't mention dark factory).
• Delegated fix verified by the host (re-run TEST_CMD per the shared flow) ⇒ commit it as in Step 4.2, then continue at Step 5 and Step 6 — a dark-factory fix never skips the regression test or tier verification.
• Unavailable, refused, or failed verification ⇒ manual Step 4.

Step 4: Fix

Implement the fix and commit atomically.

1. Edit the source file(s) to fix the bug. Keep changes minimal — fix only the identified defect.
2. Commit the fix:

   git add <changed-files>
   git commit -m "fix: <short description of what was fixed>"

Step 5: Generate Regression Test

Write a test that guards against this bug recurring.

1. Identify the correct test file. If a related test file exists, add the test there. Otherwise, create a new test file following the project's test conventions.
2. Write a test that:
   • Would fail on the original buggy code
   • Passes on the fixed code
   • Tests the specific edge case or condition that triggered the bug
3. Commit the test:

   git add <test-files>
   git commit -m "test: regression test for <short description>"

Step 6: Verify by Tier

Detect TEST_CMD per skills/_shared/test-runner-detection.md (re-detect in each bash block — shell state does not persist). Undetected tooling reports "n/a", never a failure.

Tier: quick

Lint + typecheck only, using the project's configured tools (JS example: npm run lint || npx eslint ., npm run typecheck || npx tsc --noEmit; use the detected stack's equivalents otherwise). Unconfigured ⇒ "n/a".

Tier: standard

Run the originally failing test, plus related test files (same directory or importing the fixed module): $TEST_CMD <test-file> then $TEST_CMD <related-test-files>.

Tier: exhaustive

Run the full suite ($TEST_CMD), write and run any additional edge-case tests you identify, and Step 6.5 is mandatory for user-facing fixes.

Step 6.5: Verify in the running app (user-facing fixes)

If the fix touches user-facing code (routes, components, views, templates, styles):

Invoke skill verify-app with args --yes --journey <the repro steps from Step 2, as the journey>

• Recommended at standard tier; mandated at exhaustive tier — do not report fixed there without it.
• Record the resulting evidence pack (skills/_shared/evidence-pack.md) for the report:

  SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
  source "$SHARED_DIR/repo-slug.sh"
  ls -1dt "$AW_DIR/verification/"*/ 2>/dev/null | head -1

• A FAIL verdict in the pack counts as verification failure → Step 7.

Step 7: Loop on Failure

If verification fails:

1. Persist and check the iteration counter (survives context loss — never track it only in your head):

   SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
   source "$SHARED_DIR/repo-slug.sh"
   mkdir -p "$AW_DIR/qa"
   COUNTER_FILE="$AW_DIR/qa/.bughunt-attempts-<slug>"
   ATTEMPT=$(( $(cat "$COUNTER_FILE" 2>/dev/null || echo 0) + 1 ))
   echo "$ATTEMPT" > "$COUNTER_FILE"
   echo "attempt $ATTEMPT/3"

   If ATTEMPT ≥ 3 (max), skip to Step 8 with status unfixed.
2. Analyze the new failure. Read the output, determine if it is the same bug or a new issue introduced by the fix.
3. Go back to Step 4. Revert the broken fix if necessary (git revert HEAD or edit), then re-implement.

Step 8: Write QA Report

Write the report to $HOME/.agentic-workflow/$REPO_SLUG/qa/{timestamp}-{slug}.md where:

• {timestamp} is YYYYMMDD-HHmmss format
• {slug} is a short kebab-case summary of the bug (max 40 chars)

Report format:

# Bug Hunt Report: {short description}

**Date:** {ISO timestamp}
**Tier:** {quick | standard | exhaustive}
**Status:** {fixed | unfixed}
**Attempts:** {n}/3

## Bug Description

{Original bug description or failing command}

## Root Cause

{What was actually wrong and why}

## Fix Summary

{Description of the fix}

### Changed Files
- `{file}:{line}` — {what changed}

### Commits
- `{sha}` — fix: {description}
- `{sha}` — test: regression test for {description}

## Regression Test

**File:** `{test-file-path}`
**Test name:** `{test name or describe block}`

## Verification Results

**Tier:** {tier}
**Result:** {pass | fail}

{Command output summary}

## Evidence

- **Runner:** {TEST_CMD or "n/a — no runner detected"}
- **Verification output:** {key lines from the tier run}
- **Evidence pack:** {`~/.agentic-workflow/<repo-slug>/verification/<run-id>/pack.json` from Step 6.5, or "n/a — not a user-facing fix"}
- **Pack verdict:** {PASS | WARN | FAIL | n/a}

Step 9: Report to User

Bug hunt complete.

Status: {fixed | unfixed}
Tier: {tier}
Attempts: {n}/3
Root cause: {one-line summary}
Fix: {commit sha} — fix: {description}
Test: {commit sha} — test: regression test for {description}
Report: ~/.agentic-workflow/<repo-slug>/qa/{filename}
Evidence: {pack path or "n/a"}

Sub-skill Dispatch

If the fix-and-verify loop ends with status unfixed (all hypotheses exhausted) and the depth guard allows (--depth < 2):

Invoke skill bugReport with args --depth <N+1> <scope>

Do not invoke bugReport on success — bugHunt's own Step 8 report is sufficient. At depth ≥ 2, report only.

Next steps

• /review — verify fixes pass code review
• /shipRelease — if all bugs are fixed and tests pass
• /weeklyRetro — if this was part of a larger debugging push