@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/skills/review/review-architecture/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: review-architecture
+description: |
+  Use when: reviewing code for architectural violations — layer violations, dependency direction
+  mistakes, module boundary coupling, SOLID principle breaches, NestJS module/provider structure,
+  React MVVM boundary violations, or MobX store layer misplacement.
+  Triggered by: "review architecture", "check architecture", "architectural review",
+  or dispatched by review-orchestrator with --architecture or --backend.
+  NOT for: style/naming preferences, logic correctness bugs, or security vulnerabilities.
+version: "1.0.0"
+triggers:
+  - "review architecture"
+  - "check architecture"
+  - "architectural review"
+  - "architecture review"
+  - "check layers"
+  - "dispatched by review-orchestrator"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode,claude"
+---
+
+# Review Architecture
+
+Specialized reviewer for **architectural patterns and structural decisions**.
+Reviews only changes introduced in the current branch (merge-base to HEAD).
+Focuses exclusively on verifiable structural violations — not style opinions or hypothetical concerns.
+
+---
+
+## Workflow
+
+```
+Architecture Review Progress:
+- [ ] Step 1: Read Job Context (if provided) — understand intentional stack choices
+- [ ] Step 2: Determine git scope (merge-base)
+- [ ] Step 3: Collect diff and changed file list
+- [ ] Step 4: Identify stack (NestJS, React+MobX, generic TS, mixed)
+- [ ] Step 5: Check layer assignments and dependency direction
+- [ ] Step 6: Check module/provider boundaries
+- [ ] Step 7: Check design pattern correctness (Repository, DI, MVVM)
+- [ ] Step 8: Check SOLID violations
+- [ ] Step 9: Check framework-specific concerns (NestJS / React / MobX)
+- [ ] Step 10: Emit findings in unified format
+```
+
+---
+
+## Input Contract
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `branch` | string | no | Branch to review. Defaults to current branch. |
+| `commit_range` | string | no | Explicit hash or range. Overrides merge-base detection. |
+| `context_doc` | string | no | Path to job context document. Read before reviewing to understand intentional decisions. |
+| `stack_hint` | string | no | Optional hint: `nestjs`, `react-mobx`, `generic-ts`. Reviewer auto-detects if absent. |
+
+---
+
+## Scope Detection
+
+See shared script: `skills/shared/git-merge-base.md`
+
+Run the script to determine `BASE_SHA`, then collect the diff:
+
+```bash
+# Changed files — used for stack auto-detection
+git diff --name-status "${BASE_SHA}"
+
+# Full diff — used for finding exact violations
+git diff "${BASE_SHA}"
+
+# Untracked new files
+git ls-files --others --exclude-standard
+```
+
+Review scope: **changes introduced in the current branch since merge-base only**.
+Do not review pre-existing architectural problems unless they are directly touched by the diff.
+
+---
+
+## Stack Auto-Detection
+
+When `stack_hint` is not provided, infer from changed file paths:
+
+| Signal | Detected stack |
+|--------|---------------|
+| `*.module.ts`, `*.controller.ts`, `*.provider.ts`, `@Injectable`, `@Module` | NestJS |
+| `*.store.ts`, `makeObservable`, `observable`, `action`, `computed` (MobX) | React + MobX |
+| `*.tsx` / `*.jsx` | React (check MVVM boundaries) |
+| `prisma/`, `*.repository.ts`, `*.entity.ts` | Backend data layer |
+| Mixed signals | fullstack — apply all relevant checks |
+
+---
+
+## Focus Areas and Checklist
+
+### Layer Violations
+
+A **layer violation** occurs when code belonging to one architectural layer is placed in another.
+Common layers (adapt to the project's actual layering):
+
+```
+UI (View) → ViewModel / Store → Service → Domain → Infrastructure (DB, HTTP)
+```
+
+- [ ] API call or HTTP client import inside a React component (should be in store/service)
+- [ ] Business logic inside a controller (should be in service/use-case)
+- [ ] Database query directly inside a service bypassing the repository layer
+- [ ] Domain entity mutating itself with HTTP response data (infrastructure leaking into domain)
+- [ ] UI component computing derived state that belongs in a ViewModel or computed property
+
+### Dependency Direction
+
+Dependencies must flow **inward** (from infrastructure toward domain), never outward.
+
+- [ ] Domain module importing from infrastructure (e.g., domain entity importing ORM types)
+- [ ] Core/shared module importing from feature module (inverted dependency)
+- [ ] Circular import between modules (A imports B, B imports A)
+- [ ] Barrel file (`index.ts`) that creates hidden circular references
+
+### Module Boundary Violations
+
+- [ ] Feature A directly accessing feature B's internal service instead of a public API/facade
+- [ ] Shared `utils/` or `common/` module containing domain-specific business logic
+- [ ] Cross-module data transformation happening in the wrong module
+
+### Design Pattern Misuse
+
+**Repository pattern:**
+- [ ] Repository method containing business logic (filtering/transformation beyond simple queries)
+- [ ] Service bypassing repository and using ORM/DB client directly
+- [ ] Multiple repositories doing the same data transformation independently
+
+**Dependency Injection:**
+- [ ] `new SomeService()` inside a class that should receive it via DI
+- [ ] Service locator pattern used instead of constructor injection
+- [ ] Singleton service holding request-scoped state
+
+**CQRS / Use-case:**
+- [ ] Command handler performing a query and returning domain data (mixed responsibility)
+- [ ] Use-case importing another use-case (chain via domain events instead)
+
+### SOLID Violations
+
+Focus on **SRP** and **DIP** — the two most commonly violated in practice.
+
+**SRP (Single Responsibility):**
+- [ ] Class/module doing two unrelated things (e.g., handles auth AND sends emails)
+- [ ] Service with >5 injected dependencies (smell: likely SRP violation)
+- [ ] Component rendering UI AND fetching data AND computing derived state
+
+**OCP (Open/Closed):**
+- [ ] `switch`/`if-else` chain over a type discriminant that will grow (should be polymorphism or strategy)
+
+**LSP (Liskov Substitution):**
+- [ ] Subclass overriding a method with stronger preconditions or weaker postconditions
+
+**ISP (Interface Segregation):**
+- [ ] Implementing interface that forces implementing methods never used by this class
+
+**DIP (Dependency Inversion):**
+- [ ] High-level module importing a concrete low-level class (should import an abstraction)
+- [ ] Infrastructure class passed directly through multiple layers instead of behind an interface
+
+### NestJS-Specific
+
+- [ ] `@Injectable` service used across modules without being exported from its owning module
+- [ ] `@Global()` overused — global providers for non-truly-global concerns
+- [ ] Circular dependency between NestJS modules without `forwardRef`
+- [ ] Provider scope mismatch: `REQUEST`-scoped service injected into `DEFAULT`-scoped service
+- [ ] Controller fat with business logic that belongs in the service layer
+- [ ] `@Module` imports array including modules it does not need (unnecessary coupling)
+
+### React + MVVM (with MobX)
+
+- [ ] Business logic directly in a component (should be in store action or computed)
+- [ ] `useEffect` performing state orchestration that belongs in a MobX reaction or action
+- [ ] Store method calling another store's `private` action directly (should go through public API)
+- [ ] Component subscribing to raw observable fields instead of using computed/derived values
+- [ ] View rendering based on multiple raw observable fields instead of a single computed boolean
+
+### MobX Store Layer
+
+- [ ] `@action` performing async work without wrapping in `runInAction` on resolution
+- [ ] `@computed` with side effects (computed must be pure)
+- [ ] Observable state mutated outside of an `@action` (MobX strict mode violation)
+- [ ] Store importing from another store's internal file instead of its public export
+- [ ] Inter-store callback (`onChangeX`, `handleX`, `syncX`) declared `public` when only used internally (should be `private`)
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| Layer violations, dependency direction, module coupling | YES | — |
+| SOLID violations (SRP, DIP, OCP, LSP, ISP) | YES | — |
+| NestJS module/provider/scope issues | YES | — |
+| React MVVM boundary, MobX store layer | YES | — |
+| Logic bugs, off-by-one, null safety | NO | `review-logic` |
+| Security vulnerabilities (injection, auth bypass) | NO | `review-security-code` |
+| Style, naming, import order | NO | `review-style` |
+| Performance (bundle size, render cost, query plan) | NO | `review-performance` |
+| MobX store internals deep-dive | surface violations only | `code-mobx-store-review` for full store audit |
+
+---
+
+## Orchestrated Review Contract
+
+When dispatched by `review-orchestrator`, follow the provided `reviewer-input.schema.json` payload. Return a `REVIEW_RESULT` object compatible with `skills/review-orchestrator/reviewer-finding.schema.json`, then a concise markdown summary. Keep findings evidence-based, include concrete `suggested_fix` for every blocker/major, and return `NEEDS_CONTEXT` instead of guessing when required context is missing.
+
+---
+
+## Finding Format
+
+### Class scope — required for `blocker` and `major`
+
+Every `blocker` and `major` finding must carry `class_scope`: **every** site that
+holds the shape you found, and **how you enumerated them** — the grep or query
+you ran, or the guard that derives the set.
+
+A finding anchored to one `file:line` is a claim about one site. The recorded
+history of this repository is that a fix then repairs that site and leaves its
+siblings: one writer of five, one operator instruction of four, six readers of
+eight. Each was found by the *next* review round, which is why reviews here have
+run to seven and four rounds instead of one.
+
+```yaml
+class_scope:
+  sites: ["src/lib/shell-config.ts:60", "src/session/store.ts:133"]
+  enumeration_method: "grep for the config-path resolvers; 7 writers, 2 unguarded"
+```
+
+"I checked the others" is not an enumeration method. A single-entry `sites` list
+is a claim that the class has exactly one member — make it deliberately, because
+`review-finding.schema.json` accepts it and the next round tests it.
+
+`minor` and `info` may omit it: enumerating the class for every low-severity
+observation is theatre, not rigour.
+
+```markdown
+### [F-NNN] Title
+
+- **Severity**: blocker | major | minor | info
+- **File**: path/to/file.ts:line
+- **Problem**: what architectural rule is violated and how
+- **Why it matters**: impact on testability / maintainability / correctness
+- **Fix**: concrete structural change
+- **Patch** (optional):
+  ```diff
+  - old line
+  + new line
+  ```
+```
+
+Severity guide for this reviewer:
+
+| Severity | When to use |
+|----------|------------|
+| `blocker` | Circular dependency causing runtime failure; NestJS module scope mismatch causing incorrect behavior; domain importing infrastructure breaking testability entirely |
+| `major` | Clear layer violation (API call in component, business logic in controller); broken DIP; cross-module boundary coupling that will cause maintainability failures |
+| `minor` | SRP smell with clear separation path; ISP violation; component using multiple raw observables instead of computed |
+| `info` | Architectural opinion without clear violation; pattern that could be improved but works correctly |
+
+Iron laws:
+- Only flag actual violations found **in the diff**, not pre-existing issues untouched by the change.
+- Every finding MUST cite a specific `file:line` from the diff.
+- Architecture opinions without a clear, named violation (layer, SOLID principle, pattern misuse) are `info` only — never `blocker` or `major`.
+- Do not flag correct framework usage as a violation just because an alternative exists.
+
+---
+
+## Output Contract
+
+```
+STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+```
+
+| Status | Meaning |
+|--------|---------|
+| `DONE` | No blockers or majors found; architecture is sound in this diff |
+| `DONE_WITH_CONCERNS` | One or more blocker or major findings present |
+| `NEEDS_CONTEXT` | Cannot determine correct layering without knowing the project's architecture decisions |
+| `BLOCKED` | Cannot access diff or required files |
+
+```markdown
+## Architecture Review
+
+### Review Scope
+- Branch: `<BRANCH>`
+- Parent ref: `<PARENT>`
+- Merge-base: `<BASE_SHA>`
+- Scope mode: `<default-with-uncommitted | explicit-hash-range>`
+- Stack detected: <NestJS | React+MobX | generic-ts | fullstack>
+
+### Summary
+<2-3 sentences: what structural changes were introduced, overall architectural verdict.>
+
+### Stats
+- blocker: N  |  major: N  |  minor: N  |  info: N
+
+### Layer Violations
+<[F-NNN] findings or "None detected.">
+
+### Dependency Direction
+<[F-NNN] findings or "None detected.">
+
+### Module Boundary Violations
+<[F-NNN] findings or "None detected.">
+
+### Design Pattern Misuse
+<[F-NNN] findings or "None detected.">
+
+### SOLID Violations
+<[F-NNN] findings or "None detected.">
+
+### Framework-Specific (NestJS / React+MobX)
+<[F-NNN] findings or "None detected." or "N/A — not detected in stack.">
+
+### Suggested Patches
+<Minimal unified diffs for straightforward structural fixes. Omit if not warranted.>
+```
+
+---
+
+## Job Context Awareness
+
+When dispatched by `review-orchestrator` or `job-orchestrator`, the prompt MAY include:
+
+```
+JOB_NAME:     <job-name>
+CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md
+```
+
+If provided and the file exists, read the context document **before** reviewing the diff.
+Use it to:
+- Understand which architectural patterns and layers were intentionally chosen
+- Avoid flagging deliberate deviations from the default layer model as violations
+- Identify framework and library choices that affect what counts as a valid pattern
+
+If absent, proceed normally — context is optional and non-blocking.
+When in doubt about whether a pattern was intentional, use `info` severity and note the uncertainty.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "This class is large, so it must violate SRP" | Size alone is not a violation; cite what two unrelated responsibilities it holds |
+| "I see a potential layer violation in a file not in the diff" | Scope is diff-only; pre-existing issues are out of scope unless the diff touches them |
+| "This architecture opinion makes things cleaner, so it's a major" | Opinions without a named violation are `info` only |
+| "I'll flag every cross-import as a boundary violation" | Not all cross-imports violate boundaries; check whether the dependency direction is correct |
+| "The team probably didn't intend this pattern" | Unless the context doc or a clear rule says otherwise, assume intentional; use `info` if unsure |
+| "NestJS global module is always wrong" | `@Global()` is a violation only when used for non-global concerns; framework-provided globals are fine |
+| "I can't determine if this is wrong without knowing the full architecture" | Use `NEEDS_CONTEXT` status and ask one specific question |

package/src/gdskills/bundled/skills/review/review-backend/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: review-backend
+description: |
+  Use when: reviewing NestJS backend changes — API design, service layer, DTO validation,
+  database patterns, and TypeScript correctness. Covers "review backend", "backend review",
+  "review API", "review NestJS", or dispatched by review-orchestrator with --backend flag.
+  NOT for: frontend patterns, MobX, React components, general security vulnerabilities
+  (use review-security-code for XSS/injection/auth-bypass), or performance profiling
+  (use review-performance).
+version: "1.0.0"
+triggers:
+  - "review backend"
+  - "backend review"
+  - "review API"
+  - "review NestJS"
+  - "review --backend"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode,claude"
+---
+
+# Review — Backend (NestJS / API / DB)
+
+Focused backend reviewer covering NestJS patterns, REST API design, database access patterns,
+and TypeScript correctness for service-layer code. This skill does NOT duplicate security or
+performance checks — those belong to `review-security-code` and `review-performance`.
+
+---
+
+## Workflow
+
+```
+review-backend Progress:
+- [ ] Step 1: Read Job Context (if CONTEXT_PATH provided)
+- [ ] Step 2: Determine git scope (merge-base) — see skills/shared/git-merge-base.md
+- [ ] Step 3: Collect diff and changed file list
+- [ ] Step 4: NestJS patterns check
+- [ ] Step 5: API design check
+- [ ] Step 6: Database patterns check
+- [ ] Step 7: TypeScript correctness check
+- [ ] Step 8: Emit findings in unified format, sorted by severity
+```
+
+---
+
+## Input Contract
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `branch` | string | no | Branch to review. Defaults to current branch. |
+| `commit_range` | string | no | Explicit range (e.g., `abc123..HEAD`). Overrides merge-base detection. |
+| `context_doc` | string | no | Path to job context document (e.g., `<JOBS_ROOT>/<job>/ai/context.md`). |
+| `issue_url` | string | no | GitHub issue or task URL for spec compliance reference. |
+
+---
+
+## Scope Detection
+
+See shared script: `skills/shared/git-merge-base.md`
+
+Run that script to determine `BASE_SHA` before collecting the diff.
+
+```bash
+# Default mode — all changes from merge-base to working tree
+git diff --name-only "${BASE_SHA}"
+git diff "${BASE_SHA}"
+
+# Explicit range mode
+git diff --name-only <FROM_SHA>..<TO_SHA>
+git diff <FROM_SHA>..<TO_SHA>
+```
+
+Only review files changed in scope. Do not comment on legacy code outside the diff.
+
+---
+
+## Review Checklist
+
+### 1. NestJS Patterns
+
+**Module structure**
+- `@Module()` declaration present; providers, imports, exports are correctly listed
+- Circular dependency risk: two modules importing each other — flag as `major` if detected; suggest `forwardRef()`
+- Feature modules do not import `AppModule`
+
+**Provider scope**
+- Default scope is `Singleton` — correct for stateless services
+- `REQUEST`-scoped provider injected into a `Singleton` provider is a **blocker** (creates hidden state sharing)
+- `TRANSIENT` scope used unnecessarily when singleton would suffice — flag as `minor`
+
+**DTO validation**
+- All controller methods accepting user input (body, query, param) have a DTO class decorated with `class-validator` decorators
+- Required fields: `@IsString()`, `@IsNumber()`, `@IsEmail()`, etc. present and accurate
+- `@IsOptional()` used only on truly optional fields; non-optional fields must not have `@IsOptional()`
+- `ValidationPipe` applied globally (in `main.ts`) or explicitly via `@UsePipes(ValidationPipe)` — **blocker** if missing on any endpoint accepting user input
+- `@Transform()` used where input coercion is needed (e.g., string → number from query params)
+
+**Guards and roles**
+- Protected endpoints have `@UseGuards(...)` with appropriate guard(s)
+- Role-based access uses `@Roles(...)` decorator with a roles guard — missing guard on an endpoint that should be protected is a **blocker**
+- Public endpoints explicitly marked with `@Public()` or equivalent decorator, not just left unguarded
+
+**Controller responsibilities**
+- Controllers are thin: no business logic, no direct ORM calls, no computation
+- Controller methods do: parse input → delegate to service → return response
+- If business logic is in a controller method, flag as `major` ("move to service layer")
+
+**Service layer**
+- Business logic lives in services
+- Services do not directly call the ORM in complex multi-step ways — that belongs in a repository or query object
+- Services do not import `Request`/`Response` from HTTP framework (except for streaming or special cases)
+- Services declare return types on all public methods
+
+---
+
+### 2. API Design
+
+**HTTP method conventions**
+- `GET` requests carry no body (flag as `major` if present)
+- `POST` used for resource creation
+- `PUT` for full replacement, `PATCH` for partial update — mixed usage without clear reason flagged as `minor`
+- `DELETE` on correct resource path
+
+**Response shape consistency**
+- All endpoints in a controller return the same envelope shape (e.g., `{ data, meta }`) — inconsistency (sometimes object, sometimes raw array) flagged as `major`
+- HTTP status codes match semantics: `201` for create, `200` for read/update, `204` for no-content delete, `404` for not found, `422` for validation failure
+
+**Pagination**
+- List endpoints that could return unbounded datasets must have pagination (`limit`/`offset` or `cursor`)
+- Missing pagination on a list endpoint flagged as `major` when no obvious bound exists
+
+**Error handling**
+- Async controller methods must have error handling: either `try/catch` or a global exception filter
+- Unhandled promise rejections (async method without try/catch, no global filter) — **blocker**
+- Exception messages must not leak internal details (stack traces, ORM error strings) to the HTTP response — leaking is a **blocker**
+- NestJS built-in exceptions (`NotFoundException`, `BadRequestException`, etc.) preferred over generic `Error`
+
+---
+
+### 3. Database Patterns (ORM)
+
+**N+1 queries**
+- Relation loaded inside a loop without eager loading (`relations`, `leftJoinAndSelect`) or a DataLoader — **always major**
+- Example: `for (const user of users) { user.orders = await orderRepo.find(...) }` — flag with concrete suggestion to use `relations: ['orders']` or batch query
+
+**Transactions**
+- Multi-step operations that must be atomic (e.g., create + update + delete across tables) must use a transaction
+- Missing transaction on a multi-step mutation is a **major** finding
+- NestJS TypeORM: use `dataSource.transaction(async (manager) => { ... })` or `@Transaction()` decorator pattern
+
+**Raw query safety**
+- String interpolation in raw queries is a **blocker** (SQL injection risk)
+- Use parameterized queries: `query('SELECT * FROM users WHERE id = $1', [id])`
+- Flag `createQueryBuilder().where('id = ' + id)` as blocker
+
+**Soft deletes**
+- If the project schema uses `deletedAt` / `@DeleteDateColumn()`, deletions must use `.softRemove()` / `.softDelete()`, not `.remove()` / `.delete()`
+- Hard delete on a soft-delete entity flagged as `major`
+
+**Migration safety**
+- Column removed in migration — check that no application code still references it
+- Dropping a column without a deprecation period in a live system flagged as `major`
+- `NOT NULL` column added without a default value to a populated table — **blocker**
+
+---
+
+### 4. TypeScript Correctness
+
+- No `any` in new code — suggest `unknown` with type guards, or correct typed return
+- Public service methods must have explicit return types (`Promise<UserDto>`, not inferred)
+- Service contracts expressed as interfaces (`IUserService`), not just class implementations
+- No `as any` or unsafe casts (`as unknown as T`) without a comment explaining why
+- `@ts-ignore` / `@ts-expect-error` without explanation comment — flag as `minor`
+
+---
+
+## Iron Laws
+
+| Condition | Severity |
+|-----------|----------|
+| Missing DTO validation on an endpoint accepting user input | **blocker** |
+| `REQUEST`-scoped provider injected into `Singleton` | **blocker** |
+| Leaking stack trace / raw ORM error to API response | **blocker** |
+| Unhandled promise rejection in controller method | **blocker** |
+| String interpolation in raw SQL query | **blocker** |
+| N+1 query (relation loaded in a loop) | **major** (minimum) |
+| Missing transaction on multi-step atomic mutation | **major** |
+| Business logic in controller | **major** |
+| Missing pagination on unbounded list endpoint | **major** |
+| `NOT NULL` column added without default to populated table (migration) | **blocker** |
+
+---
+
+## Orchestrated Review Contract
+
+When dispatched by `review-orchestrator`, follow the provided `reviewer-input.schema.json` payload. Return a `REVIEW_RESULT` object compatible with `skills/review-orchestrator/reviewer-finding.schema.json`, then a concise markdown summary. Keep findings evidence-based, include concrete `suggested_fix` for every blocker/major, and return `NEEDS_CONTEXT` instead of guessing when required context is missing.
+
+---
+
+## Finding Format
+
+### Class scope — required for `blocker` and `major`
+
+Every `blocker` and `major` finding must carry `class_scope`: **every** site that
+holds the shape you found, and **how you enumerated them** — the grep or query
+you ran, or the guard that derives the set.
+
+A finding anchored to one `file:line` is a claim about one site. The recorded
+history of this repository is that a fix then repairs that site and leaves its
+siblings: one writer of five, one operator instruction of four, six readers of
+eight. Each was found by the *next* review round, which is why reviews here have
+run to seven and four rounds instead of one.
+
+```yaml
+class_scope:
+  sites: ["src/lib/shell-config.ts:60", "src/session/store.ts:133"]
+  enumeration_method: "grep for the config-path resolvers; 7 writers, 2 unguarded"
+```
+
+"I checked the others" is not an enumeration method. A single-entry `sites` list
+is a claim that the class has exactly one member — make it deliberately, because
+`review-finding.schema.json` accepts it and the next round tests it.
+
+`minor` and `info` may omit it: enumerating the class for every low-severity
+observation is theatre, not rigour.
+
+```markdown
+### [F-001] Title
+
+- **Severity**: blocker | major | minor | info
+- **File**: path/to/file.ts:line
+- **Problem**: what is wrong
+- **Why it matters**: impact on correctness / safety / maintainability
+- **Fix**: concrete suggestion
+- **Patch** (optional):
+  ```diff
+  - old line
+  + new line
+  ```
+```
+
+---
+
+## Output Contract
+
+```
+STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+```
+
+- `DONE` — no blockers or majors found
+- `DONE_WITH_CONCERNS` — one or more blocker or major findings present
+- `NEEDS_CONTEXT` — cannot determine intent without context doc or issue; state what is missing
+- `BLOCKED` — cannot access diff or required files; state reason
+
+```markdown
+# Backend Review Report
+
+## Verdict: APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES
+
+## Summary
+<2-4 sentences covering what changed, overall backend health, key concerns.>
+
+## Review Scope
+- Branch: `<BRANCH>`
+- Parent ref: `<PARENT>`
+- Merge-base: `<BASE_SHA>`
+- Scope mode: `<default-with-uncommitted | explicit-hash-range>`
+- Changed files: <count>
+
+## Stats
+- blocker: N
+- major: N
+- minor: N
+- info: N
+
+## Blockers (must fix before merge)
+<[F-NNN] findings>
+
+## Major Issues
+<[F-NNN] findings>
+
+## Minor & Info
+<[F-NNN] findings>
+
+## Positive Notes
+<Optional. Things done well.>
+```
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| NestJS module / provider / DTO / controller / service | YES | — |
+| REST API shape, HTTP methods, error handling | YES | — |
+| Database ORM patterns, N+1, transactions, migrations | YES | — |
+| TypeScript strictness in service layer | YES | — |
+| XSS, injection (beyond SQL in raw queries), auth bypass | NO | `review-security-code` |
+| Bundle size, query latency profiling | NO | `review-performance` |
+| Frontend, React, MobX | NO | `review-frontend` |
+| Architectural layer violations (cross-module) | NO | `review-architecture` |
+| Naming, style, import order | NO | `review-style` |
+
+---
+
+## Job Context Awareness
+
+When dispatched by `job-orchestrator` or called with an explicit context path, the prompt MAY include:
+
+```
+JOB_NAME:     <job-name>
+CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md
+```
+
+If provided and the file exists, read the context document **before** running scope detection.
+Use it to understand:
+- Which ORM, validation library, or guard strategy was intentionally chosen
+- Project-level architectural decisions (e.g., no repository pattern by design)
+- Acceptance criteria to verify spec compliance
+
+If absent, proceed normally — context is optional and non-blocking.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "ValidationPipe is probably configured somewhere" | Always verify it is applied; assumption lets injection reach service layer |
+| "The N+1 only runs on small datasets now" | Data grows; flag it now with a clear fix, not after the incident |
+| "The controller has some logic but it's minor" | The line is binary — logic in controller = untestable without HTTP stack |
+| "Stack trace in response only shows in dev" | Config can be wrong in prod; treat it as blocker always |
+| "I'll skip the migration check — it's just a column rename" | Column renames without fallback break zero-downtime deploys |