Immutable. This exact content is served forever at /api/v1/blob/1abae9dadb28f95e.
# 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
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
```
**Key insight:** The repo structure mirrors the installed structure. 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.
## 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.