opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/brooks-sweep/sweep-guide.md

@@ -0,0 +1,264 @@
+# Brooks-Lint — Full Sweep Guide
+
+Sequential autonomous pipeline: **review → test → debt → audit**. Fixes findings
+in place, iterates until clean or capped, reports residuals. One interaction point:
+Step 0 (pre-flight consent) — after approval the pipeline runs hands-free until Step 8.
+
+Every finding follows the Iron Law: **Symptom → Source → Consequence → Remedy**.
+
+---
+
+### Step 0 — Pre-flight consent gate
+
+**Goal:** State scope, cost, and irreversibility up front; get explicit consent
+once so later steps never have to ask.
+
+0a. Estimate the file count using `git ls-files | wc -l` if in a git repo, or
+   `find . -type f -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/build/*' -not -path '*/dist/*' -not -path '*/vendor/*' -not -path '*/target/*' | wc -l` otherwise. Order-of-magnitude is enough.
+
+0b. Show this notice verbatim with the estimate filled in. Do not paraphrase —
+   the user is agreeing to this exact scope.
+
+   ```
+   ⚠️  /brooks-sweep — Full Repository Sweep & Auto-Fix
+
+   Scope:    Four analysis dimensions run in sequence — PR code decay (R1–R6),
+             test quality (T1–T6), tech debt, architecture. Edits are made in
+             place inside the detected project scope.
+   Estimated files in scope: ~N
+
+   Order:    brooks-review → brooks-test → brooks-debt → brooks-audit.
+             Each dimension scans, queues, and fixes before the next starts.
+
+   Autonomy: Fully autonomous. Safe single-file fixes apply directly. Multi-file
+             fixes that have test coverage AND do not break a public interface
+             also apply directly. High-risk fixes (public API break, cross-module
+             structural change, or no test coverage) are NOT applied — they are
+             recorded in the residual report for human review.
+
+   Iteration: After each dimension pass, modified files + same-module + static
+             consumers are re-scanned. A finding that fails to fix 3 times is
+             retired to the unresolvable set and never re-queued. Non-critical
+             rounds cap at 3 iterations; critical findings iterate until
+             resolved or retired.
+
+   Git impact: The pipeline edits files. It does NOT commit, push, or amend.
+             If you have uncommitted work you want to preserve, commit or stash
+             first.
+
+   Proceed with full autonomous sweep? [Y/n]
+   ```
+
+0c. Parse the reply (first match wins, evaluate rules in order):
+   1. **Hard negation** (`no`, `n`, `abort`, `cancel`, `取消`, `不要`): abort with "Aborted before scan — no files modified."
+   2. **Consent** (`Y`, `yes`, `ok`, `sure`, `proceed`, `go`, `continue`, `好`, `好的`, `行`, `可以`): proceed to Step 1.
+   3. **Soft pause** (`wait`, `hold on`, `等一下`, `等我`, `let me`): acknowledge in one line ("Understood, waiting"), then wait for the user's next message and re-evaluate from rule 1.
+   4. **Question**: answer it, then re-show the notice once and wait for the next reply. If the next reply is not Consent (rule 2) — whether a second question, another pause, or anything else — abort with "Aborted — did not receive consent after clarification."
+
+0d. After consent, do not ask further questions until Step 8.
+
+---
+
+### Step 1 — Scope enumeration and state init
+
+1a. Apply Auto Scope Detection from `../_shared/common.md` if the user did not
+   specify files or a directory. Otherwise honor the user's explicit scope.
+
+1b. Read `.brooks-lint.yaml` from the project root if present. Apply `disable`,
+   `severity`, `ignore`, `focus`, and `custom_risks` per common.md. Record the
+   applied config values and reuse them across all iteration rounds — do not
+   re-read the file in Step 6 even if files were modified.
+
+1c. Initialize pipeline state (persists across all rounds):
+
+   - **`unresolvable`** (set): findings retired after 3 failed attempts — keyed by `(file, line_range, risk_code)`; `signature` breaks ties. Never re-queued.
+   - **`non_critical_rounds`** (int, 0): incremented each round producing Warning/Suggestion; reset on clean round.
+   - **`fix_log`** (list): each fix with file, line range, risk code, description, and outcome (`applied` / `reverted` / `retired`).
+
+1d. Record the final scope file list in the Fix Report output buffer for Step 8.
+
+---
+
+### Step 2 — brooks-review pass (R1–R6 code decay)
+
+Scan every file in scope against all R-series risks defined in
+`../_shared/decay-risks.md`.
+
+2a. For each R-risk, apply its symptom checklist. Record each hit as a finding
+   with: risk code, file + approximate line range, Symptom, Source,
+   Consequence, Remedy, Severity (Critical / Warning / Suggestion), and
+   **Fix-Class** (see Step 2b).
+
+2b. Assign Fix-Class per finding:
+
+   | Class | Criteria |
+   |-------|----------|
+   | **Safe** | Single-file AND fully local: rename a non-exported symbol, extract a constant, remove dead code, add a null guard at a leaf, add a test scaffold for an untested pure function. Any change that modifies or removes an exported symbol is NOT Safe even if in one file. |
+   | **Extended-Safe** | Multi-file but (a) a project test command exists and passes pre-fix, AND (b) the change does not rename, remove, or alter the signature of any publicly exported symbol, AND (c) touches ≤ 5 files in this pass. |
+   | **Residual** | Public API break, cross-service boundary change, no test coverage to fall back on, or remedy ambiguous. NOT applied — carried to the Step 8 residual report. |
+
+2c. Skip any finding that matches an entry in the `unresolvable` set.
+
+2d. Apply every Safe and Extended-Safe fix in this dimension, lowest risk
+   within each severity tier first. For each fix: Edit or Write, then append
+   one row to `fix_log` with outcome `applied`. If two fixes touch overlapping
+   line ranges in the same file, apply higher-severity first, re-read the file,
+   then apply the next.
+
+2e. After all fixes in this dimension, run the project test/lint command if one
+   exists (`package.json` scripts, `pytest`, `cargo test`, `go test ./...`, etc.).
+   If tests fail: revert fixes from this dimension in reverse order one at a
+   time, re-running the test command after each revert, until tests pass.
+   Mark each reverted fix with outcome `reverted` in `fix_log` and promote the
+   finding to **Residual**. If no test command is found, note this once in the
+   report and continue.
+
+2f. Record dimension summary: N scanned, M Safe applied, K Extended-Safe applied,
+   R reverted, P Residual.
+
+---
+
+### Step 3 — brooks-test pass (T1–T6 test decay)
+
+Scan test files (and untested production code) against T-series risks defined
+in `../_shared/test-decay-risks.md`.
+
+Follow the same sub-steps as Step 2 (classify → apply → verify → summarize),
+using T-prefix risk codes. For production files with no test coverage at all,
+record as T5 (Coverage Illusion). A test scaffold that adds a pure-function test is
+**Safe**; adding tests that require new test infrastructure is **Residual**.
+
+---
+
+### Step 4 — brooks-debt pass (tech debt accumulation)
+
+Re-classify R-findings through a debt lens — same symptoms at accumulation scale:
+repeated duplication, layered workarounds, stale `TODO`/`FIXME` clusters, dead
+flags. Score each with **Pain (1–3) × Spread (1–3)**; total 7–9 = Critical,
+4–6 = Warning, 1–3 = Suggestion. Apply a severity bump for pattern-level
+occurrences (isolated Suggestion → 4+ modules Warning).
+
+Follow the same sub-steps as Step 2. Debt findings often span multiple files
+and are more likely to land in Extended-Safe or Residual than Safe.
+
+---
+
+### Step 5 — brooks-audit pass (architecture integrity)
+
+Scan the full scope for architecture-level issues. The dependency-direction
+symptoms (inverted dependencies, circular imports, cross-domain coupling) are
+defined in `../_shared/decay-risks.md` Risk 5 — use that checklist. Step 5
+additionally covers architecture-only concerns that R5 does not: missing
+abstraction layers, god modules, leaked infrastructure inside domain code,
+and seam-boundary violations.
+
+Most architecture findings are **Residual** by definition — they require human
+judgment on module boundaries. A few are Extended-Safe (e.g. extract a shared
+constant used in 3+ modules into a new module that nothing else imports yet).
+Do not auto-refactor module layouts, rename packages, or change public exports.
+
+Follow the same sub-steps as Step 2.
+
+---
+
+### Step 6 — Iteration loop
+
+**Goal:** Re-scan what the fixes touched and converge. Stop on clean round,
+cap, or no progress.
+
+6a. Build the re-scan scope:
+   - every file modified in Steps 2–5 of the current round, PLUS
+   - every file in the same module as a modified file, PLUS
+   - every file that statically imports from a modified file.
+
+   Do not re-scan files whose dependencies were not touched. On monorepos
+   where a "module" may span hundreds of files, narrow the same-module bucket
+   to files that import from or are imported by a modified file (direct
+   dependency graph only).
+
+6b. Re-run Steps 2–5 on the re-scan scope. For each new finding in this round:
+   - If it matches an entry in `unresolvable` → skip.
+   - Else if 🔴 Critical → queue and fix; Critical findings iterate until
+     resolved OR retired (3 failed attempts → `unresolvable`).
+   - Else 🟡 Warning / 🟢 Suggestion → queue and fix, subject to cap below.
+
+6c. Classify the round after all fixes attempted:
+   - **Clean round** (no new findings outside `unresolvable`): pipeline
+     converged → proceed to Step 7.
+   - **Critical-only round**: do NOT increment `non_critical_rounds`; return
+     to 6a.
+   - **Mixed or non-critical round** (any Warning / Suggestion produced):
+     increment `non_critical_rounds` by 1. If it reaches the cap (default 3,
+     or `sweep.max_iterations` from `.brooks-lint.yaml`), proceed to Step 7
+     with remaining non-critical findings recorded as
+     `"Unresolved — iteration cap reached"`. Otherwise return to 6a.
+
+6d. Fix-retry rule: if a single finding fails verification (Step 2e) 3 times
+   across any combination of rounds, retire it to `unresolvable` with reason
+   `"3-retry budget exhausted"` and stop attempting it.
+
+---
+
+### Step 7 — Residual aggregation
+
+Collect everything that was NOT fixed in place, de-duplicated:
+
+- All Residual-class findings from Steps 2–5 (first round + re-scan rounds)
+- All `unresolvable` entries with their retirement reason
+- All iteration-cap residuals from Step 6c
+
+Sort Critical → Warning → Suggestion. Within each severity, list file path,
+risk code, Symptom (one line), Remedy (one line), and the reason it was not
+applied (`public API break` / `no test coverage` / `3-retry budget` /
+`iteration cap`).
+
+---
+
+### Step 8 — Sweep report
+
+Output the final report. Use the standard Report Template from
+`../_shared/common.md` with these additions:
+
+```
+# Brooks-Lint — Full Sweep Report
+Mode: Full Sweep | Scope: <files or directory>
+Config: .brooks-lint.yaml applied (N risks disabled, M paths ignored)   # omit if no config
+
+## Dimension Summary
+| Dimension | Scanned | Safe Applied | Extended Applied | Reverted | Residual |
+|-----------|---------|--------------|------------------|----------|----------|
+| Review (R1–R6) | ... | ... | ... | ... | ... |
+| Test (T1–T6)   | ... | ... | ... | ... | ... |
+| Debt           | ... | ... | ... | ... | ... |
+| Audit          | ... | ... | ... | ... | ... |
+
+## Iteration History
+Round 1: <classification — clean / critical-only / mixed>, <N> new findings
+Round 2: ...
+Stopped at: clean round | iteration cap | no outstanding criticals
+
+## Fix Log
+| # | File | Lines | Risk | Outcome  | Change |
+|---|------|-------|------|----------|--------|
+| 1 | ...  | ...   | R2   | applied  | Extract repeated constant |
+| 2 | ...  | ...   | T4   | reverted | Test regression; promoted to Residual |
+...
+
+## Health Score Delta
+Before: <estimated score>/100  →  After: <estimated score>/100
+(Re-run /brooks-health for an exact recalculation.)
+
+## Residual Items  (<K> not applied)
+<Iron Law entries, sorted Critical → Suggestion, with "Not applied because: ..." line>
+
+## Summary
+- Total findings detected: <N>
+- Fixed this sweep: <M>
+- Residual (needs human review): <K>
+- Unresolvable (3-retry exhausted): <U>
+```
+
+If there are zero residual items and zero unresolvable entries, end with:
+**"Sweep complete — codebase is clean."**
+
+**Mode line in report:** `Full Sweep`

package/bundled-skills/brooks-test/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: brooks-test
+description: "Test quality review drawing on twelve classic engineering books — with primary focus on xUnit Test Patterns, The Art of Unit Testing, How Google Tests Software, and Working Effectively with Legacy Code — that diagnoses structural problems in an existing test suite: brittleness, mock..."
+risk: unknown
+source: https://github.com/hyhmrright/brooks-lint/tree/main/skills/brooks-test
+source_repo: hyhmrright/brooks-lint
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/hyhmrright/brooks-lint/blob/main/LICENSE
+---
+
+# Brooks-Lint — Test Quality Review
+## When to Use
+
+Use this skill when you need test quality review drawing on twelve classic engineering books — with primary focus on xUnit Test Patterns, The Art of Unit Testing, How Google Tests Software, and Working Effectively with Legacy Code — that diagnoses structural problems in an existing test suite: brittleness, mock...
+
+
+## Setup
+
+1. Read `../_shared/common.md` for the Iron Law, Project Config, Report Template, and Health Score rules
+2. Read `../_shared/source-coverage.md` for book-level coverage, exceptions, and tradeoffs
+3. Read `../_shared/test-decay-risks.md` for test-space symptom definitions and source attributions
+4. Read `test-guide.md` in this directory for the test quality review framework
+
+## Process
+
+**If the user has not shared test files or pointed to a test directory:** apply Auto
+Scope Detection from `../_shared/common.md` to determine the review scope before proceeding.
+
+1. Build the test suite map (guide's "Before You Start" section)
+2. Scan for each test decay risk in the order specified (Steps 1–4 of the guide)
+3. Apply the Iron Law and output using the Report Template (Step 5 of the guide)
+
+**Mode line in report:** `Test Quality Review`
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/brooks-test/test-guide.md

@@ -0,0 +1,147 @@
+# Test Quality Review Guide — Mode 4
+
+**Purpose:** Diagnose the health of a test suite using six test-space decay risks.
+Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+---
+
+## Before You Start: Build the Test Suite Map
+
+Before scanning for any risk, map the current test suite structure:
+
+```
+Unit tests:        X files, ~N tests
+Integration tests: X files, ~N tests
+E2E tests:         X files, ~N tests
+Ratio:             Unit X%  :  Integration X%  :  E2E X%
+Coverage areas:    [modules with tests] vs [modules without tests]
+```
+
+If you cannot access test files directly, ask the user **one question** — choose the
+most relevant:
+1. "Which module is hardest to test or has the least coverage?"
+2. "When you make a change, how often do unrelated tests break?"
+3. "Is there a part of the codebase your team avoids touching because it has no tests?"
+
+After one answer, proceed. Do not ask more than one question.
+
+---
+
+## Analysis Process
+
+Work through these five steps in order.
+
+### Step 1: Scan for Test Obscurity
+
+*Scan this first — the most visible risk and the one that determines whether the suite
+is maintainable at all.*
+
+Look for:
+- Read 5–10 test names at random: can each one communicate subject + scenario + expected
+  outcome without opening the test body?
+- Are there tests where a failure gives no clue which behavior broke (multiple assertions,
+  no message strings)?
+- Does any test depend on external state (files, database rows, env variables, shared mutable
+  fixtures) that is invisible from within the test body?
+- Is there a single massive setUp or beforeEach that every test inherits regardless of
+  what it actually needs?
+
+If all test names are clear and setups are minimal → no finding.
+
+### Step 2a: Scan for Test Brittleness
+
+*Brittle tests break on refactors that do not change observable behavior — they test
+implementation, not contracts.*
+
+Look for:
+- Ask (or check git history): did any recent refactor cause test failures with no
+  behavior change?
+- Are there test methods where the name contains "and" or that assert on 3 or more
+  unrelated behaviors (Eager Test)?
+- Do assertions specify mock call order or exact parameter values that are irrelevant
+  to the observable behavior?
+- Are tests coupled to private methods or internal state directly?
+
+If brittleness is systemic (most tests in the file break on a rename) → 🔴 Critical.
+If isolated (1–2 brittle tests) → 🟢 Suggestion.
+
+### Step 2b: Scan for Mock Abuse
+
+*Mock Abuse produces tests that pass regardless of whether the real behavior is correct.
+Scan this separately from brittleness — over-mocking is often the cause of brittleness,
+but it is a distinct problem worth its own finding.*
+
+**Sample 3–5 tests once for both steps 2a and 2b together** — read each test body and
+check brittleness signals and mock-setup ratio in the same pass, then write separate
+findings if both problems are present.
+
+Look for:
+- Is mock setup code longer than the assertion logic in the sampled tests?
+- Are the primary assertions `expect(mock).toHaveBeenCalledWith(...)` rather than
+  assertions on outputs, state, or observable events?
+- Are there methods in production classes that are only called from test files
+  (test-induced design damage)?
+- Does any single test create more than 3 mock objects?
+
+If mock setup-to-assertion ratio exceeds 3:1 → 🟡 Warning.
+If production methods exist only for test access → 🔴 Critical (architecture is being
+distorted by the test suite).
+
+### Step 3: Scan for Test Duplication
+
+Look for:
+- Is the same setup block (same variables initialized the same way) repeated across
+  5 or more test files without a shared helper?
+- Are there multiple tests that pass identical inputs and assert identical outputs
+  with no differentiation (Lazy Test)?
+- Is the same business scenario covered at unit, integration, and E2E level with no
+  difference in what each layer is testing?
+
+If duplication is systemic (10 or more instances) → Critical.
+If localized (3–5 instances) → Warning.
+
+### Step 4: Scan for Coverage Illusion and Architecture Mismatch
+
+Look for Coverage Illusion:
+- Pick the most recently modified core module. Are its error-handling branches and
+  null/boundary inputs covered by tests?
+- Are there legacy areas (old functions, no test files nearby) that are actively
+  being changed?
+- Do the tests assert on side effects (DB writes, events emitted, state transitions)
+  or only on return values?
+
+**Characterization Test check:** If legacy code is being modified without existing tests,
+the team needs Characterization Tests before making the change — not after. Look for
+this pattern and flag it when absent.
+
+A Characterization Test locks in current behavior (right or wrong) so future changes
+do not silently regress it. Template:
+```
+test("characterize: [module].[method] given [input], returns [current output]") {
+  // Call the code under test with realistic inputs
+  // Assert on whatever it currently returns — even if you suspect the output is wrong
+  // Add a comment: "This captures current behavior, not necessarily correct behavior"
+}
+```
+Source: Feathers — Working Effectively with Legacy Code, Ch. 13: Characterization Tests
+
+Look for Architecture Mismatch:
+- Compare the suite map from the start: is the ratio close to 70% unit / 20% integration / 10% E2E?
+- Are high-risk modules tested at higher density than trivial utilities?
+
+**Test suite performance:** A slow test suite is a first-class maintainability risk — it
+breaks the fast-feedback loop and causes developers to skip running tests locally.
+- If the full suite runtime is known and > 10 minutes → 🟡 Warning
+- If the full suite runtime is > 30 minutes or unknown → 🔴 Critical (unknown suite time
+  means nobody is running it regularly)
+- If tests that could be unit tests are integration tests, that is a Performance Mismatch:
+  each misclassified test adds seconds of avoidable wait time
+
+Source: Meszaros — xUnit Test Patterns, Slow Tests (p. 253)
+
+### Step 5: Apply Iron Law, Output Report
+
+Apply the Iron Law format from `../_shared/common.md` to each finding.
+
+Use the standard Report Template. Mode: Test Quality Review.
+Include the Test Suite Map as a code block immediately before the `## Findings` heading, labeled "Test Suite Map".

package/bundled-skills/bug-hunt-swarm/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: bug-hunt-swarm
+description: Parallel read-only multi-agent root-cause investigation for bugs, regressions, crashes, flaky behavior, or unexplained failures. Use when the user asks to investigate a bug, find the root cause, trace a regression, understand why something broke, or wants a ranked diagnosis with the...
+risk: unknown
+source: https://github.com/Dimillian/Skills/tree/main/bug-hunt-swarm
+source_repo: Dimillian/Skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/Dimillian/Skills/blob/main/LICENSE
+---
+
+# Bug Hunt Swarm
+## When to Use
+
+Use this skill when you need parallel read-only multi-agent root-cause investigation for bugs, regressions, crashes, flaky behavior, or unexplained failures. Use when the user asks to investigate a bug, find the root cause, trace a regression, understand why something broke, or wants a ranked diagnosis with the...
+
+
+Investigate a bug with four read-only sub-agents in parallel, then have the main agent rank the likely causes and recommend the fastest path to prove or fix the issue. This skill is diagnosis-first: do not edit files or implement fixes as part of this workflow.
+
+## Step 1: Build the Bug Packet
+
+Start by collecting the smallest useful investigation packet:
+
+1. Symptom
+2. Expected behavior
+3. Actual behavior
+4. Reproduction steps, if known
+5. Scope of impact
+6. Relevant evidence, such as logs, stack traces, failing tests, screenshots, recent diffs, or environment details
+
+Prefer this source order:
+
+1. Direct user description
+2. Explicit files, stack traces, logs, tests, or screenshots provided by the user
+3. Current git changes or recent repo history when the bug appears regression-like
+4. The smallest relevant code path or subsystem surrounding the failure
+
+If the bug report is underspecified, infer a minimal problem statement and say what is still unknown.
+
+Before launching sub-agents, read the closest project instructions and relevant docs for the touched area, such as:
+
+- `AGENTS.md`
+- repo workflow docs
+- architecture, state, routing, schema, or runtime docs for the affected subsystem
+
+## Step 2: Bound the Investigation
+
+Write a short investigation brief for the swarm:
+
+1. What appears broken
+2. What is not yet proven
+3. What part of the system is most likely involved
+4. What evidence already exists
+5. What kind of proof would count as confirmation
+
+Use read-only evidence gathering where useful:
+
+- `rg`, `git diff`, `git log`, `git show`
+- reading logs, crash traces, and config
+- existing test runs or the smallest safe reproduction command
+
+Do not edit files, inject new instrumentation, or implement fixes as part of this skill.
+
+## Step 3: Launch Four Read-Only Investigators in Parallel
+
+Launch four sub-agents when the problem is large or ambiguous enough that parallel investigation helps. For a tiny and obvious issue, it is acceptable to investigate locally instead.
+
+For every sub-agent:
+
+- give the same bug packet and investigation brief
+- state that the sub-agent is read-only
+- do not let the sub-agent edit files, run `apply_patch`, stage changes, commit, or perform any other state-mutating action
+- ask for concise investigation output only
+- ask for: hypothesis, supporting evidence, missing evidence, smallest proof step, and confidence
+- tell the sub-agent to avoid generic code quality feedback, nits, or speculative guesses without evidence
+- tell the sub-agent to send findings back to the main agent only
+
+Use these four investigation roles.
+
+### Sub-Agent 1: Reproduction and Scope Investigation
+
+Clarify the exact failure shape and its boundaries.
+
+Check for:
+
+1. The narrowest reliable trigger
+2. Conditions that make the bug appear or disappear
+3. Expected versus actual behavior at the failure boundary
+4. Whether the impact is local, cross-cutting, deterministic, or flaky
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+### Sub-Agent 2: Code Path and Failure Seam Investigation
+
+Trace the most likely execution path and identify the seam where behavior diverges.
+
+Check for:
+
+1. State transitions, lifecycle edges, or ordering problems
+2. Mismatched assumptions between caller and callee
+3. Data-flow or control-flow breaks
+4. The smallest code region most likely responsible for the failure
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `explorer` for broad tracing, or `reviewer` when a stronger local reasoning pass is more useful
+
+### Sub-Agent 3: Recent Change and Regression Investigation
+
+Look for likely regressors in nearby history or changed contracts.
+
+Check for:
+
+1. Recent diffs that correlate with the symptom
+2. Config, flag, dependency, schema, or migration drift
+3. Partial updates where several entry points should have changed together
+4. Behavior changes that fit the timing of the bug report
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+### Sub-Agent 4: Proof Plan and Observability Investigation
+
+Determine the fastest way to confirm or reject the leading hypotheses.
+
+Check for:
+
+1. The smallest existing test or reproduction that should fail
+2. The most useful current logs, traces, metrics, or assertions
+3. A minimal non-mutating command that could raise confidence quickly
+4. What evidence is missing and how to collect it without broad churn
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+Report only hypotheses that materially improve the odds of finding the real cause. It is better to return two evidence-backed theories than six vague guesses.
+
+## Step 4: Synthesize Ranked Hypotheses
+
+The main agent owns synthesis. Treat sub-agent output as raw investigation input, not final output.
+
+Merge and rank the hypotheses:
+
+- combine duplicates
+- discard weak speculation
+- prefer evidence over elegance
+- separate likely root causes from mere contributing factors
+- keep alternate theories only when they remain plausible
+
+Normalize the surviving hypotheses into this shape:
+
+1. Hypothesis
+2. Supporting evidence
+3. Missing or conflicting evidence
+4. Smallest proof step
+5. Confidence: high, medium, or low
+
+If the evidence is too weak for a real ranking, say so directly and present the leading open questions instead.
+
+## Step 5: Output a Clear Diagnosis Path
+
+Present the result in this order:
+
+1. Most likely root cause
+2. Plausible alternate causes, if any
+3. Fastest proof step
+4. Recommended fix path
+5. Open questions or blockers
+
+When the fix is not yet clear, recommend the next proving step instead of pretending the diagnosis is complete.
+
+When helpful, group actions into:
+
+- `prove now`
+- `fix next`
+- `follow up later`
+
+Do not implement fixes as part of this skill. The output is a read-only diagnosis with a prioritized path forward.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/bug-hunt-swarm/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bug Hunt Swarm"
+  short_description: "Parallel multi-agent root cause hunt"
+  default_prompt: "Use $bug-hunt-swarm to investigate this bug with four read-only lanes and return the most likely root cause plus the fastest proof path."