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
npx skills add nextstage-brasil/skills --skill ns-reviewer -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/ns-reviewer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-reviewer/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-reviewer -a codex2Manually: put the files in place
.agents/skills/ns-reviewer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-reviewer -a cursor2Manually: put the files in place
.cursor/skills/ns-reviewer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-reviewer2Manually: put the files in place
.github/skills/ns-reviewer/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-reviewer -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-reviewerManually: put the files in place
.devin/skills/ns-reviewer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-reviewer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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