Build Review Md

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(
  questions: [{
    question: "A REVIEW.md already exists at the repo root. What would you like to do?",
    header: "REVIEW.md",
    multiSelect: false,
    options: [
      { label: "Extend it (Recommended)", description: "Add rules to what's already there, keeping existing settings" },
      { label: "Start fresh", description: "Replace it with a newly generated REVIEW.md" },
      { label: "Cancel", description: "Keep the existing file unchanged and exit" }
    ]
  }]
)

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(
  questions: [{
    question: "What matters most for this review configuration?",
    header: "Priorities",
    multiSelect: false,
    options: [
      { label: "All of the above (Recommended)", description: "Security, correctness, quality, performance, tests, and conventions" },
      { label: "Security & Correctness", description: "Secrets, auth gaps, bugs, async errors, type misuse" },
      { label: "Code Quality & Performance", description: "Complexity, duplication, naming, N+1 queries, resource leaks" },
      { label: "Tests & Conventions", description: "Missing tests, commit messages, PR size, naming patterns" }
    ]
  }]
)

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).

Do not pin a threshold the user didn't ask for. The pipeline's built-in defaults (non-security confidence 55, security confidence 70, severity low — everything shown) apply automatically whenever a key is absent from REVIEW.md's config block; writing an explicit number here — even a "conservative starting point" — silently overrides that default the moment the wizard runs, for every user, without them choosing it. A ## Confidence Threshold / ## Severity Threshold markdown heading is never parsed at all (references/review-md-spec.md in the code-gauntlet skill → Format) — the only mechanism that works is the fenced config block, with the four snake_case keys inside it. Emit the block with the threshold keys commented out as digit-free examples:

# code-gauntlet
# confidence_threshold: <0-100>
#   Built-in default when omitted: 55 for non-security dimensions, 70 for security.
# severity_threshold: <critical|high|medium|low>
#   Built-in default when omitted: low (show everything).

If Step 2 surfaced an explicit user preference for a starting threshold, uncomment the relevant key and write that value instead of leaving the example commented out — but never substitute a number the user didn't state.

Do not emit a ## Model Tier section. Nothing reads it (issue #153): the model policy is fixed to the single benchmarked configuration, and the only remaining pin is the fail-loud CODE_GAUNTLET_MODEL_TIER env knob. Emitting the heading advertises a knob that does not exist.

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)

Do not generate a ## Skip section. There is no REVIEW.md mechanism that excludes files from review by glob pattern — a ## Skip heading is inert prose, never parsed (references/review-md-spec.md → "Rules and other prose"). Generating one implies a working feature that does not exist.

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?"

Subdirectory rules are advisory prose shared with every context-reading agent (summarize, discovery, validate; the file location is provenance); only thresholds and ignore patterns are enforced for that subtree.

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:

• Emit ## Rules and, if needed, a config block — no ## Model Tier and no ## Skip (see Step 3)
• 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 (built-in thresholds: 55 confidence / 70 for security, low severity)
  [subdir]/REVIEW.md — [N] rules  (if applicable)

The built-in thresholds show everything above 55 confidence (70 for security
findings) at any severity. After a few reviews, tune them in REVIEW.md's config block if needed:
- If false positives accumulate, uncomment and raise `confidence_threshold`
- If low-severity noise drowns out what matters, uncomment and set `severity_threshold` to medium or high
- 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. Never pin an unrequested threshold. Leave confidence_threshold / severity_threshold commented out in the generated config block unless the user explicitly asked for a specific value — the pipeline's built-in defaults (55 non-security / 70 security confidence, low severity) already apply when the keys are absent.
6. Never generate a ## Skip section. It is never parsed — generating one implies a feature that does not exist.
7. Never emit a ## Model Tier section. Nothing reads it (issue #153) — emitting it advertises a knob that does not exist.