opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/brooks-review/pr-review-guide.md

@@ -0,0 +1,163 @@
+# PR Review Guide — Mode 1
+
+**Purpose:** Analyze a code diff or specific files for decay risks that are directly visible
+in the changed code. Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+---
+
+## Before You Start
+
+**Auto-generated files:** If the diff contains generated files (protobuf stubs, OpenAPI clients,
+ORM migrations, lock files, minified bundles), skip those files entirely. Generated code reflects
+tool choices, not developer decisions. Note in the report which files were skipped and why.
+
+**Scope calibration:** Adjust analysis depth based on PR size before starting.
+
+| PR Size | Approach |
+|---------|----------|
+| < 50 lines | Focus on Steps 1–3 only; run Step 6a only if imports changed; run Step 6b if any class, method, or variable was renamed or introduced |
+| 50–300 lines | Full process, all steps |
+| > 300 lines | Full process; note in the Scope line that review is sampled — cover the highest-risk areas rather than every file |
+
+For PRs > 500 lines: flag in the Summary that a PR this size is itself a Change Propagation signal. A change that cannot be reviewed in one pass suggests tangled responsibilities.
+
+---
+
+## Analysis Process
+
+Work through these seven steps in order. Do not skip steps.
+
+### Step 1: Understand the scope
+
+Read the diff or files and answer:
+- What is the stated purpose of this change?
+- Which files were modified?
+- Flag immediately if the PR changes more than 10 unrelated files — that itself is a
+  🟡 Warning: Change Propagation (a PR that touches many unrelated things is a sign
+  that responsibilities are tangled).
+
+### Step 2: Scan for Change Propagation
+
+*Scan this first — it is the most visible risk in a diff.*
+
+Look for:
+- Does this change touch files in modules that have no conceptual connection to the stated purpose?
+- Does any modified class change for more than one business reason in this diff?
+- Does any method use more data from another class than from its own?
+
+If the diff shows no cross-module changes beyond what the feature requires → skip, no finding.
+
+### Step 3: Scan for Cognitive Overload
+
+Look for:
+- Are any new or modified functions longer than 20 lines?
+- Is there nesting deeper than 3 levels in new or modified code?
+- Are there more than 4 parameters in any new function signature?
+- Are there magic numbers or unexplained constants in new code?
+- Do new variable or function names require reading the implementation to understand?
+- Are there train-wreck chains (3+ method calls chained)?
+
+### Step 4: Scan for Knowledge Duplication
+
+Look for:
+- Does this change introduce logic that already exists elsewhere in the codebase?
+- Does this change introduce a new name for a concept that already has a name?
+- Does this change add a class to a hierarchy that has a parallel in another module?
+
+### Step 5: Scan for Accidental Complexity
+
+Look for:
+- Does this change add an abstraction with only one concrete use?
+- Does this change add a class that only wraps another class or delegates everything?
+- Does this change add configuration options or extension points that serve no current requirement?
+
+### Step 6a: Scan for Dependency Disorder
+
+- Do any new imports create a dependency from a high-level module to a low-level one?
+  (e.g., domain service now imports a database driver or HTTP client)
+- Do any new imports introduce a cycle between modules?
+- Does any new interface force callers to depend on methods they do not use?
+
+If no new imports and no structural changes → skip, no finding.
+
+### Step 6b: Scan for Domain Model Distortion
+
+- Do new class or variable names match the language the business uses for the same concept?
+- Does any new class hold only data with no behavior (pure data bag), where behavior was expected?
+- Does any new method put logic that belongs to the domain in a service or utility layer?
+
+---
+
+## Severity Calibration
+
+Apply the Iron Law format from `../_shared/common.md`. Each risk in `../_shared/decay-risks.md` has its own Severity
+Guide with numeric thresholds — use those as the primary reference. When a finding sits
+on the boundary between two tiers, use this as a tiebreaker:
+- 🔴 Critical — actively breaking velocity or creating production risk *today*
+- 🟡 Warning — will if left unaddressed through the next few features
+- 🟢 Suggestion — worth fixing when nearby, not urgent
+
+When multiple findings exist, list Critical items first. If there are more than 5 findings,
+add a one-line "Recommended fix order" at the end of the Findings section.
+
+---
+
+## Step 7: Quick Test Check
+
+*Run this last. Three signals only — this is not a full Mode 4 review.*
+
+If the diff contains only generated files, configuration, or documentation with no
+production logic changes → skip Step 7 entirely.
+
+**Signal 1: Do tests exist for the changed behavior?**
+
+- Does the diff modify production code?
+- Are corresponding test file changes included in the diff?
+- If new public behavior was added with no new tests:
+  → 🟡 Warning: Coverage Illusion — new behavior is untested
+  → Source: Feathers — Working Effectively with Legacy Code, Ch. 1
+- If the change is a pure refactor and existing tests cover the behavior → no finding.
+
+**Signal 2: Quick Mock Abuse sniff**
+
+Only check if the diff includes test file changes.
+
+- Is mock setup code in new/modified tests obviously longer than the test logic?
+- Are the primary assertions `expect(mock).toHaveBeenCalledWith(...)` with no behavior verification?
+- Does the diff add any methods to production classes that are only called from test files?
+
+If any of these are true:
+  → 🟡 Warning: Mock Abuse — test complexity exceeds behavior complexity
+  → Source: Osherove — The Art of Unit Testing, mock usage guidelines
+
+**Signal 3: Quick Test Obscurity sniff**
+
+Only check if the diff includes test file changes.
+
+- Do new test names express scenario and expected outcome?
+  (Pattern: `methodName_scenario_expectedResult` or equivalent)
+- Are there new tests with multiple assertions and no message strings on any of them?
+
+If test names are vague or assertions lack messages:
+  → 🟢 Suggestion: Test Obscurity — test intent is unclear from the test name or assertions
+  → Source: Meszaros — xUnit Test Patterns, Assertion Roulette (p.224)
+
+**Output rule:**
+
+If all three signals are clean → write no Test findings. Proceed directly to the report.
+
+If findings exist → add them to the Findings section using the standard Iron Law format.
+Label the risk as the test decay risk name (e.g., "Coverage Illusion", "Mock Abuse",
+"Test Obscurity").
+
+> **Note:** Step 7 is a fast check, not a full test audit. When systemic test problems
+> are found, note in the Summary: "Consider running `/brooks-lint:brooks-test` for a
+> complete test quality diagnosis."
+
+---
+
+## Output
+
+Use the standard Report Template from `../_shared/common.md`.
+Mode: PR Review
+Scope: list the files reviewed (excluding skipped generated files).

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

@@ -0,0 +1,44 @@
+---
+name: brooks-sweep
+description: "Full-sweep mode: runs a unified analysis across all quality dimensions — code decay, architecture, tech debt, and test quality — then applies fixes directly to the codebase. Safe changes are auto-applied; risky changes are confirmed before execution. Drawing on twelve classic..."
+risk: unknown
+source: https://github.com/hyhmrright/brooks-lint/tree/main/skills/brooks-sweep
+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 — Full Sweep & Auto-Fix
+## When to Use
+
+Use this skill when you need full-sweep mode: runs a unified analysis across all quality dimensions — code decay, architecture, tech debt, and test quality — then applies fixes directly to the codebase. Safe changes are auto-applied; risky changes are confirmed before execution. Drawing on twelve classic...
+
+
+## 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/decay-risks.md` for production risk symptom definitions
+4. Read `../_shared/test-decay-risks.md` for test risk symptom definitions
+5. Read `sweep-guide.md` in this directory for the unified scan and fix process
+
+## Process
+
+**If the user has not specified a project or directory:** apply Auto Scope Detection
+from `../_shared/common.md` to determine the review scope before proceeding.
+
+1. Show pre-flight consent notice and wait for the user's one-time approval (Step 0 of the guide)
+2. Enumerate scope and initialize the `unresolvable` / `non_critical_rounds` / `fix_log` state (Step 1 of the guide)
+3. Run the four dimensions in sequence — review, test, debt, audit — each scanning, classifying, applying Safe + Extended-Safe fixes, and verifying via the project test command (Steps 2–5 of the guide)
+4. Iterate: re-scan modified files + same-module + static consumers; converge on a clean round, retire 3-retry failures to the `unresolvable` set, cap non-critical rounds at 3 (Step 6 of the guide)
+5. Aggregate residual and unresolvable items and output the Full Sweep Report (Steps 7–8 of the guide)
+
+**Mode line in report:** `Full Sweep`
+
+## 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-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".