-
Notifications
You must be signed in to change notification settings - Fork 2
Specialist Depth Review
How a review decides to go deeper than its base pass, and how the result
of going deeper stays one unified review. Canonical:
shared/policies/specialist-depth.md,
routed to from
shared/policies/review-scope.md,
"Domain-specific deepening pass." This page is explanatory only — the
linked policies are the contract.
base semantic reasoning
↓
materially implicated concern
↓
evidence-driven specialist-depth decision
↓
0..N domain-specific deepening capabilities
↓
one unified review
Base semantic reasoning (review-scope.md,
"Semantic change-implication reasoning") runs unconditionally on every
review, for every dimension — no risk domain is opt-in. Some materially
implicated concerns are fully resolved right there. Others — an online
schema migration's backfill risk, a query's cardinality under real data
volume, a distributed failure-mode interaction — genuinely need deeper,
domain-specific reasoning to get right. Deciding when that deeper pass
is warranted, and how 0, 1, or several of them combine, is what this
capability owns. It never decides whether a dimension is considered at
all; that stays base reasoning's unconditional job.
File type, path, framework, language, and dependency name are signals
only — none is independently sufficient to require or suppress deepening.
A *.sql file does not by itself mean "run database specialist depth";
conversely, a persisted-state implication can arise from application code
that touches no .sql file at all (a changed cache-entry shape, a
changed queue-message schema). The trigger is what base reasoning's own
evidence shows, not what kind of file changed. See
specialist-depth.md,
"Activation: evidence-driven, never routed," for the worked contrasts.
A review may require zero, one, or several deepening capabilities. When
several materially implicated dimensions each warrant deepening, they
compose into one review — never independent reviewer verdicts,
severity scales, or output schemas. A capability-contributed finding is
an ordinary finding: same fields, same severity derivation, same
evidence bar. The only thing it additionally carries is an optional
capability provenance label (for example security-deepening) on the
shared finding contract — a provenance annotation, exactly like
contextual evidence and runtime validation, that never calculates,
raises, lowers, or overrides severity, identity, or the decision. A
capability that finds nothing beyond what base reasoning already
established contributes no finding merely to prove it ran.
Cascading activation — one deepening pass surfacing evidence that implicates a further dimension — reuses the existing repository-expansion ring/ceiling procedure and stopping criteria exactly as the base review does elsewhere. It is not a second expansion mechanism, and not recursive "specialist calls specialist" machinery.
Deeper reasoning may strengthen evidence, surface additional findings, or
justify a different severity — but going deeper never, by itself, widens
what the current change is required to fix. Whether remediation is
required at all, and how much belongs inside this change versus
follow-up work, stays governed exclusively by
remediation-scope-boundary.md.
A capability may still legitimately conclude that broader remediation is
required — but that conclusion has to come from the finding's own
evidence, never from how sophisticated the analysis behind it was.
Asking for deeper focus in a named domain ("focus especially on database migration safety") may raise depth there immediately. It can never narrow the base review's per-dimension obligation, suppress other materially implicated dimensions, lower the evidence bar, or change severity/remediation semantics. See Review-Context-and-Existing-Evidence for how this fits alongside review context generally.
Use specialist depth, specialist-depth capability, domain-specific deepening, or adaptive deepening. Avoid "selectable review profile," "selected profile," or "reviewer persona" — there is no user-facing selector, no persistent activation state, and no independent per-capability verdict. ("Profile" still appears as a literal historical name in a few existing paths; that is not the same claim.)
Five domain-specific deepening capabilities exist in the repository
today, each a concrete depth owner for one dimension
review-scope.md
already requires base reasoning to consider unconditionally:
| Capability | Deepens | Canonical policy |
|---|---|---|
| Security | Security / trust-boundary concerns base reasoning identified | security-deepening.md |
| Distributed Systems | Concurrency / distributed-system semantics | distributed-systems-deepening.md |
| Database / Migration | Data / persistence, schema-evolution and migration risk | database-migration-deepening.md |
| Performance | Performance / scale concerns | performance-deepening.md |
| Dependency / Supply Chain | Infrastructure / deployment — manifest, lockfile, base-image, and CI-action changes |
review-scope.md, "Dependency / supply-chain deepening review" |
Each follows the identical shape: it never decides whether its dimension is considered at all (base reasoning always does that); it only decides whether the evidence already gathered justifies tracing further than the base pass affords. None is a generic linter, a CVE/SAST scanner, or a vulnerability feed — each states explicitly what it does not replace in its own policy file. This list reflects what has actually landed; it is not a ceiling on what could be added later, and this page will drift the moment a new one lands unless updated alongside it — see Repository-Documentation-Map.
A dedicated benchmark sub-corpus —
docs/benchmark/corpus/specialist-depth-composition/ —
pins the architecture-level composition contract this page describes,
as distinct from any single capability's domain correctness (which each
capability's own fixture corpus, e.g.
security-deepening/,
already owns). It covers: zero/one/multiple capabilities composing into
one review, a superficial file/path signal that must not force
activation, semantic evidence triggering deepening with no expected file
type, cascading activation bounded by repository-expansion, and depth
never by itself expanding required remediation. It does not re-test any
capability's own domain reasoning — that would duplicate, not extend,
the domain corpora. See
docs/benchmark/corpus/specialist-depth-composition/README.md
for the full case table; this Wiki does not reproduce it.
Per specialist-depth.md,
"What this is not": a reasoning/composition contract, not a runtime
plugin engine. It does not add a generic plugin registry, a deterministic
file/path → specialist router, an external orchestration service, a new
agent per domain, persistent activation state, or a user-facing
specialist selector. The host reviewer performs the deeper reasoning
itself, under this contract.
| Page | What it covers |
|---|---|
| Home | Wiki entry point: what the two Skills are and where to go next. |
| Getting-Started | First steps to package and run either Skill. |
| Choosing-a-Review-Skill | How to decide between local-code-review and github-pr-review. |
| How-the-Review-Model-Works | Concept-level walkthrough of the review pipeline shared by both Skills. |
| Architecture-Overview | Component-level map of how the repository's pieces fit together. |
| Specialist-Depth-Review | When and how a review goes deeper than its base pass. |
| Local-Code-Review-Guide | Usage guide for reviewing local, not-yet-PR'd Git changes. |
| GitHub-PR-Review-Guide | Usage guide for reviewing an existing GitHub Pull Request. |
| Review-Context-and-Existing-Evidence | How optional requirements/context and prior review evidence are supplied. |
| Feature-Pages | Index of per-feature capability pages and their shared template. |
| Feature-Delta-Re-Review | How a re-review scopes itself to only what changed since the last pass. |
| Feature-GitHub-Publication-and-Authorization | What a PR review publishes to GitHub and under what authority. |
| Feature-Human-Style-Review-Output | The senior-engineer-voice prose summary output option. |
| Feature-Requirement-Coverage | How supplied requirements are checked and reported as covered or not. |
| Feature-Runtime-Validation-Evidence | How a review can execute commands or reproductions as evidence. |
| Severity-and-Decision-Model | The P0/P1/P2 severity levels and how the merge decision is derived. |
| Packaging-and-Portability | How the Skills go from source repository to a standalone archive. |
| Development-Workflow | Contributor guide for working on this repository itself. |
| Benchmark-Testing | Orientation to this repository's own review-quality benchmark pipeline. |
| Repository-Documentation-Map | Where each concern's canonical, authoritative source lives. |
| AI-Code-Review-Landscape | Neutral snapshot comparing this project against other AI code-review products. |
| FAQ | Short, practical answers to common questions. |