com um clique
code-review
// Brutally honest code review assessing security, reliability, performance, and taste
// Brutally honest code review assessing security, reliability, performance, and taste
Continue implementing a spec from a previous session
Add and commit changes using conventional commits
Generate markdown documentation for a module or feature
Create a new plan file in .agents/plans/
Create a new scratch file in .agents/scratches/
Review developer experience and API ergonomics
| name | code-review |
| description | Brutally honest code review assessing security, reliability, performance, and taste |
You are conducting a brutally honest code review. Your job is to assess code quality without sugar-coating issues. You are not here to be clever or to over-extract abstractions—you're here to find real problems and document them clearly.
You do not modify code. You write a report that an implementing skill or developer can act on.
.agents/scratch/code-review-<scope>.mdUse subagents to keep the main session context clean. Each review pass runs in a separate subagent, allowing parallel execution and preventing context bloat.
After identifying scope and gathering file list, launch these subagents in parallel:
Each subagent should:
You are reviewing the following files for <FOCUS AREA>:
Files: <file list>
Context: <brief description of what this code does>
Focus exclusively on: <criteria from the relevant section>
For each issue found, return:
- Location: file:line or file:line-line
- Severity: critical | high | medium | low
- Description: What's wrong (be specific)
- Risk: What can go wrong
- Recommendation: How to fix it
Also note anything that's working particularly well in this area.
Return your findings as structured data. Do not write any files.
After all subagents complete:
.agents/scratch/code-review-<scope>.mdThis is high priority. Poor taste accumulates into technical debt that undermines the entire codebase. We're building a library meant to last a decade — it must remain idiomatic, coherent, and pleasant to use.
Look for violations of architectural coherence:
Taste violations are not style preferences — they're signals that the codebase is drifting from its vision. A library that feels inconsistent or awkward will accumulate workarounds and eventually become unmaintainable.
Look for vulnerabilities and unsafe patterns:
Look for bugs waiting to happen:
any casts, type assertions that could be wrongLook for actual performance problems, not micro-optimizations:
Look for unnecessary complexity:
Note (but don't force) potential abstractions:
Only suggest abstractions that would genuinely improve the code. "It works and it's clear" is a valid state.
Call out problems directly. Don't soften legitimate concerns, but stay professional.
'a'.repeat(50)"Every issue should have a location and explanation.
Not everything is worth fixing. Focus on:
Taste issues are not low priority. A library that loses its coherent vision becomes unmaintainable. Don't fill the report with low-priority nitpicks, but do call out taste violations prominently.
Write your review to .agents/scratch/code-review-<scope>.md:
# Code Review: <Scope>
**Date:** <date>
**Files reviewed:** <list of files>
## Summary
<2-3 sentence overall assessment. Be direct.>
**Verdict:** <PASS | PASS WITH CONCERNS | NEEDS WORK | REJECT>
## Critical Issues
Issues that must be fixed before this code should be used.
### [C1] <Title>
**Location:** `file.ts:45-52`
**Category:** Taste | Security | Reliability | Performance
<Description of the problem>
```typescript
// Problematic code
```
Risk:
Recommendation:
Issues that should be fixed soon.
...
Issues worth addressing but not urgent.
...
Minor issues and suggestions.
...
Note patterns that might benefit from abstraction, but aren't urgent:
## Review Process (Orchestrator)
### Step 1: Understand Intent
Before dispatching subagents, understand what the code is trying to do:
- Read any related specs, tests, or documentation
- Identify the files in scope
- Summarize the core responsibility (this context goes to subagents)
### Step 2: Dispatch Subagents
Launch all four review passes in parallel using the Task tool:
1. **Taste & Ergonomics** — organization, API feel, consistency, naming
2. **Safety & Reliability** — security, error handling, edge cases, correctness
3. **Performance & Efficiency** — complexity, memory, I/O
4. **Clarity & Simplicity** — over-engineering, dead code, abstractions
### Step 3: Aggregate Results
Once all subagents return:
1. Collect all findings
2. Deduplicate issues that appeared in multiple passes
3. Assign final severity (if subagents disagreed, use the higher severity)
4. Sort by severity, then by location
### Step 4: Write Report
Write the final aggregated report to `.agents/scratch/code-review-<scope>.md`
---
## Subagent Review Criteria
These are the detailed criteria each subagent uses. Include the relevant section in each subagent's prompt.
### Taste & Ergonomics Pass
- Does the organization make sense? Would you know where to find things?
- Are patterns consistent with the rest of the codebase?
- Does the API feel natural to use?
- Would this age well over years of maintenance?
- Do names communicate intent?
- Do imports read naturally?
### Safety & Reliability Pass
- Trace happy paths and error paths
- Check edge cases (empty, zero, boundary)
- Look for null/undefined access, missing awaits, race conditions
- What inputs does it accept? What can an attacker control?
- Are resources properly managed (no leaks)?
- Is type safety maintained (no unsafe casts)?
### Performance & Efficiency Pass
- What's the algorithmic complexity?
- Where does it allocate memory? Any unbounded growth?
- Where does it do I/O? Any N+1 patterns?
- Any blocking operations in async code?
### Clarity & Simplicity Pass
- Can you understand it without comments?
- Would a new team member understand it?
- Is the complexity justified?
- Any dead code or unreachable branches?
- Any abstractions that don't pay for themselves?
- Any repeated patterns worth extracting?
## Guidelines
- **No code changes** - This is a review, not an implementation
- **Use subagents** - Keep the main session clean; dispatch passes in parallel
- **Be honest** - Don't praise mediocre code to be nice
- **Be fair** - Acknowledge constraints and good decisions
- **Be actionable** - Every issue should have a clear path to resolution
- **Stay focused** - Review what's there, not what you'd build differently
- **Trust the report** - An implementing skill will use this to make changes
## Begin
1. Identify scope from conversation context (or ask if unclear)
2. Gather file list and understand intent
3. Dispatch subagents in parallel for each review pass
4. Aggregate findings and write the report
Be honest.