Code Review Workflow

Run a comprehensive, multi-perspective code review on the current branch changes. This skill activates the Review Council and integrates automated security scanning to catch issues before they reach a pull request.

[!CAUTION] Scope boundary: This skill reviews code and commits fixes. It does NOT create pull requests, push to remote, or merge anything. When the review is complete, stop and suggest the user run
/submit-pr
next. Do not proceed to PR creation — that is
/submit-pr
's job.

[!WARNING] Checkpoint protocol. When this workflow reaches a
### CHECKPOINT
, you must actively prompt the user for a decision — do not simply present information and continue. Use your agent's interactive prompting mechanism (e.g.,
AskUserQuestion
in Claude Code) to require an explicit response before proceeding. This prevents queued or in-flight messages from being misinterpreted as approval. If your agent lacks interactive prompting, output the checkpoint content and stop all work until the user explicitly responds.

Step 1: Analyze Current Changes

Identify all changes on the current branch:

Run
```
git diff origin/main...HEAD
```
to see all changes relative to main
Run
```
git diff
```
and
```
git diff --cached
```
to catch any uncommitted work
Run
```
git status
```
to see modified, added, and deleted files

Categorize changed files by layer based on your project's directory structure:

Frontend: UI components, pages, styles, client-side logic
Backend: API routes, services, business logic, server-side code
Database: Schema files, migrations, seed data
Configuration: Config files, CI/CD, container definitions, environment files
Documentation: Markdown files, docs directories
Tests: Test files (
```
.test.*
```
,
```
.spec.*
```
)

Present a summary of changed files by category to the user.

Step 2: Run Formatting and Lint Checks

Run your project's formatting and lint commands before the council review to catch mechanical issues early. Common examples:

# Adapt to your project's toolchain
format:check    # Prettier, Black, gofmt, etc.
lint            # ESLint, Ruff, golangci-lint, etc.

If formatting checks fail, fix them immediately by running the auto-formatter on the reported files and stage the changes. Do not include formatting issues in the council review — just fix them.

Step 3: Run Automated Security Scanning

Perform static application security testing (SAST) on all changed files. Scan for:

<details> <summary>SAST Scanning Checklist</summary>

Are all database queries parameterized? (SQL/NoSQL injection)
Are user inputs sanitized before rendering? (XSS — reflected, stored, DOM-based)
Are state-changing endpoints protected against CSRF?
Are there hardcoded secrets, API keys, passwords, or connection strings?
Are authentication flows following secure patterns? (no auth bypass paths)
Are error messages leaking internal details? (stack traces, DB structure)
Are dependencies free of known CVEs?
Are file uploads validated and restricted?
Are authorization checks present on all protected endpoints?

</details>

If backend files are changed, also perform a hardening review:

Is input validation comprehensive on all user-facing inputs?
Are authentication and authorization checks present and correct?
Are error responses safe? (no internal details leaked)
Are secrets managed securely? (environment variables, vaults — not hardcoded)
Are security headers configured? (CSP, HSTS, X-Frame-Options)
Are rate limits configured on public endpoints?

Collect all findings with severity levels (Critical, High, Medium, Low, Info).

Claude Code optimization: If the
/security-scanning:security-sast
and
/security-scanning:security-hardening
skills are available, use them for enhanced automated scanning. Otherwise, follow the manual checklists above.

Step 4: Run Accessibility Audit (if frontend changes)

If any frontend files (UI components, CSS, HTML templates) are in the changeset, check WCAG compliance on modified components:

<details> <summary>Accessibility Checklist</summary>

Do text and interactive elements meet color contrast ratios? (4.5:1 for normal text, 3:1 for large text)
Can all interactive elements be reached and operated via keyboard alone?
Are ARIA attributes used correctly? (roles, labels, live regions)
Is focus managed properly during dynamic content changes? (modals, route transitions)

Is semantic HTML used? (

<button>

not

<div onClick>

<nav>

<main>

<article>

)

Are images and icons given accessible names? (
```
alt
```
text,
```
aria-label
```
)
Are form inputs associated with labels?
Does the page make sense when read linearly by a screen reader?

</details>

Claude Code optimization: If the
/ui-design:accessibility-audit
skill is available, use it for enhanced automated WCAG compliance checking. Otherwise, follow the manual checklist above.

Step 5: Activate the Review Council

Read the Review Council template from the skill's

councils/review-council.md

and conduct the full council review. For each council member, read their agent definition from the skill's

agents/

directory and use the complexity tier specified to calibrate review depth.

Security Engineer (Lead)

Review all SAST findings from Step 3
Check for OWASP Top 10 vulnerabilities in the changed code
Validate input sanitization on any new endpoints or forms
Check secrets management (no hardcoded credentials, API keys, tokens)
Verify authentication and authorization logic
Vote: Approve / Concern / Block
Findings: List each issue with severity and file location
Recommendations: Specific fixes for each finding

QA Lead

Assess test coverage for changed files
Check if new functionality has corresponding tests
Identify untested edge cases and boundary conditions
Verify error scenarios are tested
Check if test coverage meets the >80% target
Vote: Approve / Concern / Block
Findings: Missing tests, coverage gaps, untested scenarios
Recommendations: Specific tests to add

DevX Engineer

Check if documentation is updated for user-facing changes
Review code readability and clarity of complex logic
Verify README/docs reflect any new features or changes
Check that public APIs have proper documentation comments
Vote: Approve / Concern / Block
Findings: Documentation gaps, unclear code sections
Recommendations: Documentation and clarity improvements

Domain Specialist

Select the appropriate specialist based on changed files:

Frontend Specialist if frontend files changed
Backend Specialist if backend files changed
Both if changes span frontend and backend

Review domain-specific best practices:

Component patterns, state management, rendering performance (frontend)
Framework patterns, service architecture, API design (backend)
Schema design, query optimization, migration safety (database)
Vote: Approve / Concern / Block
Findings: Pattern violations, anti-patterns, performance concerns
Recommendations: Specific improvements

Step 6: Present Consolidated Review Report

Present the full review report organized by severity:

Critical / Blocking Issues

Issues that must be fixed before merge (any Block vote or Critical SAST finding).

High Priority Issues

Issues strongly recommended to fix (High SAST findings, Concern votes with security implications).

Medium Priority Issues

Issues worth fixing but not blocking (Medium SAST findings, code quality concerns).

Low Priority / Suggestions

Nice-to-have improvements (Low findings, style suggestions, minor documentation gaps).

Review Decision Summary

Overall Status: Approved / Needs Changes / Blocked
Council Votes: Summary of each member's vote
Action Items: Prioritized list of what to fix

CHECKPOINT: Present all findings to the user. Ask which items they want to address now. Wait for instructions before proceeding.

Step 7: Apply Fixes

For each item the user approves for fixing:

Apply the fix
Re-run the relevant check (lint, test, type-check, or security scan) to verify the fix
Stage the changes

If the user asks to skip certain findings, note them as deferred items for Step 9.

CHECKPOINT: Present the applied fixes to the user. Confirm all changes look correct before committing.

Step 8: Commit

If the user approves:

Stage all changes

Commit with an appropriate conventional commit message (e.g.,

fix(security): address SAST findings

refactor: address code review feedback

)

Step 9: Track Deferred Work

If any review findings were deferred (not fixed in this cycle), document them so they don't get lost.

Check for Deferred Items

Review the following sources for deferred work:

Skipped findings: Items the user chose not to address from the review report
Low priority suggestions: Items categorized as Low/Info that weren't fixed
Council recommendations: Improvements suggested by council members that are out of scope for this PR

Document Deferred Work

For each deferred item, create a tracking issue in your project's issue tracker with the finding description, context on why it was deferred, and what needs to happen.

[!TIP] Not every review generates deferred work. If all findings were addressed or accepted, skip this step entirely. Don't manufacture follow-up issues just to have them.

Step 10: Hand Off — STOP Here

[!CAUTION] This skill's work is done. Do NOT proceed to create a pull request, push to remote, or merge anything. Those are separate skills with their own workflows and checkpoints.

Suggest the next step — then stop:

If ready for PR: "Run
```
/submit-pr
```
to create a pull request"
If more work needed: "Continue implementation, then run
```
/review-code
```
again when ready"

Do not push the branch, create a PR, or invoke
/submit-pr
from within this skill.

review-code

NPX Install

Tags

SKILL.md Content