alexei-led/reviewing-code

Code Review

Review changed code for security, correctness, test coverage, maintainability, and documentation. Ground every finding in concrete evidence: a file:line reference or tool output.

If a task-tracking facility is available, track these phases as tasks.

Role and output contract

This skill produces findings, not edits. It owns the tiered-findings output contract below. Emit the findings regardless of role; route the actual fixes to fixing-code or the refactor to refactoring-code. A reviewer (read-only) cannot run git diff or builds — work from the files in scope plus any diff context the caller supplies, and ask for that context if it is missing rather than guessing.

Workflow

1. Determine review scope.
2. Detect languages and load the matching references.
3. Walk the review dimensions across the scope.
4. Aggregate findings by severity and report.

Track progress through the workflow phases using TaskCreate / TaskUpdate.

If $ARGUMENTS is passed, the keywords below tune the workflow:

• deep — cover all six review dimensions, not just the security and correctness pair.
• team — fan the dimensions to parallel reviewer sub-tasks that challenge each other's findings and converge.
• external — additionally spawn external AI reviewers. Only when explicitly requested; never run by default.

Without external, run only this skill's own review. Never spawn external reviewers implicitly.

Determine scope

Resolve the scope from the request. Options:

• Uncommitted changes
• Branch compared to the default branch
• Specific files (user provides paths)

If a role with Bash is running this, resolve to the appropriate git invocation and use it consistently across phases. If a read-only role is running this, work from the file list and diff context the caller provides. If the user already named a scope, use it without asking; otherwise ask one clarifying question.

Use AskUserQuestion with header "Review scope" and the three options spelled out above.

Detect languages and load references

Scan the changed-file extensions. For each language present, load the matching reference for language-specific review checks:

• Go → references/go.md
• Python → references/python.md
• TypeScript → references/typescript.md
• Web / HTML / CSS / JS → references/web.md

Mixed languages: load each matching reference. Unknown or unsupported language: use the generic dimensions below only and note the reduced coverage.

Review dimensions

Walk every dimension across the scope. For a standard review, cover the security and correctness dimensions; for a thorough review, cover all six. If the runtime supports parallel sub-tasks and the scope is large, the orchestrator may fan the dimensions out, but the rubric is identical either way.

• Logic, security, OWASP, race conditions, unchecked errors, resource leaks
• Patterns, conventions, stdlib usage, error handling
• Test coverage, edge cases, mocking discipline
• Requirements match, dependency injection, boundary inputs
• Comments, docstrings, API docs, ARIA labels for web
• Maintainability, dead code, confusing indirection, pass-through wrappers

Run the dimensions as the read-only reviewer role. For large scope, the orchestrator may fan them out as parallel Task(subagent_type="reviewer", prompt=...) sub-tasks, one per dimension or per file group; each sub-task's model is set in its own metadata — do not pin a model from the skill.

When team is set, run those sub-tasks as an agent team so they challenge each other's findings; the report prefixes each finding with [Flagged by: <dimension>].

When external is set, additionally spawn any configured external-AI reviewer bridges in parallel for a second-model pass on security and quality. Do not hard-depend on a specific external agent; skip silently if none is configured.

Review rules

• Cite concrete file:line evidence or tool output for every finding. No evidence, no finding.
• Findings include severity and a concrete fix.
• For security findings, remind the user: keep private code local; do not paste private diffs into web tools. Use web only for external facts (CVE, library docs); cite separately.
• Ask one clarifying question at a time; do not batch.
• Keep the review scoped to changed code or the user-provided file list. Do not expand into repo-wide architecture analysis.

Historical context (optional)

If cross-session memory tooling is available, query for prior observations on the files about to be reviewed. Skip already-litigated issues so old findings are not repeated. Skip silently if no such tooling is configured.

If mcp__plugin_claude-mem_mcp-search__search is available, query for past findings on the files in scope:

search({ query: "<file paths in review scope>", limit: 10 })

Fetch full observations via get_observations for relevant hits. Skip already-litigated issues. Skip silently if the MCP is not installed.

Report format

## Code Review Summary

**Scope**: <description>
**Languages**: <list>

### Critical (must fix)

- `file:line` — issue. Fix.

### Warnings (should fix)

- `file:line` — issue. Fix.

### Suggestions (consider)

- `file:line` — improvement.

### Summary

Overall assessment in 2-3 sentences, then a prioritized list of recommended actions.

Writing style

• One sentence per finding. No preamble, no "I noticed that…".
• Cut hedging: "potential", "might", "consider". State what is wrong.
• Direct: "This leaks memory" not "This could potentially lead to memory issues".
• Technical precision: include type names, function signatures, line numbers.

Edge cases

• No changes in scope → "Nothing to review."
• Linters missing or unrunnable (read-only role) → say so explicitly; still review by reading.
• Tests missing → flag as a finding under the test-coverage dimension.
• Scope larger than expected → review only what was asked; list adjacent suspicious files as out of scope.