---
name: catalyst-review-module
description: >
  Deep coherence review of a complete backend module's controllers, services, resolvers, and
  patterns. Audits naming, structure, consistency, and alignment with project skills. Trigger: When
  reviewing a backend module before closing it, or when running /review-module on a backend path.
license: MIT
metadata:
  author: aurora
  version: '1.0'
  auto_invoke: 'Backend module review, coherence audit, service layer analysis'
allowed-tools: Read, Edit, Glob, Grep, Bash, Agent, Task
---

## Purpose

Perform a deep coherence review of an entire backend module to ensure all its pieces — controllers,
services, resolvers, models, DTOs, handlers — form a consistent whole and align with the project's
established patterns.

This is NOT a code simplification pass. It is a **structural and semantic audit**.

## When to Use

- Before closing/finalizing a backend module
- After a significant refactor spanning multiple files
- When onboarding to an unfamiliar module to assess its health
- Periodically as a hygiene check

## Review Process (MANDATORY ORDER)

### 1. Map the Module Tree

Read `backend/.claude/skills/catalyst-project-structure/SKILL.md` to understand the expected
directory structure for the module (API layer, application layer, domain, infrastructure).

Then read the full directory tree of the target module and list every file. Understand the hierarchy
before analyzing anything. Do NOT assume a fixed structure — read the actual directory first and
compare against the project structure skill.

### 2. Load Applicable Skills

Before reviewing, read ALL skills that apply to the module's code:

- `.claude/skills/typescript/SKILL.md` — TypeScript patterns (always applies)
- `backend/.claude/skills/catalyst-handler-composer/SKILL.md` — when the module has handlers (every
  standard module does); source of truth for handler shape, decorator wiring, and the
  handler-vs-service split
- `backend/CLAUDE.md` — backend-specific conventions

These skills define the **expected patterns**. The review compares reality against them.

### 3. Audit Dimensions

Review each dimension and report findings:

#### A. Naming Coherence

- File names match NestJS conventions (`kebab-case.type.ts`)
- Controller, service, and resolver names align with domain language
- DTO names follow a consistent pattern (`Create{Entity}Dto`, `Update{Entity}Dto`)
- Model field names align with the Aurora YAML schema definitions
- No mixed naming styles within the module

#### B. Structural Consistency

- All services use `inject()` function (not constructor injection) consistently
- Controllers follow the same method ordering (CRUD order or by domain operation)
- Resolvers mirror controller patterns where both exist
- DTOs use class-validator decorators consistently
- No orphaned files (created but never imported/used)

#### C. Layered Architecture

- Controller > Service > Repository separation is respected
- No business logic in controllers (controllers only delegate)
- No direct model access from controllers (always through services)
- Guards and interceptors are applied at the right level
- No circular dependencies between services

#### D. API Consistency

- Endpoint naming follows RESTful conventions or GraphQL schema patterns
- Response shapes are consistent across similar operations
- Error handling follows the same pattern throughout the module
- Pagination, filtering, and sorting follow aurora-criteria patterns

#### E. Explicit Code

- Variable and function names describe **what**, not **how**
- No nested ternaries or dense one-liners that obscure intent
- Public/exported functions have explicit return types
- Intermediate variables are used to clarify complex expressions
- Service methods have clear, domain-driven names

## Output Format

Generate a report with this structure:

```markdown
## Module Review: {module-name}

### Summary

{1-2 sentences: overall health assessment}

### Findings

#### Aligned

- {Things that are correct and consistent}

#### Inconsistencies

- {Pattern divergences, naming mismatches, structural issues}
- Each item: **What** is wrong > **Where** (file:line) > **Why** it matters > **Suggested fix**

#### Critical

- {Violations of REQUIRED patterns from skills, broken conventions}

### Metrics

| Dimension              | Status                  |
| ---------------------- | ----------------------- |
| Naming Coherence       | OK / Warning / Critical |
| Structural Consistency | OK / Warning / Critical |
| Layered Architecture   | OK / Warning / Critical |
| API Consistency        | OK / Warning / Critical |
| Explicit Code          | OK / Warning / Critical |

### Recommended Actions

1. {Prioritized list of actions to fix findings}
```

## CRITICAL

- **Read skills before reviewing** — you cannot assess alignment without knowing the standard
- **Report facts, not opinions** — every finding must reference a specific file and line
- **Don't auto-fix** — this is an audit. Present findings and let the user decide what to act on
- **Scope to the module** — don't review code outside the target module unless it directly impacts
  coherence
