1 added, 1 removed. Audit A to A.
---
name: build-review-md
description: |
- Use this skill when the user wants to create or set up a REVIEW.md configuration file for their repository. Trigger for ANY of these: (1) user says "create REVIEW.md", "set up REVIEW.md", or "configure review rules", (2) code-gauntlet Phase 2c detects no REVIEW.md and suggests creating one, (3) user wants to customize what the code-gauntlet skill focuses on or ignores, (4) user asks "how do I configure the reviewer" or "how do I set review rules". Do NOT trigger for: reviewing code (use code-gauntlet), explaining what REVIEW.md does in the abstract, or editing an already-complete REVIEW.md the user is satisfied with. This skill NEVER loads into the main code-gauntlet context — it is a standalone configuration wizard.
+ Use this skill when the user wants to create or set up a REVIEW.md configuration file for their repository. Trigger for ANY of these: (1) user says "create REVIEW.md", "set up REVIEW.md", or "configure review rules", (2) code-gauntlet Phase 2d detects no REVIEW.md and suggests creating one, (3) user wants to customize what the code-gauntlet skill focuses on or ignores, (4) user asks "how do I configure the reviewer" or "how do I set review rules". Do NOT trigger for: reviewing code (use code-gauntlet), explaining what REVIEW.md does in the abstract, or editing an already-complete REVIEW.md the user is satisfied with. This skill NEVER loads into the main code-gauntlet context — it is a standalone configuration wizard.
---
# REVIEW.md Builder
Guided wizard that creates a REVIEW.md configuration tailored to the repo's actual languages, frameworks, and priorities. Produces a root REVIEW.md and subdirectory configs only when the multi-stack test justifies them.
**This skill produces configuration files, not code review.** Do not run review agents or analyze code for bugs. Stay in configuration mode until exit.
---
## Step 1: Detect
Scan the repository to understand what you are configuring. Do this silently — do not ask the user to describe their stack.
**Languages** — scan file extensions:
- `.ts`, `.tsx` → TypeScript/React
- `.js`, `.jsx` → JavaScript
- `.py` → Python
- `.go` → Go
- `.rs` → Rust
- `.cs` → C#/.NET
- `.java` → Java
- `.rb` → Ruby
- `.php` → PHP
**Frameworks and runtimes** — check for manifest files:
- `package.json` → Node/JS/TS ecosystem; read `dependencies` and `devDependencies` for React, Next.js, Vue, Express, NestJS, RTK Query, Zod, Vitest, Jest
- `requirements.txt` / `pyproject.toml` / `setup.py` → Python; check for Django, FastAPI, SQLAlchemy, pytest
- `Cargo.toml` → Rust; check for tokio, axum, sqlx
- `go.mod` → Go; check for gin, echo, gorm
- `pom.xml` / `build.gradle` → Java/Kotlin; check for Spring Boot, Hibernate
- `*.csproj` / `*.sln` → .NET; check for ASP.NET Core, EF Core, xUnit, NUnit
- `Gemfile` → Ruby on Rails
**Multi-stack / mono-repo detection** — a repo is multi-stack when it contains multiple package manifest files in different subdirectories (e.g., `frontend/package.json` AND `backend/*.csproj`). Record the subdirectory paths.
**Existing REVIEW.md** — check whether a root REVIEW.md already exists. If it does, announce what you found and ask:
```
AskUserQuestion({
"question": "A REVIEW.md already exists at the repo root. What would you like to do?",
"options": [
"Start fresh — replace it with a new one",
"Extend it — add rules to what's already there",
"Cancel — keep what I have"
]
})
```
If "Cancel", exit immediately with the message: "Your existing REVIEW.md is unchanged."
---
## Step 2: Ask priorities
Announce your detection findings in one sentence (e.g., "I found a TypeScript/React frontend and a .NET backend in separate directories."), then ask:
```
AskUserQuestion({
"question": "What matters most for this review configuration?",
"options": [
"Security & Correctness — catch secrets, auth gaps, bugs, async errors, type misuse",
"Code Quality & Performance — complexity, duplication, naming, N+1 queries, resource leaks",
"Test Coverage & Conventions — flag missing tests, enforce commit messages, PR size, naming patterns",
"All of the above"
]
})
```
Record the selected priorities. Security and Correctness always produce **prescriptive rules** ("MUST", "NEVER", "CRITICAL") because violations are always wrong. Code quality, performance, test coverage, and conventions produce **directional rules** ("prefer", "consider", "flag when") that allow judgment.
---
## Step 3: Generate root REVIEW.md
Generate a root REVIEW.md with 8–10 rules drawn from the detected stack and selected priorities. Rules must be specific and verifiable — see guidance below.
**Rule writing standards** (derived from research on LLM instruction-following):
- Prescriptive rules for security and correctness: state the requirement, then state why in one sentence. Example: "CRITICAL: Never commit secrets or API keys in source files. Use environment variables or secret managers — exposure in git history is permanent."
- Directional rules for quality and conventions: state the preference, then the escape hatch or rationale. Example: "Prefer composition over inheritance. Deep hierarchies make behavior unpredictable — flag more than 2 levels unless there is an explicit abstraction reason."
- One-liners are acceptable only when the rule is truly unambiguous. Two-sentence rules with rationale outperform one-liners for anything contextual.
- CRITICAL label is reserved for security and correctness violations that are always wrong. Use it for at most 3–4 rules per file — overuse destroys emphasis.
- Do not write rules that duplicate what linters catch deterministically (formatting, indentation, import sorting).
**Start with conservative thresholds:**
```markdown
## Confidence Threshold
85
## Severity Threshold
medium
## Model Tier
optimized
```
The research consensus: start at confidence 85 and severity medium for the first 2–4 weeks. Lower thresholds after reviewing acceptance rates. Document this in a comment above the thresholds block.
**Rule sections** — organize by selected priorities:
- Security (always first, if selected)
- Correctness / language-specific bugs
- Architecture and design (if code quality selected)
- Performance (if selected)
- Tests (if selected)
- Conventions (always last, if selected)
**Skip patterns** — always include a full skip block with generated/binary/lock files appropriate to the detected stack. Standard set:
```markdown
## Skip
**/bin/**
**/obj/**
**/dist/**
**/node_modules/**
**/.next/**
**/Generated/**
package-lock.json
pnpm-lock.yaml
yarn.lock
**/*.g.cs
**/Migrations/*.Designer.cs
**/.vs/**
**/*.suo
**/*.user
**/*.png
**/*.jpg
**/*.woff2
**/*.woff
```
Adjust for detected stack (e.g., add `**/target/**` for Rust/Java, `**/__pycache__/**` for Python, `**/vendor/**` for Go).
**Output** — write the file to `REVIEW.md` at the repo root. Announce: "Root REVIEW.md written with [N] rules."
---
## Step 4: Generate subdirectory REVIEW.md(s)
Apply the multi-stack decision test: for each technology-specific rule you want to add, ask: **"Would this rule generate false positives when applied to the other stack?"**
If yes → the rule belongs in a subdirectory REVIEW.md.
If no → the rule belongs in the root REVIEW.md.
**Only create subdirectory configs when the answer is "yes" for at least 3 rules.** A single technology-specific rule does not justify a new file — add it to root with a path qualifier in the rule text: "For files in `backend/`: prefer event-sourced state transitions over direct entity mutation."
**When creating subdirectory configs:**
- Include `## Model Tier` and technology-specific `## Skip` patterns only
- Do not repeat rules that are already in root
- Do not contradict root rules — extend them. If root says "prefer immutable types," the subdirectory rule should add the escape hatch, not contradict
- Subdirectory configs should have 5–8 rules each; stop at the second directory level
**Common subdirectory rules by stack:**
*TypeScript/React frontend:*
- TypeScript strict mode enforcement (no `any`, no `@ts-ignore` without comment)
- React hooks rules (no conditional hooks, useEffect cleanup, dependency arrays)
- RTK Query cache invalidation (invalidatesTags on mutations)
- Zod schema validation at API boundaries (.safeParse() not type assertions)
*.NET/C# backend:*
- Async/await patterns (no .Result/.Wait(), async void except event handlers, CancellationToken)
- EF Core patterns (N+1 detection, AsNoTracking for reads, scoped DbContext)
- DI lifetime correctness (no scoped in singleton)
*Python:*
- Type hints required on public functions
- SQLAlchemy session management (no session reuse across requests)
- Async correctness (no blocking calls in async functions)
*Go:*
- Error wrapping with context (errors.Wrap, not bare return err)
- Context propagation (first argument, no context.Background() in handlers)
- Goroutine leak prevention (always close channels, cancel contexts)
**Output** — write each subdirectory REVIEW.md. Announce each file written and the rule count.
---
## Step 5: Exit
After all files are written, output a brief summary:
```
REVIEW.md created. Start your review — the config will be picked up automatically.
Files written:
REVIEW.md — [N] rules ([threshold] confidence, medium severity)
[subdir]/REVIEW.md — [N] rules (if applicable)
Thresholds are conservative for week 1. After 2–4 weeks, review your acceptance rate:
- If >60% of findings result in fixes, lower severity threshold to "low"
- If false positives accumulate, raise confidence threshold to 90
- Run `code-gauntlet` on any open PR to see results immediately
```
Do not offer to run a review or explain the review process. The user can trigger code-gauntlet separately.
---
## Critical Rules
1. **No code review.** This skill configures — it does not analyze code for bugs, security issues, or quality problems.
2. **Prescriptive for non-negotiables, directional for preferences.** Never write a CRITICAL rule for a style preference, never write a directional rule for a security requirement.
3. **15–25 rules total across all files.** Exceeding this degrades LLM instruction-following. Prefer 8–10 in root, 5–8 per subdirectory.
4. **Do not create subdirectory configs without the decision test.** Technology-specific rules that pass the false-positive test belong in root with a path qualifier.
5. **Conservative defaults.** Always start at confidence 85, severity medium. The research is unambiguous: teams that start broad generate noise and lose trust.