@tplog/hasapi 0.1.0

package/hasapi-skills/_shared/test-decay-risks.md

@@ -0,0 +1,246 @@
+# Test Decay Risk Reference
+
+Six patterns that cause test suites to degrade. Apply the Iron Law to each finding.
+
+---
+
+## Risk T1: Test Obscurity
+
+**Diagnostic question:** How much effort does it take to understand what this test verifies?
+
+Unclear test intent breeds distrust, missed failures, and duplicates — one step from an abandoned suite.
+
+### Symptoms
+
+- Assertion Roulette: multiple assertions with no message string — when one fails, it is
+  impossible to determine which behavior broke without reading every assertion
+- Mystery Guest: test depends on external state (files, database rows, shared fixtures)
+  that is not visible in the test body
+- Test names that do not express the scenario and expected outcome
+  (e.g., `test1`, `shouldWork`, `testLogin`, `testUserService`)
+- General Fixture: an oversized setUp or beforeEach shared by unrelated tests, making
+  each test's preconditions invisible
+- Test body requires reading production code to understand what is being verified
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Assertion Roulette | Meszaros — xUnit Test Patterns | Assertion Roulette (p.224) |
+| Mystery Guest | Meszaros — xUnit Test Patterns | Mystery Guest (p.411) |
+| General Fixture | Meszaros — xUnit Test Patterns | General Fixture (p.316) |
+| Test naming | Osherove — The Art of Unit Testing | method_scenario_expected naming convention |
+
+### Severity Guide
+
+- 🔴 Critical: no test name in the file describes the behavior being tested; all assertions lack messages
+- 🟡 Warning: multiple Mystery Guests; several ambiguous test names
+- 🟢 Suggestion: minor naming issues; isolated General Fixture
+
+### What Not to Flag
+
+- Multiple assertions are acceptable when they describe one coherent behavior and fail with a clear story
+- Shared setup is fine when every initialized value is relevant to nearly every test
+- Concise test names are acceptable if scenario and expected outcome are still obvious
+
+---
+
+## Risk T2: Test Brittleness
+
+**Diagnostic question:** Do tests break when you refactor without changing behavior?
+
+Brittle tests punish refactoring — eventually developers stop refactoring and the codebase stagnates to protect the suite.
+
+### Symptoms
+
+- Tests assert on private method results, internal state, or implementation details
+  rather than observable behavior
+- Eager Test: one test method verifies multiple unrelated behaviors; any single change
+  causes it to fail regardless of which behavior was touched
+- Over-specified: assertions enforce mock call order or exact parameter values that are
+  irrelevant to the behavior being tested
+- Renaming or extracting a method causes 5 or more tests to fail even though no behavior changed
+- Erratic Test: a test produces different results across runs without any change to
+  production code — caused by race conditions, time-dependent logic, random data, or
+  shared mutable state between tests
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Eager Test | Meszaros — xUnit Test Patterns | Eager Test (p.228) |
+| Erratic Test | Meszaros — xUnit Test Patterns | Erratic Test |
+| Implementation coupling | Osherove — The Art of Unit Testing | Test isolation principle |
+| Orthogonality violation | Hunt & Thomas — The Pragmatic Programmer | Ch. 2: Orthogonality |
+
+### Severity Guide
+
+- 🔴 Critical: refactoring with no behavior change causes test failures; > 5 tests coupled to a single implementation detail
+- 🟡 Warning: Eager Tests common across the suite; moderate implementation-detail assertions
+- 🟢 Suggestion: isolated over-specification in non-critical tests
+
+### What Not to Flag
+
+- Verifying an externally observable event or emitted command is not implementation coupling
+- One test with several assertions is acceptable when all assertions support one behavior claim
+- A fake or in-memory adapter is not brittleness if the test still asserts behavior, not wiring
+
+---
+
+## Risk T3: Test Duplication
+
+**Diagnostic question:** Is the same test scenario expressed in more than one place?
+
+Duplicated tests must change in multiple places and create false confidence without testing distinct behavior.
+
+### Symptoms
+
+- Test Code Duplication: same setup or assertion logic copy-pasted across multiple tests
+  without extraction into a shared helper
+- Lazy Test: multiple tests verifying identical behavior with no differentiation in input,
+  state, or expected output
+- Same boundary condition tested identically at unit, integration, and E2E level —
+  three copies with no layer differentiation
+- Test helper functions or fixtures duplicated across test files instead of shared
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Test Code Duplication | Meszaros — xUnit Test Patterns | Test Code Duplication (p.213) |
+| Lazy Test | Meszaros — xUnit Test Patterns | Lazy Test (p.232) |
+| DRY violation in tests | Hunt & Thomas — The Pragmatic Programmer | DRY: Don't Repeat Yourself |
+
+### Severity Guide
+
+- 🔴 Critical: core business scenario fully duplicated across all three test layers with no differentiation
+- 🟡 Warning: common scenario setup repeated in 5 or more tests without extraction
+- 🟢 Suggestion: minor helper duplication; isolated Lazy Tests
+
+### What Not to Flag
+
+- The same scenario may appear at unit and integration level when each layer verifies a distinct risk
+- Small local setup duplication can be clearer than an over-abstracted fixture maze
+- Similar assertions against different domain rules are not Lazy Tests if the business intent differs
+
+---
+
+## Risk T4: Mock Abuse
+
+**Diagnostic question:** Is the test more complex than the behavior it tests?
+
+Mock abuse produces tests that pass while verifying nothing — production code can be fully broken as long as the mocks are wired up.
+
+### Symptoms
+
+- Mock setup code is longer than the test logic itself
+- Primary assertion is `expect(mock).toHaveBeenCalledWith(...)` — the test verifies
+  that a mock was called, not that any real behavior occurred
+- Test-only methods added to production classes for lifecycle management in tests
+- Single unit test uses more than 3 mocks
+- Incomplete Mock: mock object missing fields that downstream code will access,
+  causing silent failures only visible in integration
+- Hard-Coded Test Data: test data has no resemblance to real data shapes or constraints
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Mock count > 3 | Osherove — The Art of Unit Testing | Mock usage guidelines |
+| Testing mock behavior | Meszaros — xUnit Test Patterns | Behavior Verification (p.544) |
+| Test-only production methods | Feathers — Working Effectively with Legacy Code | Ch. 3: Sensing and Separation |
+| Hard-Coded Test Data | Meszaros — xUnit Test Patterns | Hard-Coded Test Data (p.534) |
+| Incomplete Mock | Osherove — The Art of Unit Testing | Mock completeness requirement |
+
+### Severity Guide
+
+- 🔴 Critical: mock setup > 50% of test code; production class has methods only called from tests
+- 🟡 Warning: mocks consistently > 3 per test; primary assertions are mock call verifications
+- 🟢 Suggestion: isolated Incomplete Mocks; minor Hard-Coded Test Data
+
+### What Not to Flag
+
+- A small number of mocks around nondeterministic dependencies is acceptable when assertions still verify behavior
+- Fakes and spies used to observe state transitions are not mock abuse by default
+- One interaction assertion may be appropriate when the interaction itself is the behavior under test
+
+---
+
+## Risk T5: Coverage Illusion
+
+**Diagnostic question:** Does the test suite actually protect against the failures that matter?
+
+Coverage measures execution, not verification. 90% line coverage can still miss every critical failure mode — teams stop looking because the number says "covered."
+
+### Symptoms
+
+- High line coverage but error-handling branches, boundary conditions, and exception paths
+  have no corresponding tests
+- Happy-path only: no sad paths, no null/empty/zero inputs, no concurrency edge cases
+- Legacy code areas are being actively modified with no tests present
+  (Feathers: "legacy code is code without tests")
+- Coverage percentage treated as a sign-off criterion; critical change paths remain untested
+- Tests assert on return values but not on important side effects such as database writes,
+  event publications, or state transitions
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Legacy code = no tests | Feathers — Working Effectively with Legacy Code | Ch. 1: "Legacy code is code without tests" |
+| Change coverage vs line coverage | Google — How Google Tests Software | Ch. 11: Testing at Google Scale |
+| Happy-path only | Osherove — The Art of Unit Testing | Test completeness principle |
+
+### Severity Guide
+
+- 🔴 Critical: legacy code area actively being modified with no tests; error-handling paths entirely absent
+- 🟡 Warning: coverage > 80% but edge and exception paths are systematically absent
+- 🟢 Suggestion: a few non-critical paths missing sad-path tests
+
+### What Not to Flag
+
+- High line coverage is useful when paired with branch, boundary, and change-path coverage
+- A new module may have limited coverage early if it is still private and low-risk
+- Side-effect assertions may live in integration tests rather than unit tests without implying a gap
+
+---
+
+## Risk T6: Architecture Mismatch
+
+**Diagnostic question:** Does the test suite structure reflect the system's actual risk profile?
+
+Wrong suite shape is slow and expensive — not from bad tests, but from using the wrong type at the wrong layer.
+
+### Symptoms
+
+- Inverted test pyramid: E2E or integration test count exceeds unit test count,
+  causing a slow and fragile suite
+- Legacy code with no seam points: no interfaces, dependency injection, or seams exist,
+  making it impossible to test in isolation without modifying production code
+- Legacy areas being modified have no Characterization Tests to capture current behavior
+  before changes are made
+- Full suite execution time exceeds 10 minutes (indicates architectural problem,
+  not a performance problem — too many slow tests)
+- High-risk and low-risk paths are tested at identical density;
+  no risk-based prioritization in test distribution
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Inverted pyramid | Google — How Google Tests Software | 70:20:10 unit:integration:E2E ratio |
+| No seam points | Feathers — Working Effectively with Legacy Code | Ch. 4: Seam Model |
+| Missing Characterization Tests | Feathers — Working Effectively with Legacy Code | Ch. 13: Characterization Tests |
+| Suite execution time | Meszaros — xUnit Test Patterns | Slow Tests (p. 253) |
+
+### Severity Guide
+
+- 🔴 Critical: legacy code being modified has no seams and no characterization tests; pyramid fully inverted
+- 🟡 Warning: suite execution > 10 minutes; integration/E2E count exceeds unit tests
+- 🟢 Suggestion: localized pyramid ratio deviation; a few legacy areas missing characterization tests
+
+### What Not to Flag
+
+- Deviating from 70:20:10 can be justified by platform constraints or product risk
+- A suite heavy on integration tests can still be healthy if feedback is fast and purposefully layered
+- A small number of critical-path E2E tests is desirable, not a smell

package/hasapi-skills/hasapi-audit/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: hasapi-audit
+description: >
+  Architecture audit that maps module dependencies, checks layering integrity, and
+  flags structural decay across a codebase, drawing on twelve classic engineering books.
+  Triggers when: user asks to audit architecture, review folder/module structure,
+  check for circular imports, understand how the codebase is organized, or asks
+  "does this follow clean architecture?", "why does everything depend on everything?",
+  "are our layers correct?", "where should this code live?".
+  Also triggers for onboarding requests: "explain this codebase to a new developer"
+  or "give me a codebase tour" (use onboarding mode).
+  Do NOT trigger for: PR-level code review (use brooks-review) or line-level refactoring
+  questions — this skill analyzes structural/module-level concerns, not individual functions.
+---
+
+# Brooks-Lint — Architecture Audit
+
+## 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 symptom definitions and source attributions
+4. Read `architecture-guide.md` in this directory for the audit framework
+
+## Process
+
+**Onboarding mode:** If the user asks for an onboarding report, codebase tour, or
+"explain this codebase to a new developer", read `onboarding-guide.md` from this
+directory and follow it instead of `architecture-guide.md`. This mode explains rather
+than diagnoses — no Health Score, no Iron Law findings.
+
+**If the user has not specified files or a directory to audit:** apply Auto Scope
+Detection from `../_shared/common.md` to determine the audit scope before proceeding.
+
+1. Gather codebase context and draw the module dependency graph as Mermaid (Steps 0–1 of the guide)
+2. Scan for each decay risk in the order specified (Steps 2–4 of the guide)
+3. Assign node colors in the Mermaid diagram based on findings (red/yellow/green) — after Step 4
+4. Run the Testability Seam Assessment (Step 5 of the guide)
+5. Run the Conway's Law check (Step 6 of the guide)
+6. Output using the Report Template from common.md — Mermaid graph FIRST, then Findings
+
+**Mode line in report:** `Architecture Audit`

package/hasapi-skills/hasapi-audit/architecture-guide.md

@@ -0,0 +1,195 @@
+# Architecture Audit Guide — Mode 2
+
+**Purpose:** Analyze the module and dependency structure of a system for decay risks that
+operate at the architectural level. Every finding must follow the Iron Law:
+Symptom → Source → Consequence → Remedy.
+
+**Monorepo note:** Treat each deployable service or library as a top-level module. Draw
+dependencies between services, not between their internal packages. Apply the Conway's Law
+check at the service ownership level. Within a single service, apply standard module-level analysis.
+
+---
+
+## Analysis Process
+
+Work through these six steps in order.
+
+### Step 0: Gather Codebase Context
+
+Before drawing anything, establish what you can see.
+
+**If the user provided a full directory tree or pasted relevant file contents:** skip the
+proactive reading below and proceed to Step 1.
+
+**Otherwise, proactively read the project using these tools:**
+
+1. **Top-level structure** — glob top two levels to identify module boundaries:
+   ```
+   Glob: **/*(depth 2, directories only)
+   ```
+2. **Entry points** — read the package manifest or main config file (e.g., `package.json`,
+   `go.mod`, `pom.xml`, `Cargo.toml`, `pyproject.toml`) to confirm language, framework,
+   and declared dependencies.
+3. **Dependency edges** — grep import statements to discover inter-module calls. Run once
+   per language present; limit to the first 200 matches to avoid token overrun:
+   ```
+   Grep: "^\s*(import|from|require\(|use )" across *.ts|*.py|*.go|*.rs|*.java
+   ```
+4. **Large modules** — for any top-level directory with > 10 files, read the file matching
+   `index.*`, `main.*`, or `__init__.*` to understand its stated responsibility.
+
+**Stop when you can answer all three:**
+- What are the top-level modules (names and count)?
+- Which modules import from which other modules?
+- Which module has the highest fan-in or fan-out?
+
+If the project has > 100 top-level files or > 4 levels of nesting, note which areas were
+sampled vs. inferred, and flag this in the report scope line.
+
+### Step 1: Draw the Module Dependency Graph (Mermaid)
+
+Before evaluating any risk, map the dependencies as a Mermaid diagram. Use this format:
+
+````mermaid
+graph TD
+  subgraph UI
+    WebApp
+    MobileApp
+  end
+
+  subgraph Domain
+    AuthService
+    OrderService
+    PaymentService
+  end
+
+  subgraph Infrastructure
+    Database
+    MessageQueue
+  end
+
+  WebApp --> AuthService
+  WebApp --> OrderService
+  MobileApp --> AuthService
+  MobileApp --> OrderService
+  OrderService --> PaymentService
+  OrderService --> Database
+  OrderService --> MessageQueue
+  PaymentService --> Database
+  AuthService -.->|circular| OrderService
+
+  classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
+  classDef warning fill:#ffd43b,stroke:#e67700
+  classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff
+
+  class PaymentService critical
+  class OrderService warning
+  class Database,MessageQueue,AuthService,WebApp,MobileApp clean
+````
+
+Draw the graph structure first — nodes, subgraphs, and edges — without any `classDef` or
+`class` lines. You cannot assign colors until you have completed the risk scan in Steps 2–4.
+
+**After completing Step 4**, return to this graph and add the `classDef` and `class` lines
+based on findings. The example above shows the final colored output.
+
+Rules:
+1. **Nodes** — Use top-level directories or services as nodes, not individual files
+2. **Grouping** — One `subgraph` per architectural layer or top-level directory (e.g., UI, Domain, Infrastructure)
+3. **Edges** — Solid arrows (`-->`) point FROM the depending module TO the dependency; use dotted arrows with label (`-.->|circular|`) for circular dependencies. If no circular dependencies exist, use only solid arrows
+4. **Node limit** — Keep the graph to ~50 nodes maximum; collapse low-risk leaf modules into their parent if needed
+5. **Fan-out** — For any node with fan-out > 5, use a descriptive label: `HighFanOutModule["ModuleName (fan-out: 7)"]`
+6. **Colors** — Apply `classDef` colors AFTER completing Steps 2-4: `critical` (red `#ff6b6b`) for nodes with Critical findings, `warning` (yellow `#ffd43b`) for Warning findings, `clean` (green `#51cf66`) for nodes with no findings or only Suggestions. If no findings at all, classify all nodes as `clean`
+7. **Direction** — Default to `graph TD` (top-down); use `graph LR` only if the architecture is clearly a left-to-right pipeline
+
+### Step 2: Scan for Dependency Disorder
+
+*The most architecturally consequential risk — scan this first.*
+
+Look for:
+- Circular dependencies (any `-.->|circular|` edge in the map above)
+- Arrows flowing upward (high-level domain depending on low-level infrastructure)
+- Stable, widely-depended-on modules that import from frequently-changing modules
+- Modules with fan-out > 5
+- Absence of a clear layering rule (no consistent answer to "what depends on what?")
+
+### Step 3: Scan for Domain Model Distortion
+
+Look for:
+- Do module names match the business domain vocabulary?
+- Is there a layer called "services" that contains all the business logic while domain objects
+  are pure data structures?
+- Are there modules that cross bounded context boundaries (e.g., billing logic in the user module)?
+- Is there an anti-corruption layer where external systems interface with the domain?
+
+### Step 4: Scan for Remaining Four Risks
+
+Check each in turn:
+
+**Knowledge Duplication:**
+- Are there multiple modules implementing the same concept independently?
+- Does the same domain concept appear under different names in different modules?
+
+**Accidental Complexity:**
+- Are there entire layers in the architecture that do not add value?
+- Are there modules whose responsibility cannot be stated in one sentence?
+
+**Change Propagation:**
+- Which modules are "blast radius hotspots"? (A change here requires changes in many other modules)
+- Does the dependency map reveal why certain features are slow to develop?
+
+**Cognitive Overload:**
+- Can the module responsibility of each module be stated in one sentence from its name alone?
+- Would a new developer know which module to add a new feature to?
+
+### Step 5: Testability Seam Assessment
+
+A *seam* is a place in the architecture where behavior can be altered without editing source
+code — typically an interface, a configuration point, or a dependency injection boundary.
+Seam density is a proxy for testability and evolvability.
+
+Scan for:
+- **No seam at the infrastructure boundary**: can you replace a real database, file system,
+  or HTTP client with a test double without editing the module under test? If not, the
+  architecture forces integration tests where unit tests would suffice.
+- **Seam collapse**: a module that was once testable in isolation has had its seams removed
+  (e.g., direct constructor instantiation replaced a dependency injection point, or a global
+  singleton replaced an injected collaborator).
+- **Missing seam in legacy areas**: modules without an obvious injection point or interface
+  boundary — any change requires touching the entire call stack to substitute behavior.
+
+If all modules have clear seams at their infrastructure boundaries → no finding.
+
+If seams are absent or collapsed: flag as 🟡 Warning with a Remedy pointing to the specific
+module and the injection point that needs to be restored or introduced.
+
+Source: Feathers — Working Effectively with Legacy Code, Ch. 4: The Seam Model
+
+### Step 6: Conway's Law Check
+
+After the six-risk scan, assess the relationship between architecture and team structure:
+
+- Does the module/service structure reflect the team structure?
+  (Conway's Law: "Organizations design systems that mirror their communication structure")
+- If yes: is this intentional design or accidental coupling?
+- A mismatch that causes cross-team coordination overhead for every feature is 🔴 Critical.
+- A mismatch that is theoretical but not yet causing pain is 🟡 Warning.
+- If team structure is unknown, note this as context missing and skip the check.
+
+**Calibration examples:**
+- 🔴 Critical: the Payments module is owned by Team A but contains auth logic owned by Team B —
+  every Payments change requires a sync meeting with Team B
+- 🟡 Warning: two separate teams own the `utils/` and `helpers/` directories which do the same
+  things — theoretically painful but not yet causing release coordination issues
+- Not a finding: a single team owns a monorepo with multiple logical modules — Conway's Law
+  misalignment requires *separate teams* to be meaningful
+
+---
+
+## Output
+
+Use the standard Report Template from `../_shared/common.md`. Mode: Architecture Audit.
+
+Place the Mermaid dependency graph FIRST under "Module Dependency Graph". Reference
+relevant node names in findings. Add `classDef` color assignments LAST, after all
+findings are identified.

package/hasapi-skills/hasapi-audit/onboarding-guide.md

@@ -0,0 +1,89 @@
+# Codebase Onboarding Guide
+
+**Purpose:** Produce a newcomer-friendly tour of the codebase. This is NOT a diagnostic
+report — no Health Score, no Iron Law findings. Focus on explanation and orientation.
+
+---
+
+## Process
+
+### Step 1: Map the Territory
+
+- Read top-level structure (same as architecture-guide Step 0)
+- Output: a plain-language overview of what each top-level module does (one sentence each)
+- Group into layers: "Things users interact with", "Business logic", "Infrastructure"
+
+### Step 2: Draw the Dependency Map
+
+Draw the same Mermaid dependency graph as architecture audit Step 1, but color nodes by
+**recommended reading order** using a DISTINCT palette from the severity palette
+(which uses red/yellow/green). This avoids confusing "red = danger" with "red = read last":
+
+- 🔵 Blue (`#339af0`): start here — entry points, core domain
+- 🟣 Purple (`#9775fa`): read next — supporting modules
+- ⚪ Gray (`#ced4da`): read last — infrastructure, generated code, utilities
+
+Add numbered labels: `CoreModule["1. CoreModule"]`
+
+```
+classDef start fill:#339af0,color:#fff
+classDef next fill:#9775fa,color:#fff
+classDef last fill:#ced4da
+```
+
+### Step 3: Highlight Key Conventions
+
+Identify and document patterns the codebase follows:
+- Naming conventions (file naming, class naming, variable naming)
+- Directory organization pattern (feature-based? layer-based? hybrid?)
+- Error handling pattern (exceptions? result types? error codes?)
+- Testing convention (co-located? separate directory? naming pattern?)
+- Dependency injection pattern (if any)
+
+### Step 4: Mark Danger Zones
+
+For each module with known complexity or coupling issues, add a brief warning:
+- "OrderService: high complexity, only modify with full test suite running"
+- "legacy/: no tests, use Characterization Tests before changing"
+
+Do NOT use Iron Law format — use plain warnings. This is orientation, not diagnosis.
+
+### Step 5: Build a Domain Glossary
+
+Extract 10-15 key domain terms from code (class names, method names, constants) and map
+them to plain-language definitions. This applies Evans's Ubiquitous Language as documentation.
+
+### Step 6: Suggest First Tasks
+
+Based on the dependency map, suggest 2-3 low-risk areas where a new developer could make
+their first contribution: modules with good test coverage, clear boundaries, low coupling.
+
+---
+
+## Output Template
+
+```
+# Codebase Tour: [Project Name]
+
+## Overview
+[2-3 sentence summary of what the project does and its tech stack]
+
+## Module Map
+[Mermaid graph with reading-order colors]
+
+## Module Guide
+[One paragraph per top-level module: what it does, what it depends on, key files to read]
+
+## Conventions
+[Bullet list of patterns this codebase follows]
+
+## Danger Zones
+[Bullet list of areas to be careful with, or "None identified" if the codebase is clean]
+
+## Domain Glossary
+| Term | Meaning |
+|------|---------|
+
+## Suggested First Tasks
+[2-3 concrete suggestions for a new developer's first PR]
+```

package/hasapi-skills/hasapi-debt/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hasapi-debt
+description: >
+  Tech debt assessment that identifies, classifies, and prioritizes maintainability
+  problems — helping teams build a refactoring roadmap — drawing on twelve classic
+  engineering books.
+  Triggers when: user asks about tech debt, refactoring priorities, what to clean up
+  first, or asks "why is this so hard to change?", "where's the most painful part?",
+  "what should we fix first?", "how do I justify refactoring to management?",
+  "why is our velocity dropping?".
+  Do NOT trigger for: server health checks, HTTP /health endpoints, Kubernetes probes,
+  database health, or application uptime — "health" in those contexts is infrastructure,
+  not code quality. Also not for single-function refactoring questions.
+---
+
+# Brooks-Lint — Tech Debt Assessment
+
+## 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 symptom definitions and source attributions
+4. Read `debt-guide.md` in this directory for the debt classification framework
+
+## Process
+
+**If the user has not described the codebase or pointed to specific areas:** apply Auto
+Scope Detection from `../_shared/common.md` to determine the assessment scope before proceeding.
+
+1. Scan for all six decay risks (Step 1 of the guide); list every finding before scoring
+2. Apply the Pain × Spread priority formula and classify debt intent (Steps 2–3 of the guide)
+3. Group findings by decay risk (Step 4 of the guide)
+4. Output using the Report Template from common.md, plus the Debt Summary Table
+
+**Mode line in report:** `Tech Debt Assessment`