Code Review & Analysis
Relevant source files
The following files were used as context for generating this wiki page:
The Code Review & Analysis system in Roughly is a multi-layered, gated process designed to ensure technical accuracy, adherence to project conventions, and implementation quality throughout the software development lifecycle. It transitions from pre-implementation specification reviews to parallel post-implementation code analysis, utilizing specialized subagents and automated verification loops.
The system is "loud" and "gated," meaning it requires explicit human confirmation between stages and produces visible output for every analysis performed. It specifically targets the prevention of context overflow—a common failure mode in AI-driven development—by isolating review tasks into discrete, context-aware operations.
Sources: README.md:120-134, README.md:295-300
Review Architecture & Subagent Model
Roughly employs a subagent-per-task model for code analysis. Instead of a single monolithic process, the orchestrator dispatches specialized agents for different types of review.
Specialized Review Agents
| Agent | Model | Primary Focus |
|---|---|---|
| Epic Reviewer | Opus | Pre-implementation hollistic review of stories and ACs. |
| Code Reviewer | Sonnet | Logic errors, security, and project conventions. |
| Static Analysis | Sonnet | Type checking, linting, and build verification. |
| Silent Failure Hunter | Sonnet | Error handling patterns and edge cases. |
| Plan Reviewer | Sonnet | Verifying implementation plans against the current codebase. |
Sources: README.md:255-265, CLAUDE.md:88-100, agents/code-reviewer.md:1-10
Parallel Post-Implementation Review
The standard code review process (triggered via /roughly:review) dispatches three agents in parallel to provide a synthesized report.
This diagram illustrates the parallel execution of specialized agents during a standard code review to ensure comprehensive coverage without context bloat.
Sources: skills/review/SKILL.md:21-50
Pre-Implementation Analysis
Analysis begins before any code is written, focusing on the quality of requirements and the feasibility of implementation plans.
Epic Review
The epic-reviewer agent, powered by the Opus model, performs a cross-story reasoning check on epic files. It evaluates dimensions such as technical accuracy, risk assessment (integration, scalability), and "AC Mutual Satisfiability."
AC Mutual Satisfiability Check:
The system verifies that pairs of Acceptance Criteria (AC) targeting overlapping surfaces (the same file path, step number, or prose region) do not create structural impossibilities. For example, if AC1 requires a modification when a gate is closed, but AC2 forbids modifications outside that same gate, the Epic Reviewer flags this as a blocker.
Sources: agents/epic-reviewer.md:13-33, skills/review-epic/SKILL.md:25-35
Implementation Plan Review
Automated as a blocking subagent in build and fix pipelines, the Plan Reviewer (review-plan) verifies that a specific implementation plan's claims and assumptions are sound relative to the actual codebase.
The Plan Reviewer iterates up to 3 times automatically to resolve uncertainties by reading the actual codebase.
Sources: skills/review-plan/SKILL.md:17-30, skills/review-plan/SKILL.md:104-113
Post-Implementation Quality Gates
Once implementation tasks are executed, they must pass through a two-stage quality gate before being marked complete.
- Spec Compliance: The orchestrator verifies if the subagent modified only the files listed in the task and if the output matches the task description.
- Quality Check: An automated loop runs project-specific type checks and linting. The system allows up to 4 auto-fix attempts for linting/type errors, but only 2 attempts for test failures before escalating to a human.
Sources: skills/fix/SKILL.md:162-185, CLAUDE.md:101-110
Epic Auditing
Post-implementation, the system can perform a retrospective audit of an entire epic. This involves mapping completed stories to specific git commits and files to verify that all original ACs were met.
The audit process uses git metadata to ground its analysis in actual historical changes.
Sources: skills/audit-epic/SKILL.md:41-95
Known Pitfalls & Convention Tracking
A critical component of Roughly's analysis is the .roughly/known-pitfalls.md file. This serves as a dynamic knowledge base that is:
- Read by every agent before starting a task for context.
- Updated at the end of build/fix pipelines via the
doc-writeragent when new anti-patterns are discovered. - Used by the
silent-failure-hunterto look for domain-specific risk patterns.
Sources: agents/agent-preamble.md:16-20, skills/review/SKILL.md:41-45, agents/doc-writer.md:15-20
Summary of Review Findings Severity
Reports generated by the system (specifically from /roughly:review and code-reviewer) are categorized by severity to help developers prioritize fixes.
| Severity | Description | Requirement |
|---|---|---|
| Critical | Bugs, logic errors, or security vulnerabilities (e.g., OWASP top 10). | Must be fixed before proceeding. |
| Warning | Anti-patterns or violations of documented project conventions in CLAUDE.md. | Should be addressed; human may override. |
| Info | Minor improvements or optional stylistic suggestions. | Optional consideration. |
| Passed/Clean | Areas that look correct and follow all patterns. | Informational signal. |
Sources: agents/code-reviewer.md:26-39, skills/review/SKILL.md:52-65