@ai-agent-lead/skills 1.0.0

package/skills/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [skills/LANGUAGE.md](../LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,41 @@
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [skills/LANGUAGE.md](../LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. 
+
+**Assign each sub-agent a specific persona from [`skills/design/PERSONAS.md`](../design/PERSONAS.md)** (e.g., Agent 1 is "The Minimalist", Agent 2 is "The Extensible").
+
+Include both [skills/LANGUAGE.md](../LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in EXISTING code, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Use for EXISTING code; for designing the shape of a new module from scratch, use `design`. Skip for single-module local refactors with no cross-module impact — use `design` or just refactor inline.
+complexity: high
+expected_duration: 45 minutes
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+## When to use
+
+- The user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable.
+- Mid-project in `tdd-rounds`, after the load-bearing seams exist — surface candidates that become dedicated refactor rounds.
+- After [`zoom-out`](../zoom-out/SKILL.md) reveals shallow modules in an unfamiliar area.
+
+## When to skip
+
+- Designing the shape of a new module from scratch — use [`design`](../design/SKILL.md).
+- Greenfield system topology — use [`system-design`](../system-design/SKILL.md).
+- Single-module local refactor with no cross-module impact — use `design` or refactor inline.
+- Line-level cleanup (renames, dead-code removal) — use [`code-hygiene`](../code-hygiene/SKILL.md) + [`simplify`](../simplify/SKILL.md).
+
+## Glossary
+
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [skills/LANGUAGE.md](../LANGUAGE.md).
+
+- **Module** — anything with an interface and an implementation (function, class, package, slice).
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+
+Key principles (see [skills/LANGUAGE.md](../LANGUAGE.md) for the full list):
+
+- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.**
+- **One adapter = hypothetical seam. Two adapters = real seam.**
+
+This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+Read the project's domain glossary ([`docs/CONTEXT.md`](../../docs/CONTEXT.md)) and any ADRs in [`docs/adr/`](../../docs/adr/) for the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
+
+**Use CONTEXT.md vocabulary for the domain, and [skills/LANGUAGE.md](../LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-plan` (see [`../formats/CONTEXT-FORMAT.md`](../formats/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [`../formats/ADR-FORMAT.md`](../formats/ADR-FORMAT.md).
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+
+### 4. Context Splitting
+
+When a single `CONTEXT.md` becomes a bottleneck (>100 terms), the codebase is likely ready for context splitting.
+
+- **Identify Seams**: Find logical boundaries where domain terms are largely independent.
+- **Extract Sub-Contexts**: Move terms into `<module>/CONTEXT.md` files.
+- **Update CONTEXT-MAP.md**: Create or update the root [`docs/CONTEXT-MAP.md`](../formats/CONTEXT-MAP-FORMAT.md) to point to the new sub-contexts.
+- **AI-Navigability**: This reduces context pollution, allowing agents to focus only on the relevant vocabulary for a given module.
+
+## Pairing with other skills
+
+- **[`zoom-out`](../zoom-out/SKILL.md)** — runs *before* if the area is unfamiliar. Map first, then propose.
+- **[`design`](../design/SKILL.md)** — shares vocabulary ([`LANGUAGE.md`](../LANGUAGE.md)). `design` is the greenfield twin of this skill.
+- **[`system-design`](../system-design/SKILL.md)** — the system-level twin. Greenfield topology vs brownfield deepening.
+- **[`grill-plan`](../grill-plan/SKILL.md)** — invoked when a candidate hits an ADR that needs revisiting (or when a rejection deserves an ADR).
+- **[`tdd`](../tdd/SKILL.md) / [`tdd-rounds`](../tdd-rounds/SKILL.md)** — runs *after* the candidate is chosen. Refactor rounds: ACs are "all existing tests still green".
+- **[`prod-ready`](../prod-ready/SKILL.md)** — gate before merge.
+
+## Done when
+
+For each candidate the user chose to explore:
+
+- The deepened module's interface has been sketched (small surface, clear seam).
+- Implications for tests are named (which existing tests survive; which need updating).
+- Any new domain terms used are added to `CONTEXT.md`.
+- Any architectural decision worth preserving is offered as an ADR.
+
+If the user wants to deepen multiple candidates, run the skill again per candidate — don't batch them in one pass.

package/skills/investigate/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: investigate
+description: Use when the user asks for investigation, research, a proposal, or "options" before any code lands; or proactively for non-trivial structural decisions (new dependency, framework choice, API contract change, cross-cutting refactor). Triggered by phrases like "investigate X", "research Y", "give me a proposal", "what are our options", "how would we approach", "let's explore", "should we...". Produces a durable research note in `docs/research/<topic>.md`. Skip for tasks where one obvious approach exists (typo fixes, config tweaks, mechanical refactors). Pairs with `feature-doc` (captures *what* we're building once a direction is chosen) and `grill-plan` (stress-tests a chosen plan).
+complexity: medium
+expected_duration: 20 minutes
+---
+
+# Investigation Workflow
+
+Investigation is a separate phase from implementation. It produces a durable artifact — a research note in `docs/research/<topic>.md` — that captures what's true today, the viable approaches, and the recommendation with its tradeoff. The artifact survives the conversation; future contributors can reach for it.
+
+## When to use
+
+- The user explicitly asks for investigation, research, a proposal, options, or "how would we approach X".
+- A non-trivial structural decision is on the table: new dependency, new architectural pattern, framework choice, contract change, cross-cutting refactor.
+- The decision passes the same bar as an ADR: hard to reverse, surprising-without-context, or the result of a real trade-off.
+
+## When to skip
+
+- One obvious approach (typo fixes, config tweaks, mechanical refactors).
+- Pure execution of an already-decided plan.
+- Bug fixes that don't change architecture.
+
+## Phases
+
+Each phase is a stop. Don't start the next until the previous is grounded.
+
+### 1. Survey the current state — read first, claim later
+
+Do not work from impressions. Read the relevant files and ground every claim in the artifact in something cite-able (`path:line`). Specifically check:
+
+- **The relevant code paths.** Read entire functions, not just headers. If a behavior is being challenged, read the test that pins it.
+- **Existing ADRs** (`docs/adr/`). A prior decision may already constrain the space — surface it; do not relitigate without flagging.
+- **`CONTEXT.md`** if the topic touches domain language. Get the terms right before writing anything down.
+- **Feature docs** (`docs/features/`) for acceptance criteria already committed.
+- **Open follow-ups** in the codebase (TODO/FIXME) related to the topic.
+- **Known Issues Ledger** (`docs/known-issues.md`). Check for historical "surprises" or wire-shape drifts found during past end-to-end verifications in this area. Learning from past failures prevents repeating them.
+
+The Context section of the artifact lists what you found, with citations. Not what you guessed.
+
+### 2. Map the design space — 2 to 3 options
+
+Aim for 2 to 3 genuinely viable options. One option is not a design space; six is performance art. For each option capture:
+
+- **Approach** — one or two sentences. Concrete, not abstract.
+- **Pros** — what makes this attractive.
+- **Cons** — what hurts. Don't soft-pedal — if you'd reject the option later, name the reason now.
+- **Fit with project** — does it align with existing ADRs, conventions, the level of ceremony the team uses? Misfit isn't disqualifying but should be explicit.
+- **Main tradeoff** — one line. The thing being accepted if this option is picked.
+
+If you found only one option, say so and explain why other paths were ruled out. Do not pad with strawmen.
+
+### 3. Recommend — with reasoning
+
+Pick one option. Name it. Give explicit reasoning. Name the tradeoff being accepted. If the recommendation genuinely depends on user preference, say which preferences map to which option — do not punt the decision back without structure.
+
+### 4. Checkpoint questions
+
+Identify the user decisions that must land before any code does. Examples:
+
+- "Do you want X or Y?"
+- "Is the team OK with adding dependency Z?"
+- "Should I draft an ADR first or start the implementation?"
+
+Each question should be answerable; if it's open-ended, sharpen it.
+
+### 5. (Optional) Independent review
+
+For high-stakes artifacts — specs, ADRs, anything load-bearing for cross-team alignment — spawn an independent reviewer agent (e.g., `general-purpose`) with a self-contained brief and the artifact path. Do not delegate the synthesis; ask for a critique against specific axes (correctness, completeness, internal consistency).
+
+## The artifact
+
+Save the research note to `docs/research/<short-topic>.md`. Use [`templates/research-note.md`](./templates/research-note.md) as the skeleton. Create `docs/research/` lazily on first use.
+
+The note must include:
+- **Context** with citations.
+- **Options** — 2 to 3, each with the five fields above.
+- **Recommendation** with reasoning and the accepted tradeoff.
+- **Checkpoint questions** the user must answer.
+- **Out of scope** — explicit, so adjacent decisions don't silently leak in.
+
+## Rules
+
+- Do **not** start implementing inside the investigation. Stop at the artifact and the recommendation; wait for the user to choose.
+- Do **not** narrow to one option silently. If only one option survives, the artifact must explain why the others were ruled out.
+- Do **not** conflate research with planning. A plan executes a chosen option; research surfaces options.
+- Do **not** skip the artifact for "small" investigations. The discipline of writing it is the value; the durable trail is the bonus.
+- Do **not** add a Recommendation that just lists the options again. Pick one.
+
+## Handoff
+
+Once the user picks an option:
+
+- Mark the research note **Decided** and bold the chosen option in the Recommendation section.
+- If the decision is hard-to-reverse / surprising-without-context / the result of a real tradeoff → write an ADR (use `grill-plan`, or write directly into `docs/adr/`). Link the ADR back from the research note.
+- If a concrete feature is now being built → run `feature-doc` next; link it from the research note.
+- If the chosen option requires later validation → leave the research note Open and add a "Follow-ups" section.

package/skills/investigate/templates/research-note.md

@@ -0,0 +1,84 @@
+# Research: <topic>
+
+**Status:** Open | Decided | Superseded
+**Owner:** <user>
+**Date:** YYYY-MM-DD
+
+<!--
+Status values:
+- Open       — investigation in progress, or written and awaiting decision
+- Decided    — user has chosen an option; record it on the Decision line below
+- Superseded — replaced by a later research note or ADR; link the replacement
+-->
+
+**Decision:** _<pin the chosen option here once decided, e.g., "Option B — decided 2026-05-07">_
+
+## Context
+
+What's true today. Each claim should be cite-able (file:line, ADR number, doc heading). Include:
+- The problem or question that triggered the investigation.
+- Relevant code paths and what they do today.
+- Prior ADRs / feature docs / `CONTEXT.md` entries that constrain the space.
+- Existing follow-ups (TODO/FIXME) related to the topic.
+
+## Options
+
+### Option A — <short name>
+
+- **Approach:** one or two sentences, concrete.
+- **Pros:** what makes this attractive.
+- **Cons:** what hurts. Don't soft-pedal.
+- **Fit with project:** alignment with existing ADRs / conventions / team ceremony level.
+- **Main tradeoff:** one line.
+
+### Option B — <short name>
+
+- **Approach:**
+- **Pros:**
+- **Cons:**
+- **Fit with project:**
+- **Main tradeoff:**
+
+### Option C — <short name>
+
+(Optional. Two to three options total. One is not a design space; six is performance art.)
+
+## Recommendation
+
+Option **X**.
+
+**Reasoning:** ...
+
+**Tradeoff being accepted:** ...
+
+## Open Questions
+
+Research-level unknowns the team carries forward — uncertainties to validate later, not blockers for the decision.
+
+(Distinct from Checkpoint Questions below: those are decisions the *user* must answer before code lands; these are unknowns nobody yet has the answer to.)
+
+- ...
+
+## Checkpoint Questions
+
+Decisions the user must make before any code lands. Each question should be answerable.
+
+1. ...
+2. ...
+
+## Out of Scope
+
+Decisions deliberately deferred from this investigation.
+
+(Distinct from a feature doc's "Non-Goals", which lists *capabilities deliberately not built*.)
+
+- Things the investigation deliberately does not cover.
+- Adjacent decisions that should get their own research note.
+
+## Handoff
+
+Once a direction is picked:
+- Update **Status** to `Decided` and fill in the **Decision** line at the top.
+- Bold the chosen option in the Recommendation section.
+- If the decision is hard-to-reverse, surprising-without-context, and the result of a real tradeoff → write an ADR and link it here.
+- If a feature follows → invoke `feature-doc` and link the resulting feature doc here.

package/skills/pr-review/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: pr-review
+description: Discipline for reviewing someone else's pull request — the inverse of `prod-ready` (which is the author's pre-merge gate). Use when the user asks to "review this PR", "look over the diff", "check this change", "give feedback on", or invokes a code-review slash command. Reviews against the linked feature doc / ADRs / domain vocabulary, classifies findings by severity (blocker / suggestion / nit), and returns a structured report. Skip for trivial PRs (typo, dep bump, lint-only) — approve directly. Pairs with `prod-ready` (the author's checklist; the reviewer verifies it landed honestly), `security-review` (escalation when the diff is surface-changing), and `code-hygiene` (the line-level lens applied during the read).
+complexity: medium
+expected_duration: 20 minutes
+---
+
+# PR Review
+
+The author's job is to write a defensible change. The reviewer's job is to verify the **claim** (what the PR says it does) matches the **diff** (what it actually does), against the **contract** (what the feature doc / ADR / tests said the change should be).
+
+Most bad PR reviews are line-by-line nit fests that miss the load-bearing decisions. This skill flips the order: read the *claim* first, verify it, then walk the diff.
+
+## Why this skill exists
+
+- A PR reviewed line-by-line without context produces lots of comments and misses the architectural drift.
+- A PR rubber-stamped after skimming the description misses the security / consistency / scope-creep failures.
+- A reviewer who treats every concern as equal severity exhausts the author's attention and dilutes signal.
+
+This skill produces a **prioritised** review where blockers are unambiguous, suggestions are framed as suggestions, and nits are clearly nits — so the author knows what must change vs what's optional.
+
+## When to use
+
+- The user asks for a PR review (any phrasing).
+- Reviewing a Builder's round in `tdd-rounds` (the parent's verification ritual borrows from this skill).
+- Reviewing your own work before opening the PR — last self-check after `prod-ready`.
+
+## When to skip
+
+- Typo / lint-only / formatter-only diffs. Approve.
+- Dependency bumps with no API change (still: scan changelog for security advisories before approving).
+- Trivial config tweaks with no behavioural change.
+- PRs that are explicitly draft / WIP — give early feedback, but skip the formal severity classification until the author flags ready.
+
+## Process
+
+### 1. Read the claim first
+
+Before opening the diff, read what the PR claims to do:
+
+- **PR description / title** — what's the change? Why?
+- **Linked feature doc** (`docs/features/<name>.md`) — what's the contract? Which ACs?
+- **Linked ADRs** — what decisions does this change rely on or supersede?
+- **Linked research note / known-issues entry** — for fix-rounds, the bug ledger entry doubles as the brief.
+
+If there's no description / no linked artifact / no ACs, **that's the first finding**. A PR without a stated claim is not reviewable — ask the author to add one before continuing.
+
+### 2. Verify the claim against the diff
+
+For each AC / each ledger entry / each promised change:
+
+- Find the test that pins it. Read the test. Does it actually exercise the claim, or does it pass while testing something adjacent?
+- Find the implementation. Does the diff match the claim? Anything extra?
+- Anything **missing** from the diff that the claim said would change?
+- Anything **extra** in the diff that the claim didn't mention? (Scope creep; flag as a finding.)
+
+This step is the difference between "the PR ships what it says" and "the PR ships, plus a surprise refactor and a silent feature flag." Catch the silent additions here.
+
+### 3. Read the diff with the right lenses
+
+In this order — biggest-impact first:
+
+#### 3a. Architectural / interface review
+
+- Does the change respect the dependency direction in `docs/architecture.md` and the existing ADRs?
+- Are new modules deep, or shallow? (Apply the deletion test from [skills/LANGUAGE.md](../LANGUAGE.md).)
+- Are new public types / functions / endpoints named consistently with `CONTEXT.md`?
+- Does anything contradict an ADR without superseding it explicitly?
+
+#### 3b. Test review
+
+- Does each new test exercise behaviour through the public interface?
+- Does each test name describe a behaviour, not a function? (See `tdd/TESTS.md`.)
+- Does the test actually fail without the implementation change? If it would still pass on `main`, it's not testing the claim.
+- Are mocks at boundaries only? Internal-collaborator mocks are a smell.
+
+#### 3c. Security review (delegate when surface-changing)
+
+If the diff introduces or alters a trust boundary, identity flow, authorization check, sensitive data path, or external surface — flag that **`security-review` is required** and hold the PR until that review lands. Don't try to inline a half-review of a surface-changing change.
+
+For non-surface-changing diffs: walk `prod-ready` Section 3 (defense-in-depth) bullets; flag specific gaps if you see them, otherwise move on.
+
+#### 3d. Operational review
+
+- Walk `prod-ready`'s checklist sections relevant to the diff. Did the author's `prod-ready` pass actually land? (Verify the timeouts, the migrations idempotency, the structured logging, the doc-map.)
+- A common failure mode: `prod-ready` was checked off but the diff doesn't reflect the changes the checklist would have driven. Treat that as a blocker.
+
+#### 3e. Doc-drift audit
+
+This is the second line of defense for `prod-ready` Section 7. Author may have missed it; reviewer catches what's left. Walk these four questions against the diff:
+
+- **New decision with viable alternatives** → does an ADR exist in `docs/adr/` for it? Does it name what it supersedes? If load-bearing, is it referenced from the code?
+- **New or changed domain term** → has [`docs/CONTEXT.md`](../../docs/CONTEXT.md) been updated? Are `_Avoid_:` aliases listed if there's risk of confusion?
+- **New / removed package, changed public interface, shifted module boundary** → is the feature's design note (`docs/features/<feature>.design.md`) updated? Module map, file layout, public-interface signatures, test boundaries.
+- **Changed acceptance criteria** → does the feature doc reflect what was actually built? Silently-dropped or silently-added behavior is the most common drift class — flag and don't accept "we'll fix in a follow-up".
+
+If any answer is "no" without `n/a + reason`, that's a finding. Severity:
+- **Blocker** — the missing doc is load-bearing for the next reader (ADR for a hard-to-reverse decision; CONTEXT.md entry for a term other PRs will use; AC drift hiding behavior).
+- **Suggestion** — the doc would help but the diff is self-explanatory in isolation.
+
+The doc-map is small enough to walk in 2–3 minutes. Skip it and you're trading 3 minutes now for an hour of orientation in 3 months.
+
+#### 3e. Hygiene (line level)
+
+Apply `code-hygiene` as a lens here, not as a primary phase:
+
+- Names that mislead (boolean returning non-bool, `getX` that mutates, `Manager`/`Helper` suffixes hiding what the thing is).
+- Cleverness that earns its cost? Or could be boring?
+- YAGNI — "in case we need it" parameters / interfaces / classes? Strip.
+- Premature extraction (Rule of 3 violated)?
+
+Save these for last — they shouldn't outweigh architectural concerns.
+
+### 4. Classify findings
+
+Every finding gets a severity. **The severity is part of the finding.**
+
+- **Blocker** — must change before merge. The PR is wrong, breaks a contract, has a security gap, regresses an AC, or contradicts a load-bearing ADR.
+- **Suggestion** — the author should consider; you'd prefer a change but won't block. Includes design alternatives, missing-but-non-essential tests, hygiene improvements with real impact.
+- **Nit** — taste-level. Naming preferences, whitespace, tiny refactors. The author can resolve or dismiss without further discussion.
+- **Question** — you genuinely don't understand and need the author to explain before you can rank it. Asking "why this approach?" is fine; using questions as passive-aggressive blockers is not.
+
+Default to fewer blockers. A review with 12 blockers is usually a review with 1 blocker and 11 suggestions miscategorised.
+
+### 5. Write the review
+
+Structured, scannable. The author should be able to triage in one read.
+
+```md
+## PR review: <title>
+
+**Verdict**: Approve | Approve with suggestions | Request changes | Needs security-review first
+
+**Claim verification**:
+- Description matches diff: yes / partial — <what's extra or missing>
+- ACs covered: AC-XX (test `name`), AC-YY (test `name`), ...
+- Linked ADRs respected: yes / <which one is in tension>
+
+**Blockers**:
+- [file:line] <issue>. <why it blocks>. <what would unblock>.
+- ...
+
+**Suggestions**:
+- [file:line] <issue>. <why>. <what to consider>.
+- ...
+
+**Nits**:
+- [file:line] <one-liner>.
+- ...
+
+**Questions**:
+- [file:line] <question>.
+- ...
+```
+
+Empty sections: write `_none_` rather than omit. Explicit beats implicit.
+
+## Severity calibration — one rule
+
+If you label something a blocker, you must be able to finish this sentence: *"This change cannot merge as-is because ___."* If your reason is "I'd prefer X" or "in my style", it's a suggestion. If it's "the AC isn't covered" or "the trust boundary is open" or "the ADR contradicts this", it's a blocker.
+
+## Anti-patterns
+
+- **Drive-by approve.** "LGTM" without reading the linked artifacts. The artifacts exist so reviewers can verify the claim; skipping them defeats the discipline.
+- **Re-litigating decided ADRs.** If the change implements an ADR-blessed approach you disagree with, the place to argue is a new ADR (or a `grill-plan` session), not the PR. Note the disagreement, don't block on it.
+- **Miscategorised severity.** Calling a naming preference a blocker burns trust. Calling a missing AC a suggestion misses the point of review.
+- **Architectural review as nit pile.** If you have ten line-level comments and zero architectural finding on a 500-line PR, you reviewed at the wrong altitude.
+- **Reviewing the author, not the diff.** Address the change, not the person. "This function does X, but the AC says Y" — not "you didn't understand the AC."
+- **Ignoring the `prod-ready` line item.** If the PR claims `prod-ready` was run, verify a sample of items. Otherwise it becomes a checkbox both sides ignore.
+
+## When this skill is invoked by `tdd-rounds` parents
+
+A `tdd-rounds` parent verifying a Builder's round runs a focused subset:
+
+1. Read the Builder's structured report (`templates/builder-report.md`).
+2. Run the test command independently — don't trust pasted output.
+3. Read the diff, classify findings.
+4. Tick AC checkboxes in the feature doc with the test names.
+5. Append the round summary to `docs/STATE.md`.
+
+The classification (blocker / suggestion / nit) lives in the parent's notes; only blockers gate the next round.
+
+## Pairing with other skills
+
+- **`prod-ready`** is the author's pre-merge checklist. Reviewer verifies it landed.
+- **`sync-check`** is the diagnostic context auditor. Reviewer runs it (or verifies it was run) to catch terminology drift and ADR contradictions early.
+- **`security-review`** is the surface-change escalation. Reviewer flags when required.
+- **`code-hygiene`** is the line-level lens applied during the read.
+- **`grill-plan`** is where load-bearing disagreements go (a new ADR, not a PR comment thread).
+- **`debug`** if a finding turns out to be "this PR introduces a bug" — switch to debug to characterise it before recommending a change.
+
+## Done when
+
+- The claim is verified or contradicted, with citations.
+- Every finding has a severity, a file:line, and a concrete next step.
+- Blockers are genuinely blocking ("cannot merge because ___").
+- The verdict is one of the four states; ambiguous reviews leave the author guessing.