Skip to main content
skill CX Codex

ns-reviewer — Claude Code skill: code review by SOLID and security standards

ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection.

Apache-2.0 140 installs updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-reviewer -a claude-code
Open on GitHub

What ns-reviewer does

ns-reviewer acts as a quality gate: it assesses modified files against a project's unified criteria and assigns an overall score from 1 to 10. Approval requires score 10 with zero critical findings. A score of 9 automatically rejects — you must lift it to 10.

The skill checks SOLID violations (DRY, SSoT, OCP breaks), export safety, and modularity. If state is split across multiple places, a logic block appears in two functions, or extension requires edits at three or more sites, the score caps at 7. It produces fix maps listing concrete issues rather than formal reports, or a brief summary when approved.

Run it after code changes, before opening a PR, at task closure, or to review an existing PR or issue. Depends on ns-harness; do not confuse it with ns-judge (requirement and AC proof) or ns-investigator (root-cause analysis).

What it helps with

  • grade code quality before a pull request
  • spot SOLID violations and duplicated logic
  • verify export correctness and module boundaries
  • catch security issues in changed files
  • get actionable fix list before approval

Example prompts for the agent

  • Review this code for quality before merging
  • ns-reviewer: score these changes against SOLID and security
  • Is this ready to merge or do we need fixes?

How to install ns-reviewer

1Skills CLI (Vercel)

npx skills add nextstage-brasil/skills --skill ns-reviewer -a claude-code

2Manually: put the files in place

~/.claude/skills/ns-reviewer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-reviewer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ns-reviewer

How do I install ns-reviewer in Claude Code?

Run npx skills add nextstage-brasil/skills --skill ns-reviewer -a claude-code, then check ~/.claude/skills/ns-reviewer/SKILL.md for setup details.

What does ns-reviewer do?

It grades modified files on adherence to SOLID, code cleanliness, export safety, and modularity. Approval requires score 10 with no critical issues; score 9 means rejection.

How is ns-reviewer different from ns-judge?

ns-reviewer focuses on code quality and produces fix maps. ns-judge validates requirements, acceptance criteria, and ui-contract — it runs after ns-reviewer approves.

Source text

SKILL.md · Apache-2.0
---
name: ns-reviewer
description: "(NS) Code quality gate: SOLID, clean code, performance, security, testability. `Approved` only at score 10; score 9 = `Rejected`. Use after code changes, before PRs, at implementation closure, or code/PR/issue review — even without naming this skill. Delivery proof is ns-judge after Code Review: Approved. GitLab `ISSUE_URL`: Issue review mode. Do NOT parse requirements.md. Do NOT write code-review-report.md. Do NOT debug root-cause (ns-investigator)."
license: Apache-2.0
metadata:
  author: nextstage-brasil
  version: "2.4"
depends:
  - ns-harness
---

# Code Reviewer

Deep constructive review vs project rules. **Code only.** Delivery proof (`requirements.md` ACs, ledger, ui-contract, visual checklist) = `ns-judge` **after** `Code Review: Approved`. This skill **MUST NOT** dispatch `ns-judge`.

## Caller contract (workflow callers)

Invoker: `ns-coder`, `ns-autonomous`, `ns-execution-gitlab-issue` (direct or harness **`reviewer-agent`**):

- Caller **must** run this skill — **MUST** dispatch `reviewer-agent` when available (`../../ns-harness/references/subagent-dispatch.md`); else read this `SKILL.md` in-session. No Cursor Task personas (`senior-tech-lead-reviewer`, `bugbot`, `security-review`) or improvised review.
- Gate rules: `references/review-gate-workflow.md`.
- Every response to workflow caller **must** end exact line: `Code Review: {Approved|Rejected|Blocked}`. Overall score in **Executive Summary**.

## Session boot

See `../../ns-harness/references/session-boot.md`. **Complete Session boot (blocking)** before any other step — cold start this reviewer run; mid-session skip only if steps 1–6 done and files unchanged. Never tool-Read `AGENTS.md`.

## Workflow

1. **Session boot** — Cold start `reviewer-agent` / this skill: Session boot steps 1–6 in `session-boot.md`. Already booted same agent run (1–6 done), files unchanged: no re-read. Still judge diff vs `AGENTS.md` (in context) + project rules.
2. `git diff` (`git status` if needed).
3. Focus modified files + surrounding context.
4. Start immediately — no permission ask.

### Ad-hoc diff mode (from `ns-coder`)

Invoker passes working-tree diff only (no `ISSUE_URL`, no version-closure path):

1. Review `git diff` on working tree.
2. Apply **Score gate** + severity below.
3. Last line to parent: `Code Review: {Approved|Rejected|Blocked}`

### Version closure

1. Apply **Score gate** (SOLID, security, orphan export, actor/rules). End chat with `Code Review: {Approved|Rejected|Blocked}`.
2. **Do not** parse `requirements.md`. **Do not** walk `spec-coverage.md` / `ui-contract.md` / visual checklist — parent runs `ns-judge` after `Approved` (`../ns-judge/SKILL.md`).
3. **Do not** write `code-review-report.md` (or any persistent review report).
4. `Rejected` / `Blocked`: emit fix map per **Fix map rounds** (`references/review-fix-map.template.md`). No human prose, no positive findings, no history.
5. `Approved`: Executive Summary + score + verdict line only (no fix map). Parent may then invoke `ns-judge`.

### Issue review mode

Invoker passes `ISSUE_URL` (or `project_id` + `issue_iid`):

1. Delegate issue context to `ns-execution-gitlab-issue` context flow or `gitlab-issue-context-agent` — no `read_issue` if synthesis block provided.
2. Diff `origin/<target>...origin/<source>` from synthesis — never wrong branch.
3. **Code only.** Do not run Requirement proof / AC token scan — `ns-judge` **issue** mode after `Approved` (`--ac-file`). Producer-only unused **export** still uses orphan-export cap below.
4. **Verdict (exactly one):** `Approved` | `Rejected` | `Blocked` — **Score gate** below.
5. Post internal GitLab comment via `mcp-gitlab-usage` — first line: `Code Review | YYYY-MM-DD HH:MM (UTC) | Verdict: {Approved|Rejected|Blocked}`
6. Last line to parent: `Code Review: {Approved|Rejected|Blocked}`
7. `Rejected`/`Blocked`: GitLab comment = same fix-map facts (**Fix map rounds**).

### Fix map rounds

**Round 1 (exhaustive):** before write map, walk **every** touched file vs **Score caps** table. Emit **every** Critical **and** every Warning that would still cap score after other rows fixed — duplicate members already in a touched file each get a row (same smell class, multiple symbols). Template: `references/review-fix-map.template.md`. Omit P2 that does not block gate.

**Round 2+ (delta):** only when parent prompt says `delta` **and** names prior map IDs. Check those rows + hunks fixer changed. New Warning outside that set = round-1 miss — **do not** emit, **do not** reject for it. New Critical **inside** those hunks = only new row allowed. Else residual open IDs only.

## Score gate (all modes)

Every review **must** include overall score **1–10**. **`Approved`** = zero Criticals **and** score **= 10** only. Callers close on `Approved` — `references/review-gate-workflow.md`. Score **9** = **`Rejected`** (Lift toward 10).

| Score | Meaning | Verdict impact |
|-------|---------|----------------|
| **10** | Ship as-is | **`Approved`** (only eligible score) |
| **9** | Near-bar leftover (redundancy / non-uniform) | **`Rejected`** — Lift |
| **≤8** | Below bar / score cap | **`Rejected`** |

**`Approved` only when all true:**

1. Zero Critical findings
2. Overall score **= 10**/10

**`Rejected` when:** any Critical, **or** score ≤ **9**. AC / ledger / ui-contract proof is **not** this skill.

### Scoring unit

Score **quality of touched module/file after diff**, not hunk-alone correctness. Minimal patch leaving/worsening SSoT/DRY/OCP in file **cannot** score 9–10.

### Score caps (lowest that fits)

| Condition in touched module | Max score |
|-----------------------------|-----------|
| New/changed behavior with config/lookup **split across 2+ places** (SSoT) | **7** |
| Same resolution block copied in **2+ functions** in diff scope (DRY) | **7** |
| Predictable extension requires editing **3+ points** in same file (weak OCP, e.g. provider) | **7** |
| New/changed **exported / public** symbol (module `return { }`, `module.exports`, `export`, `public`/`public static`, window/global attach) with **no caller outside defining module** (grep: other files + same-file call sites that are not the export list) | **7** |
| Diff correct, zero Critical, mediocre / inconsistent pattern in file | **7–8** |
| gate/role helper or domain constant swapped without cited project-rule clause | **6** |

Internal/private/nested helpers **do not** count. **Do not** cap on function count. Example: 6 exported IP helpers vs 2 caller ops (`validateOriginIpInput`, `originIpMatches`); private `originIpKey` = OK.

**9:** zero Critical **and** smells above absent or resolved in touched module; predictable extension = one SSoT.

**10:** same as 9 **plus** no obvious fallback/redundancy; uniform pattern across file.

### Anti-inflation

- **Forbidden:** “minimal diff / tests pass / AC ok ⇒ 10”
- **Required** in Executive Summary: one sentence justifying score vs rubric (e.g. “cap 7 — apiKey outside preset”)

### Smell severity (SSoT / DRY / weak OCP / orphan public)

Split SSoT, duplicated resolution, **or orphan public/exported surface** in touched module ≥ **Warning**. Prefer **Warning + score cap** over auto-Critical. **Critical** for bugs, security. Score ≤ **9** forces `Rejected`. AC failures belong to `ns-judge`.

## Review priorities

Within each section, order by severity:

1. Critical (must fix before merge)
2. Warning (should fix)
3. Suggestion (consider)

Diff touches `agent-api` (or LangGraph runtime paths): load `../ns-langgraph-agents/references/anti-patterns.md`. Placement, Prompt inject, Bind parity, Spec drift, colon wire names = Critical if violated.

### AI / agent diff criteria

Keep anti-patterns delegation above. Extra criteria when diff touches agent/LLM surfaces:

| Finding | Severity |
| ------- | -------- |
| Irreversible write reachable without a gate | **Critical** |
| Prompt body changed without version bump | **Critical** |
| `UPDATE` / `DELETE` against audit history | **Critical** |
| Equality assertion on model output (exact string) instead of accepted range / contract | **Warning** + score cap **7–8** |
| New LLM call with no token/cost accounting | **Warning** (no extra score cap unless combined with other smells) |

### SOLID and clean code

- SRP, OCP, LSP, ISP, DIP
- Naming, cyclomatic complexity, error handling, dead code

### Performance, security, testability

- N+1, unnecessary renders, missing validation
- SQL injection, XSS, sensitive logs
- Coupling that blocks testing

| Finding | Severity |
| ------- | -------- |
| Secret/credential in versioned file | **Critical** |
| Test weakened/deleted to pass | **Critical** |
| Real LLM/network call reachable from default tier (no live marker, or not excluded from default run/CI) | **Critical** |
| Live-tier test without documented on-demand trigger, or credentials not from env/secret manager | **Warning** |
| Unjustified type escape hatch | **Warning** |
| New dependency or abstraction not approved in task | **Warning** |
| New code duplicates existing repo helper, stdlib/platform feature, or installed dependency | **Warning** + score cap **8** |
| Speculative option/config/wrapper not asked by task | **Warning** + score cap **8** |
| Moved/merged code lost validation or error handling | **Warning** + score cap **8** |
| New non-trivial logic (branch, loop, parser, money, security) without test | **Warning** + score cap **8** |

### Actor and gate semantics (rules-first)

Before proposing change to session gate, middleware, or role check:

- Read project rules for **named actor semantics**. Homonyms not interchangeable.
- Forbidden to swap helper by label similarity. **Critical** when rules define distinct actors.
- Diff introducing actor/gate spec never named in rules: **Warning**.
- Gate/auth fix-map must cite **project-rule clause**.

## Required output format

### Approved

### Executive Summary

- Score **10** (**Score gate** — `Approved` only at **10**)
- One sentence justifying score vs score-cap rubric
- Two-line overall assessment

Then: `Code Review: Approved`

### Rejected / Blocked

### Executive Summary

- Score 1–10
- One sentence justifying score
- Two-line overall assessment

### Fix map (agent)

Follow **Fix map rounds** + `references/review-fix-map.template.md` — actionable correction rows only.
Omit positive findings, suggestions-only noise, history, long prose.

Then: `Code Review: Rejected` or `Code Review: Blocked`

## Constraints

- **Read-only.** No edit/create/delete product files — including `code-review-report.md`
- **Not substitutable.** Workflow callers must invoke this skill by name; platform review subagents not equivalent unless human explicitly requests them this run
- Direct, constructive; no personal criticism
- No rewrite unrelated code
- Findings from actual diff + rules read
- Match project conventions visible in codebase
- Fix map audience = **another agent**, not human

## References

| File | When |
| ---- | ---- |
| `references/review-fix-map.template.md` | Rejected/Blocked response body |
| `../../ns-harness/references/artifact-layout.md` | Artifact paths |
| `mcp-gitlab-usage` | Posting internal review comments |
| `../ns-judge/SKILL.md` | Delivery proof after this skill returns `Approved` |

© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills

Similar skills

All skills for Code review and refactoring →

From the same set20

The whole set →
ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs ns-living-spec ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth. CX Codex +1 140installs ns-proto-visual-guide The ns-proto-visual-guide Claude Code skill documents the required appearance of cards, forms, shells, and overlays. It activates for normative visual guides and visual QA checklists. CX Codex +1 106installs ns-proto-creator ns-proto-creator — a Claude Code skill that captures live interfaces with Playwright and builds or updates a prototype. It runs for URL-based prototyping, screen reconstruction, and changes to an existing prototype/. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open