Immutable. This exact content is served forever at /api/v1/blob/43acbc1d05541cac.
# Development Guidelines for review-code
## File Locations
This repo contains the source files for the `/review-code` skill:
- `skills/review-code/SKILL.md` - Skill definition (routing + small handlers)
- `skills/review-code/handlers/` - Large handlers loaded on demand (find, review, learn)
- `skills/review-code/scripts/` - Bash scripts that implement the skill
- `skills/review-code/context/` - Base context files (languages, frameworks, orgs)
- `skills/review-code/learnings/` - Learning system documentation
- `agents/` - Agent definitions
- `bin/` - Development utilities (fmt, lint, test, setup)
## Agent Definitions
The nine domain reviewers in `agents/` deliberately repeat four shared blocks instead of sourcing them from one file: "Before You Review", "Self-Challenge", the confidence rubric, and the finding format (a fenced ```text body plus the `Location: path:line | Confidence: NN%` trailer). Each subagent receives its own prompt exactly once, so deduplicating would save no runtime tokens; keep the four blocks in sync when editing one. The finding format is parsed by `parse-review-findings.sh` and the synthesis step in `handlers/review.md`; don't change its shape.
## Architecture
**In the repository:**
```
skills/review-code/
SKILL.md # Skill definition (routing + small handlers)
handlers/ # Large handlers loaded on demand
find.md
review.md
learn.md
briefing/ # Static text concatenated into the agent briefing
shared-instructions.md
scripts/ # Helper scripts
context/ # Base context files (shipped to users)
languages/
frameworks/
orgs/
learnings/ # Learning system docs
agents/ # Review agent definitions
```
**Installed at `~/.claude/skills/review-code/`:**
```
~/.claude/skills/review-code/
SKILL.md
handlers/ # Large handlers loaded on demand
find.md
review.md
learn.md
scripts/
context/ # Base + user learnings (merged)
languages/
frameworks/
orgs/
.reviews/ # Review outputs (org/repo/pr.md)
posthog/
posthog/
pr-123.md
.learnings/ # Learning index
index.jsonl
analyzed.json
.sessions/ # Session state, pre-flight markers, and per-review artifacts
review-code/
artifacts-XXXXXX/ # diff.patch, briefing.md, scoped diffs (swept with the session)
.worktrees/ # PR checkout worktrees (org/repo/pr-N)
```
**Key insight:** The repo structure mirrors the installed structure, except that runtime state (reviews, learnings, sessions, worktrees) is installed into dot-prefixed directories so skill scanners that ignore dot-directories don't count it against the skill's file budget (source `learnings/README.md` installs to `.learnings/README.md`). During setup, `skills/review-code/` is copied to `~/.claude/skills/review-code/`. User learnings applied to installed context are preserved through smart merge - new sections from base are added, but existing sections (which may contain learned patterns) are kept.
## Keeping Reviews Cheap
A review's cost is the orchestrating conversation's context multiplied by its turn count, plus everything the orchestrator has to write out. Two rules follow, and breaking either one is expensive in a way that is invisible in a single run:
- **Never put a large payload in an agent prompt.** The diff, the review context, the PR body and comments all live in files under the session's `artifacts_dir`. `build-agent-briefing.sh` writes them once; agent prompts carry a path. Inlining any of them means the orchestrator writes it once per agent, at output-token prices.
- **Never Read the session file wholesale.** Use `review-status-handler.sh get-review-fields`, which returns the small orchestration fields and deliberately excludes `diff`, `review_context`, `pr.body`, and `pr.comments`. Anything added to that accessor is paid for on every later turn of the run.
`handlers/review.md` is read on every review, so its length is also multiplied by the turn count. Stage-specific instructions belong in an on-demand handler (see `review-compose.md`, `review-pr-output.md`, `review-inline-fallback.md`), and mechanical steps belong in a script rather than in prose the model has to carry (see `log-token-usage.sh`).
Measure with `bin/token-report` before and after. The skill's own `.reviews/token-usage.jsonl` sees subagents only, and the orchestrator is roughly half the bill.
## Important: Edit Source Files Only
**Never edit files in `~/.claude/` directly.** Always edit the source files in this repo.
The files in `~/.claude/skills/review-code/` are installed copies. To update them after making changes:
```bash
bin/setup
```
This copies the source files to the appropriate locations and uses smart merge for context files to preserve user learnings.
## Testing Changes
After editing source files:
1. Run `bin/setup` to install changes to `~/.claude/`
2. Test the skill with `/review-code` in a Claude Code session
3. Run `bin/test` to run the test suite
## Formatting
Before committing, run:
```bash
bin/fmt
```
This formats shell scripts with shfmt.