Code Review Pipeline¶

The review pipeline is a multi-dimensional code review system built into the sq-dev plugin. It runs static analysis, bug hunting, documentation compliance, and simplification analysis — then synthesizes everything into a single pass/fail verdict.

You get structured feedback that's actionable, not just noise.

Quick Start¶

/sq-dev:full-review

That's it. Interactive mode asks what depth you want, runs the applicable dimensions, and shows a consolidated report.

For coding agents (or when you don't want prompts):

/sq-dev:full-review mode:autonomous

This runs the full pipeline, auto-fixes what it can, and returns a verdict.

The Three Dimensions¶

Every review runs one or more dimensions depending on the depth you choose:

Dimension	What it checks	Skill
Style/Lint	Formatting, types, lint rules — the stuff your linter catches	`/sq-dev:code-check`
Code/Security	Bugs, security vulnerabilities, logic errors, docs compliance	`/sq-dev:code-review`
Simplification	Dead code, unnecessary complexity, refactoring opportunities	`/sq-dev:simplify-review`

Depth controls which dimensions run:

Depth	Dimensions	When to use
Quick	Code/Security only	Fast sanity check before pushing
Standard	Style/Lint + Code/Security	Default — covers the things that break production
Thorough	All three	Pre-merge, audits, or when you want the full picture

Parameters¶

The full-review skill accepts key:value parameters — all optional with sensible defaults:

/sq-dev:full-review [key:value...]

Parameter	Values	Default
`mode`	`autonomous`, `interactive`	`interactive`
`depth`	`quick`, `standard`, `thorough`	`standard`
`target`	`staged`, `working`, `branch`, `all`, `custom`	`working`
`fix`	`smart`, `all`, `major`, `off`	`smart` (autonomous)

Examples¶

# Interactive, standard depth, working tree changes (all defaults)
/sq-dev:full-review

# Pre-commit: only staged files, quick check
/sq-dev:full-review depth:quick target:staged

# PR review: everything on this branch vs main
/sq-dev:full-review target:branch

# Full audit of the repo
/sq-dev:full-review depth:thorough target:all

# Agent-friendly: autonomous with no fixes, just a report
/sq-dev:full-review mode:autonomous fix:off

Legacy syntax still works

If you're used to the old positional keywords, they still work:

/sq-dev:full-review autonomous quick report-only

The skill auto-detects which syntax you're using (presence of : triggers key:value parsing).

Target Modes¶

Target controls which files get reviewed:

Target	What it reviews	Use case
`working`	`git diff` + `git diff --staged`	Default — all your uncommitted work
`staged`	`git diff --staged` only	Pre-commit gate — just what you're about to commit
`branch`	`git diff $(merge-base)...HEAD`	PR review — everything on this branch
`all`	`git ls-files`	Full repo audit
`custom`	User-provided file list	Targeted review of specific files or components

Branch base detection tries origin/dev first, then origin/main, then falls back to HEAD~1. A warning is emitted to stderr if no remote base is found.

Interactive Mode¶

When you run /sq-dev:full-review without mode:autonomous, you get an interactive flow:

Choose depth — Quick, Standard, or Thorough (skipped if you specified depth:)
Dimensions run — each produces findings with severities
Consolidated report — executive summary with verdict
Post-review options:
- Commit — changes look good, proceed to /sq-dev:make-commit
- Fix all — fix every actionable finding
- Fix major — fix CRITICAL + HIGH only
- Smart fix — major + quick wins (MEDIUM/LOW fixable in 5 lines or less)
- Review details — drill into specific findings
- Stop — address findings manually

The fix flow applies fixes, re-runs affected dimensions to verify, and presents the updated report. One fix+verify cycle max — if issues persist, you decide what to do next.

Autonomous Mode¶

Autonomous mode is designed for coding agents and CI pipelines. No prompts, no interaction — just analysis, fixes, and a verdict.

/sq-dev:full-review mode:autonomous

Self-Healing Loop¶

When the verdict is not PASS, autonomous mode enters a fix loop (up to 3 cycles):

Filter findings by fix tier (smart by default)
Apply deterministic fixes first — run module fix commands (formatters, linters)
Apply LLM-driven fixes — code edits for bugs, security issues
Re-run affected dimensions to verify
Repeat if findings remain (up to 3 cycles)

Fix Tiers¶

Tier	What gets fixed
`smart` (default)	CRITICAL + HIGH always; MEDIUM + LOW only if the fix is 5 lines or less
`all`	Everything actionable (CRITICAL through LOW)
`major`	CRITICAL + HIGH only
`off`	No fixes — report + verdict only

The Verdict¶

The last line of output is always one of:

VERDICT: PASS     # Ship it
VERDICT: REVIEW   # Needs human attention
VERDICT: BLOCK    # Do not merge

Rules:

BLOCK — any CRITICAL finding, or any dimension returned BLOCK
REVIEW — any HIGH finding, any dimension returned REVIEW, or a dimension errored
PASS — all dimensions clean

The Executive Summary¶

Both modes produce the same consolidated report format:

=== Review: Executive Summary ===
Scope: 14 files analyzed
Modules: backend (py), frontend (ts)
Depth: Standard
Target: branch

| Dimension       | Status | Critical | High | Medium | Low | Info |
|-----------------|--------|----------|------|--------|-----|------|
| Style/Lint      | PASS   | 0        | 0    | 2      | 1   | 0    |
| Code/Security   | REVIEW | 0        | 1    | 3      | 2   | 1    |
| Docs            | PASS   | 0        | 0    | 0      | 0   | 0    |

Overall: REVIEW

Code-review findings with Docs/ categories (e.g., Docs/Compliance, Docs/Staleness) are split into their own row.

Running Dimensions Individually¶

Each dimension is a standalone skill you can invoke directly:

Code CheckCode ReviewSimplify Review

/sq-dev:code-check

Runs static analysis using the project's own tools. If your project has scripts.validate in package.json or a validate: target in Makefile, it uses that. No linter configured? Falls back to style-auditor agents for best-effort analysis.

Auto-runs your fix command (if detected) before validation to eliminate noise.

/sq-dev:code-review

Deploys bug-hunter agents to analyze changed files for bugs, security issues, and logic errors. Also checks documentation compliance against Sartiq internal docs.

Agent count scales with file count — more files means more concurrent agents for faster analysis.

/sq-dev:simplify-review

Pure assessor — analyzes complexity and reports refactoring opportunities without making changes. Findings are LOW (mechanical improvements) and INFO (architectural suggestions). Never produces BLOCK.

Under the Hood: Review Scripts¶

The pipeline is backed by shell scripts in scripts/review/ that handle file discovery, module detection, and verdict computation. These are the building blocks that skills orchestrate.

classify-changes.sh¶

Classifies changed files by language (TypeScript, Python, other) for routing to appropriate reviewers.

bash scripts/review/classify-changes.sh [--target <mode>] [--by-module <json>]

Output: single-line JSON

{"ts": ["src/api.ts"], "py": ["app/main.py"], "other": ["README.md"], "total": 3}

With --by-module, adds a by_module object bucketing files per module.

Classification rules:

TypeScript/JavaScript — .ts, .tsx, .js, .jsx, .mts, .cts (excludes .d.ts, test files, __tests__/)
Python — .py (excludes test_*.py, *_test.py, conftest.py, tests/, test/, migrations/)
Other — everything else (markdown, shell scripts, config files, etc.)

detect-modules.sh¶

Discovers project structure — single root module or multi-module monorepo.

bash scripts/review/detect-modules.sh

Output:

{
  "modules": [{
    "name": "backend",
    "path": "backend",
    "lang": "py",
    "validate": {"command": "make validate", "source": "Makefile"},
    "fix": {"command": "make fix", "source": "Makefile"}
  }]
}

Scans depth-1 subdirectories for project markers (package.json, pyproject.toml, Makefile). Each subdirectory with its own validate command becomes a module. If no subdirectory modules are found, returns a single root module.

detect-validate.sh / detect-fix.sh¶

Detect the project's validation and auto-fix commands respectively. Check package.json scripts first (priority: validate / fix > lint:fix > format:fix > format), fall back to Makefile targets.

compute-verdict.sh¶

Maps severity counts to a verdict:

bash scripts/review/compute-verdict.sh --critical 0 --high 2
# Output: REVIEW

Condition	Verdict
`critical > 0`	BLOCK
`high > 0`	REVIEW
Otherwise	PASS

Multi-Module Support¶

In monorepo projects, the pipeline automatically detects subdirectory modules and routes validation to each one independently. A project like:

myproject/
  backend/        # pyproject.toml + Makefile
  frontend/       # package.json with scripts.validate
  docs/           # no validate command → not a module

Gets two modules: backend (py) and frontend (ts). Each module's validate and fix commands run in their own directory. Changed files are bucketed by module using longest-path-prefix matching.

Testing¶

The review scripts have comprehensive BATS tests:

make test

Tests cover all target modes, module detection, file classification, verdict computation, flag combinations, backward compatibility, and edge cases (special characters in filenames, empty repos, etc.).

Test files are in tests/scripts/ and tests/structure/. Shared helpers in tests/helpers/setup.bash provide isolated git repo creation for each test.