Solid Hunter

SOLID Hunter

Audit code for design that resists change — a unit serving two actors at once, a variant set whose every addition edits the same scattered dispatch sites, an implementor that cannot honor the contract it claims, an interface that forces its consumers to carry capabilities they never call, a unit that builds its own database client instead of receiving it. Goal: units have one set of stakeholders, variants extend without editing existing dispatch, implementors honor what their abstraction promises, consumers depend only on the capabilities they use, and collaborators arrive from outside.

Supports Go, Python, TypeScript via per-language reference files.

Not covered (owned by other hunters): whether an abstraction should exist at all, function-body mixed concerns, boolean parameters dispatched at one site (→ simplicity-hunter); file-level accumulation, misplaced entity transitions, a class that should be a function, the write to a mutable global (→ smell-hunter); exhaustiveness arms and narrowing on data variant sets (→ invariant-hunter); import direction between layers and external types in domain signatures (→ boundary-hunter); package naming and directory legibility (→ boundary-hunter); test design (→ test-hunter); AI-generated noise and cosmetic style (→ slop-hunter). Where ownership is contested, the category's Ownership: note in What to Hunt is authoritative.

When to Use

• Sharpening package, class, and interface responsibilities after prototyping
• Preparing a codebase for extension with new variants or strategies
• Reducing coupling between services, packages, or layers
• Improving testability by moving collaborators out of constructors
• Reviewing a type hierarchy or interface set before a refactor

Quick Reference

Full rules in What to Hunt; every finding must also clear Not-a-finding and the category's evidence bar. Category names are canonical: the heading here, in What to Hunt, and in the report are identical. The unit each category is judged on is named per language (see Applicability).

Hunter names are unsuffixed end-state names. Until consolidation completes, live skills are language-suffixed (boundary-hunter-go, test-hunter-py, security-hunter-ts, and so on).

Core Principles

1. Single Responsibility (SRP). A unit should have one set of stakeholders. Its evidence is named actors — persistence, transport, billing rules, notification — not method count. Two responsibilities that always change together are one responsibility.

2. Open/Closed (OCP). A variant set that has already paid the extension cost should stop paying it. The finding is not "a switch exists"; it is "this set is open, and each addition edits the same scattered sites".

3. Liskov Substitution (LSP). An implementor must honor what its abstraction promises. A promise is shown by the contract's documentation, its abstract method's stated behavior, or a consumer that relies on it — a method's name alone is not a promise.

4. Interface Segregation (ISP). No consumer should be forced to depend on capabilities it never calls. Width is judged per affected consumer, at an interface that has a live seam; whether the interface should exist at all is a different question and a different hunter's.

5. Dependency Inversion (DIP). A unit should receive its collaborators, not build them. The finding is self-instantiation of an I/O dependency, and the remedy is injecting the concrete type — an abstraction only when a second implementation or a test double already exists.

6. Pragmatism over dogma. SOLID manages change; it does not chase purity. A cohesive aggregate with fourteen methods, an interface every consumer uses fully, a closed variant set switched in three places — none is a finding. A candidate that fails its evidence bar is withdrawn, not reported at Low.

7. Respect the language. Go's small consumer-defined interfaces, composition over inheritance, and explicit main() wiring are the language working as designed; so are Python's duck typing and TypeScript's structural typing. Calibrate to the audited language, never to transplanted Java/C# patterns. Framework-mandated shapes are exempt only when the construct is named.

8. Scans nominate; reading decides. Nothing is a finding until implementors, consumers, and the composition roots have been read. A &X{} match, a switch, an isinstance is a location to inspect, never evidence.

Terms

• Unit — the construct a principle is judged on in a given language. Go: package (SRP), struct (SRP, DIP), interface (ISP, LSP). Python: class (SRP, DIP), ABC/Protocol (ISP, LSP). TypeScript: class (SRP, DIP), interface and abstract class (ISP, LSP). Named in each language reference; the category names are unit-neutral.
• Actor — a stakeholder or concern whose requests change the code: persistence, transport, billing rules, notification. SRP's evidence is named actors, never method count.
• Service dependency — a collaborator that represents behavior (client, repository, gateway, clock, mailer). Distinguished from a value (DTO, dataclass, struct literal, builder, slice, map), whose direct construction is never a DIP finding.
• Composition root — a function that builds dependencies and passes them into other units' constructors, and never stores or calls them itself: Go main(), wire/fx providers; Python app factory, container module, Depends providers; TypeScript entry point, Nest module, container registration. Direct instantiation there is wiring, never a finding. The distinguishing evidence is who keeps the object: a root hands it on; a unit's own constructor (NewSvc, __init__, constructor) that builds a service and stores it in the unit's field is self-instantiation, whatever file it lives in.
• Contract type vs data variant — the LSP/invariant ownership test. A contract type is a behavioral abstraction with methods (interface, ABC, Protocol, abstract class). A data variant set is a union of shapes (TypeScript discriminated-union members, Literal-discriminated dataclasses, Go tagged structs). Consumer narrowing on a contract type to special-case an implementor is here; narrowing on a data variant set is invariant-hunter's. For a base class carrying both fields and methods: if the base declares abstract or overridable behavior the consumer calls, it is a contract type; a dataclass hierarchy with no overridable methods is a data variant set.
• Open variant set — the OCP evidence test. A set is open when this set has paid the extension cost: a variant added in history (git log -S on the discriminant) touched two or more of the listed dispatch sites, or the diff under review adds a variant and touches them now. A sibling registry elsewhere, a plugin architecture in another subsystem, or a discriminant sourced from configuration or external input nominates the history check; none proves that this set needs an extension point. Exhaustiveness is a separate property: a set can be open and still carry assertNever arms at every site. The arms make each addition a compile error; they do not remove the cost of editing every site. Missing exhaustiveness is invariant-hunter's; extension cost is here; the same union can carry one finding of each, at different anchors.
• Existence vs width — the ISP/simplicity ownership test for an interface. An interface with no live seam raises an existence question: simplicity's. A seam is live when a production consumer receives the interface from outside — through handwritten wiring or a container, the mechanism is irrelevant — or when a second implementation or a test double exists. Everything else (an interface only ever returned by the code that implements it, or never held as a parameter or field) is an existence question. Width is judged per affected consumer: a consumer forced to depend on capabilities it never calls that are unrelated to the ones it does (write alongside read, admin alongside runtime). One consumer using everything does not erase the finding; the Action keeps a composite for it and adds role interfaces for the others. A fake stubbing members is supporting evidence, never the sole proof.
• Self-instantiation — a type creating its own service dependency inside a constructor or method, or reading a module/package-level service instead of receiving it. The DIP finding. A service dependency here does I/O or holds process-external state: database, network, filesystem, queue, clock, randomness. A pure in-process helper (parser, formatter, validator) constructed internally is not one. Nor is a stdlib handle opened and closed inside one method on a path or address the method received (os.Open(path), open(path)): that is resource use, not a collaborator.
• Compensating branch — a consumer branch that exists because one implementor cannot honor the contract (skip the transaction for InMemoryRepo, catch the not-implemented error from ReadOnlyStore). The consumer form of the LSP finding. Distinct from capability dispatch: checking for an optional interface and falling back to the base contract when absent (io.WriterTo in io.Copy) is the language working as designed.
• Target scope and context — findings anchor in the manifest; implementors, consumers, and test doubles outside it are read to judge them.

Not a finding on these grounds alone

Conditionals, not category exemptions — each states what does not justify a finding and, where one exists, what would:

• A cohesive aggregate with many methods. Methods that all operate on the same data for one workflow, or form one transaction boundary (mutation + rule + audit that are inseparable), are one responsibility. Is a finding when two named actors can change independently.
• Value types, DTOs, dataclasses, config objects, builders — they are the data; never DIP or ISP subjects. Direct construction of them is never self-instantiation.
• Functional-style code — plain functions and closures are not struct/class subjects: no DIP, ISP, LSP, or struct-level SRP finding demands that objects be introduced. Recorded as architecture style. Go package-level SRP still applies: a package of functions serving persistence AND transport AND rules is Responsibility Sprawl at the package unit regardless of style.
• Exhaustiveness arms — their presence or absence never decides OCP. A missing arm is invariant-hunter's. A set with arms at every site is still Rigid Extension Points when it is open and dispatch is scattered; a set with no evidence of openness is not a finding however many sites switch on it — withdraw, do not report at Low.
• Capability dispatch with a fallback — checking for an optional interface (io.WriterTo, a Flusher, a SupportsBatch Protocol) and falling back to the base contract when absent. Not Broken Substitution. Is when the branch exists because an implementor cannot honor what the base contract promises.
• A concrete-type check that only unlocks an extra (if pg, ok := store.(*PostgresStore); ok { pg.Vacuum() } where Vacuum is outside Store's contract) — not Broken Substitution: nothing in the contract is broken. Not DIP either: the consumer constructs nothing and reads no global. No finding.
• A single dispatch site consuming a foreign result type to answer its own question — one site is not scattered dispatch, and a registry for one consumer is gold plating.
• Heterogeneous dispatch arms — sites that serve different consumers with deliberately different answers do not consolidate (the registry gate). Recommend exhaustiveness at each site, not a registry. Not a Rigid Extension Points finding.
• Direct instantiation in a composition root — wiring, in every language. Also: a constructor parameter typed as a concrete class is not a finding by itself; it is a finding only when the unit creates the dependency.
• A constructor parameter a named framework construct injects (Nest @Injectable constructor injection, FastAPI Depends, wire/fx providers) — the container is the composition root. The construct must be named; "this project uses Nest" is not evidence.
• A method shape a named framework construct prescribes (Django class-based view handlers, Angular lifecycle hooks) — the member's existence and signature are exempt. Its body is evaluated normally: a get() that also sends email and writes an audit log is sprawl in the body — simplicity-hunter's Mixed Concerns — not a mandated shape. Is a Responsibility Sprawl finding when members outside the prescribed shape serve a second actor.
• An interface with no live seam (never received by a consumer from outside, no double, one implementation) — simplicity-hunter's (should it exist?). Never a Fat Interfaces finding here.
• Narrowing on a data variant set — invariant-hunter's, whether guarded or not.
• A global service that is written after initialization — the write is smell-hunter's Mutable Global State at the declaration/write site. The read inside a unit's logic is Concrete Dependency Chains here, anchored at the consumer. Two anchors, one finding each, cross-referenced; neither reports the other's site.
• Go small interfaces defined at the consumer, composition over inheritance, explicit main() wiring — the language working as designed.
• A pattern in a test file — never a finding; test files are out of scope, not exempt (see Test-code scope).

What to Hunt

Categories are named, not numbered. Cross-references use category names (e.g. "→ Fat Interfaces").

Responsibility Sprawl (SRP)

One unit serving two or more actors with independent reasons to change.

Signals — every one of them nominates; none is a threshold:

• Many public methods spanning unrelated concepts
• Many constructor dependencies
• Imports from many unrelated modules or packages (persistence, HTTP, formatting, crypto)
• Vague names with broad scope: Manager, Handler, Service, Utils, Helper
• Methods that do not share the unit's fields — half the methods untouched by half the state
• Go adds the package unit: a package serving persistence AND transport AND rules
• A test that needs many mocks to run the unit (read from context; test-hunter already points here)

Evidence bar: name each actor and the members belonging to it, and give a change scenario for one actor that touches members belonging to another.

Action: extract per actor; the original delegates or dissolves.

Ownership: split by unit. A class (and, in Go, a package or struct) serving two actors is here. A file accumulating unrelated responsibilities is smell-hunter's God Module. A class that should be a function is smell-hunter's Class Abuse; the placement of entity transitions is smell-hunter's Anemic Domain Model. A function body mixing fetch, transform and persist is simplicity-hunter's Mixed Concerns. Package naming and directory legibility (util, common, name/directory mismatch, models of unrelated domains) is boundary-hunter's; Go package-level responsibility analysis stays here. Until boundary-hunter unifies, its Go §7 signal "multiple files in a package spanning unrelated concerns" double-owns this; cross-reference rather than suppress.

Rigid Extension Points (OCP)

Adding a variant to an open set requires editing two or more dispatch sites beyond the variant's definition.

Signals:

• switch / if-elif / if-else on a discriminant in several sites
• A factory with a growing switch and no registration mechanism
• Hard-coded strategy selection (if typ == "email" { sendEmail() } else if typ == "sms" { sendSMS() })
• A boolean parameter is a two-member discriminant and meets exactly the same bar: its choice dispatched at two or more sites, the set shown open. There is no separate boolean path and no "will grow" carve-out

Evidence bar: list every dispatch site (enumerated project-wide, not from the manifest alone); show the arms share one responsibility (the registry gate); show the set is open by the history test — a variant added in history touched two or more of the listed sites, or the diff under review adds one and touches them now. No openness evidence, no finding: withdraw, do not report at Low.

Registry gate. A registry or dispatch table is the remedy only where the scattered arms share one responsibility — near-identical bodies answering the same question. Sites that serve different consumers with deliberately different answers (one resolves a template, one a rate limit, one an icon) do not consolidate: a record spanning them becomes a heterogeneous bag of weak callbacks. There, recommend the cheap standalone fix — exhaustive dispatch with assertNever-style arms so the next variant is a compile error — and raise no finding here.

Action: the smallest seam that removes the per-site edit — a lookup table when the arms only select a value, a shared function when the arms differ by one call, an interface with one implementation per variant only when the arms carry behavior. The Action states what each added concept removes, so the net benefit is defensible: an interface, N implementations and a registry replace one switch with N+2 units, and a remedy that cannot argue the net is not recommended — the finding then names the cost instead.

Ownership: three-way split by the openness test. Here: scattered dispatch on an open variant set whose arms share one responsibility. smell-hunter's Shotgun Surgery keeps non-variant scattering — adding a field touches mappers, validators and serializers; a config concept spanning layers; a rename that is find-and-replace — including scattering only git history reveals. invariant-hunter keeps exhaustiveness: the missing arm, no design change. The last two are orthogonal to this one; a single union can carry one finding of each at different anchors. A boolean dispatched at one site is simplicity-hunter's Over-Parameterized APIs however likely it looks to grow.

Broken Substitution (LSP)

An implementor fails the contract its abstraction promises, or a consumer carries a compensating branch for one implementor.

Signals:

• Not-implemented / unsupported throws, raises, or panics in an implementing member
• A silent zero return or no-op instead of the promised behavior
• Narrowed preconditions — the implementor rejects input the abstraction accepts
• Widened error cases — the implementor fails where the contract implies success
• Consumer isinstance / instanceof / x.(T) / type switch on a contract type — this nominates only; the branch must compensate for a contract failure to be a finding

Evidence bar: name the promised behavior — shown by the contract's documentation, its abstract method's stated behavior, or a consumer that relies on it; a method's name alone is not a promise — the implementor that breaks it and how (throws/panics not-implemented, silent zero/no-op, narrowed input, widened errors), and whether a consumer holding the abstraction has a path to the broken member. For the consumer form: the compensating branch, the guarantee it gives up, and the implementor it compensates for.

Action: a narrower abstraction or composition — the type stops claiming what it cannot honor. Where the consumer branch stays for now, the Action names the guard form; guardedness is a note, never a second finding.

Ownership: the contract-type vs data-variant test (see Terms). Narrowing on a contract type to special-case an implementor is here, whatever the guard form — a bare x.(T) in that role is one Broken Substitution finding with the guard noted in Action, not an additional invariant-hunter finding. Narrowing on a data variant set, and assertions from any / open data (JSON, config, interface{} payloads), stay invariant-hunter's. Capability dispatch and concrete checks that only unlock an extra are not findings (see Not-a-finding).

Fat Interfaces (ISP)

An interface with a live seam forces a production consumer to depend on unrelated capabilities it never calls.

Signals:

• Consumers calling a small subset of a wide interface
• Read and write bundled where some consumers only read; runtime and admin capabilities on one type
• One interface for an entire subsystem
• Implementors or fakes carrying stubs (supporting evidence only)
• A consumer-side interface mirroring a dependency's full API — only when the existence test routes it here

Evidence bar: name each affected consumer and the subset it calls, and the unrelated capabilities it is forced to carry. A stubbing implementor or fake is supporting evidence, never the sole proof: a fake stubbing seven members with a single consumer that uses all twelve proves nothing about production width.

Action: split into role interfaces; in Go, define them at the consumer. One consumer that uses everything keeps a composite; the others get role interfaces.

Ownership: the existence-vs-width test (see Terms). No live seam → simplicity-hunter (Unnecessary Abstractions; in Go, Interface Pollution) — an existence question, never a finding here. Live seam → here, judged per affected consumer.

Concrete Dependency Chains (DIP)

A unit self-instantiates a service dependency that does I/O, or reads a module/package-level one instead of receiving it.

Signals:

• new X() / X() / &X{} / pkg.X{} / NewX() of a service inside a constructor or method
• self.client = EmailClient() in __init__; this.mailer = new SmtpMailer() in a constructor
• A package/module-level service read inside business logic
• Static or classmethod calls to a concrete utility that holds state or does I/O

Evidence bar: name the instantiation or global-read site inside the unit; show the dependency does I/O or holds process-external state; confirm the unit is not a composition root (who keeps the object — see Terms); and state what the caller cannot control as a result: the configuration or endpoint chosen inside, the clock or randomness, the lifecycle of a shared resource.

Action: accept the concrete dependency in the constructor. Recommend an abstraction only when a second implementation or a test double already exists — naming an imagined double does not justify one. In Go a concrete pointer parameter cannot accept a fake, so the Action states that a future double will need a consumer-defined interface, introduced with the test that needs it: a recorded consequence, not a recommendation.

Ownership: type-level wiring only. Import direction between layers, and external types in domain signatures, are boundary-hunter's Dependency Direction Violations and Missing Abstraction Over Externals — a domain module importing a driver package directly, with no instantiation inside a type, is not a finding here. Whether a resulting interface should exist is simplicity-hunter's question, which this category answers in advance by injecting the concrete type. The write to a global after initialization is smell-hunter's Mutable Global State at the global's own site; the read inside a unit's logic is here, anchored at the consumer.

Within-skill routing — Broken Substitution vs Fat Interfaces

The same stub fires both: ReadOnlyStore.Save() panicking is an implementor failing its contract (LSP) and an interface forcing a stub (ISP). Each category clears its own bar first; a site that clears neither is no finding. When both clear:

• Broken Substitution when the implementor is held as the abstraction by some consumer. Reachability of the broken member sets Severity (High reached, Medium held but unreached) — it does not decide ownership.
• Fat Interfaces, anchored at the interface, when the implementor is never held as the abstraction and an affected consumer shows the split.

The Evidence cell of whichever is reported names the other reading in one clause, so the reader sees why it was not chosen. One finding per site.

Applicability

All five categories are universal and applicable in every supported language; what changes is the unit. A language with no reference is not supported — its files are excluded, never implicitly audited.

There are no language-only categories: no supported language has a SOLID defect the others lack, and none is invented.

Test-code scope

Test files are excluded from findings — the same deviation invariant-hunter records. The design of a test class or fixture is not a SOLID question. Test paths per language: Go *_test.go; Python test_*.py, *_test.py, tests/, conftest.py; TypeScript *.test.*, *.spec.*, *.e2e.*, __tests__/. The exclusion is by path: a production helper under tests/ is not audited.

Test files are read as context:

• A hand-written double proves a seam is live — which routes an interface to Fat Interfaces rather than to simplicity-hunter.
• A fake with ten no-op members supports a width finding the production consumers must carry on their own.
• A test that patches a module-level client in order to construct a unit confirms self-instantiation and records the friction in the Evidence cell.

Test evidence never raises Severity. Cite the test file in the Evidence cell; anchor the finding at the production type.

Severity and Impact

Every finding carries both, per the sibling definitions. They answer different questions and routinely diverge.

Severity — behavioral risk if left as-is:

• Critical — all four parts named: the triggering call, the violated contract, the downstream consequence (data loss, crash, corrupted state), and why nothing contains it. A Save that silently no-ops on an implementor a production write path reaches, with the caller reporting success. A reachable throw that a caller catches and handles is not Critical. Only Broken Substitution can reach Critical.
• High — a Broken Substitution awaiting its first call: the implementor is registered or injected as the abstraction and a consumer path reaches the broken member; the consequence is stated, or stated as unknown.
• Medium — the default for the other four categories once they clear their evidence bar, and for a Broken Substitution whose break is not reachable through the abstraction today.
• Low — a finding that clears its bar with the smallest consequence: one affected consumer carrying one unused member; a hidden clock or random source with no configuration behind it.

A pattern that fails its evidence bar or matches a Not-a-finding conditional produces no finding at any severity. Test friction (patching, skipping) is Evidence and raises Impact; it never sets Severity. Severity is never a confidence scale: an uncertain finding is withdrawn, not downgraded.

Impact — how much the change is worth: contextual, never derived from method or site count. A sprawl in the type every handler touches is High impact at Medium severity.

• High — substantial reduction on code read or changed often
• Medium — clear improvement on a moderately reached surface
• Low — clears the evidence bar but touches a small, rarely hit surface

Recommendations group by Severity (Critical → High → Medium → Low), then by Impact within each group.

Audit Workflow

Phase 1: Gain Context

1. Resolve the raw manifest. Scope may be:

   • Diff: files changed relative to the base branch — committed, staged, unstaged, untracked
   • Path: specific files, folders, or packages
   • Codebase: the entire project (default when unspecified; set SCOPE=.)

   Party mode: when the orchestrator supplies a scope snapshot, treat scope.txt as a file manifest only (one path per line). Read run metadata (base SHA, surface kind, counts) from scope-meta.txt when present. Use the manifest verbatim; do not re-resolve. The resolution below is for standalone runs only.

   For diff mode, resolve fail-closed:

   BASE=$(git symbolic-ref -q refs/remotes/origin/HEAD | sed 's@^refs/remotes/@@')
   git rev-parse -q --verify "$BASE^{commit}" >/dev/null 2>&1 || BASE=
   if [ -z "$BASE" ]; then
     for b in origin/main origin/master main master; do
       git rev-parse -q --verify "$b^{commit}" >/dev/null && BASE=$b && break
     done
   fi
   # BASE still empty: STOP and ask for an explicit base. Do not continue.
   MB=$(git merge-base "$BASE" HEAD) || exit 1                        # STOP: no merge base
   CHANGED=$(git diff --name-only --diff-filter=d "$MB") || exit 1    # STOP: diff failed
   UNTRACKED=$(git ls-files --others --exclude-standard) || exit 1    # STOP: ls-files failed
   DELETED=$(git diff --name-only --diff-filter=D "$MB") || exit 1    # STOP: diff failed
   SCOPE=$(printf '%s\n%s\n' "$CHANGED" "$UNTRACKED" | sed '/^$/d' | sort -u)
   

   Every command that supplies audit data is checked; only the base-discovery probes may fail, because failure there means "try the next candidate". One diff from the merge base to the working tree covers committed, staged, and unstaged changes. A file that existed at the merge base and is gone from the working tree lands in $DELETED; a file added after the merge base and deleted again appears nowhere. A failed command is never an empty scope.

   If $SCOPE is empty, run no scans: write the report with "Audit completed: 0 findings — empty diff scope", listing $DELETED under "Deleted in diff" if non-empty, and stop. If the resolved surface exceeds the context budget, report the file count and ask to narrow or chunk.

   Record provenance. Capture git rev-parse --short HEAD and whether the working tree is dirty (git status --porcelain -- $SCOPE); both go in the report's Scope section. On a dirty tree, line numbers match no commit — state that findings must be re-located by symbol name.

   The raw manifest is immutable and language-independent. Do not redefine it on a mixed scope — silently narrowing breaks the party guarantee that all hunters audit the same surface.

   Whitespace in paths is unsupported. The newline-delimited manifest plus -- $SCOPE shell expansion word-splits on spaces; whitespace paths are a declared limitation.

2. Detect languages from manifest extensions alone:

   • .go → go
   • .py, .pyi → python
   • .ts, .tsx, .mts, .cts → typescript

   Supported languages are Go, Python, and TypeScript. Every other extension — .js, .jsx, .mjs, .cjs included — is excluded, not audited: without a reference there is no unit vocabulary, no eligibility rule, no scan set, no remedy vocabulary. Record excluded — no reference for .<ext>: {count} files in Scope, naming each extension.

3. Load language references. For every detected language, read references/solid-<lang>.md from the directory this SKILL.md was read from (e.g. references/solid-go.md). Fail closed: if a required reference cannot be read, stop and report; do not continue with the universal categories only.

4. Derive per-language eligible subsets by applying each reference's generated-code and vendoring rules plus the test-path exclusion to that language's files. These subsets are then immutable. Record in Scope: raw manifest count, each per-language eligible subset, exclusions with the test paths listed, and References loaded: {go, python, typescript as present}.

   Drop from eligibility only: vendored trees, lockfiles, Markdown-only inputs, test paths, and generated files identified by each reference's authoritative in-file marker — never by filename guessing.

   If nothing eligible remains: write Audit completed: 0 findings — no eligible source in scope and stop before scanning.

   Two surfaces. Findings are reported only against the target scope — every finding anchors (file:line) there. Files outside it, test files included, are read as context: enumerating an interface's consumers, an abstraction's implementors, or a discriminant's dispatch sites routinely leaves any diff scope. Diff and path scope narrow the manifest, never the context reading.

5. Read repository instructions (CLAUDE.md, AGENTS.md, .cursor/rules/) for stated policies: the architecture style the project chose, framework conventions, sanctioned wiring mechanisms, layers that are deliberately concrete. A stated policy is respected and acknowledged in the report's Policy: line.

6. Identify the composition root(s) and the architecture style. Roots are identified by what a function does — constructs, wires, returns or runs, decides nothing about the domain — not by path; cmd/, main.go, an app factory, a container module, a Nest module nominate the search. Existing wire / fx / container wiring is recognized as a root; neither is recommended for adoption. Record the style in Scope as Architecture style: {struct-based / class-based / mixed / functional (limited findings)}. In a primarily functional codebase the struct/class categories fire only where structs, classes and interfaces exist, and Go package-level Responsibility Sprawl fires regardless.

No toolchain step. No supported language has a SOLID analyzer a project would configure; none is invented, and nothing is installed. The report carries no Toolchain lines.

Phase 2: Scan for Candidates

Scans produce candidates only. For each loaded reference, run its Phase 2 scan block against that language's eligible subset (SCOPE=. in codebase mode). Pass an explicit path to every rg invocation. Diff mode nominates from the working tree over the manifest files, not from added lines: design is a property of the current code.

Phase 3: Enumerate Implementors, Consumers, and Dispatch Sites

Project-wide, regardless of scope — an interface's consumers and a discriminant's dispatch sites live outside any diff. For each nominated unit:

• Abstractions: every implementor, every production consumer, every test double, and for each consumer the subset of members it calls.
• Discriminants: every dispatch site, and the history test — git log -S '<discriminant value>' (or the diff under review) to see whether a variant addition touched two or more of them.
• Units: every collaborator the unit stores, where each one is created, and which composition root (if any) builds it.
• Actors: who asks for changes to each member — inferred from the member's concern (persistence, transport, rules, notification), corroborated by history where it is available.

Structural typing bounds this phase: regex finds implements clauses and explicit subclassing only. Unannotated structural implementors (TypeScript, Python Protocol) are found by reading the interface's consumers. Record in Scope what was searched and that implementors outside the searched consumers — external packages included — are not found; findings claim the enumerated set only.

Phase 4: Evaluate Each Finding

For each candidate: apply Not-a-finding first; confirm the unit exists in that file's language (see Applicability); apply the three ownership tests — contract type vs data variant, open vs closed, existence vs width — and the within-skill routing between Broken Substitution and Fat Interfaces; then clear the category's evidence bar from What to Hunt. Check repository policy: a Policy: line withdraws what it names. Run each loaded reference's Phase 4 block for its language-specific judgment.

Assign Severity and Impact to every finding (both required; they diverge). One finding per site. Nothing is held back; Audit completed: N findings counts every reported finding.

Phase 5: Produce Report

Save as YYYY-MM-DD-solid-hunter-audit-{model-name}.md — {model-name} is the executing model's short name (e.g. fable-5) — in the project's docs folder (or project root if none exists). A caller-specified output path or return mode (e.g. the party-hunter orchestrator) overrides this default.

Read references/report-format.md for the report template and per-category table schemas.

Red Flags — stop and re-check

…(truncated)