Document Conventions

Document conventions

Turn what /infer-conventions finds into this project's REVIEW.md, and commit it. Run once per project, re-run to amend.

Find: where the project keeps its standards and what its stack is — via /infer-conventions, confirmed with the user.

Produce: REVIEW.md at the repo root — a natural-language table of contents mapping each review pass to the docs that define "correct" for it. It has succeeded when a review can judge against the project's real standards by following it, without re-discovering anything.

Step 1 — Discover and confirm

Use /infer-conventions, then check what it found with the user — "these are your conventions docs, correct? Anything missed, anything wrong?" It's a conversation, not a form. Correct it from their answers before writing anything.

Step 2 — Write REVIEW.md

Write REVIEW.md at the repo root (create it if missing; merge into it if it exists). Write it the way you'd guide a human teammate to the right docs.

Structure it as a ## <pass> section per pass (mission, architecture, implementation, craft, security, performance), with the docs for that pass beneath it. Notes on writing it well:

• Point at documents, don't restate rules. If a rule lives in a doc, say "see knowledge/technical/conventions.md" — don't copy the rule into REVIEW.md. This file is a map, not a duplicate of your standards.
• Natural language beats dry key-value. A short sentence like "Architecture generally lives in knowledge/technical/, with the important system docs below:" reads better than a bare list, and the reviewing agent reads it more accurately.
• Give explicit "look at these for X" pointers. Prefer naming the specific docs a pass should read, over a general pointer to the folder.
• Omit passes with no project-specific standard. Don't invent sections. If the project has no security doc, there's no security section. Never pad with a "see conventions.md" pointer unless that doc genuinely covers the topic — verify by reading it, not by assuming. A genuinely uncovered pass can get a one-line note under ## Notes ("security isn't documented; guidance is incidental in X"), not a fake section.
• Optional ## Notes section. For anything that doesn't fit a pass — repo quirks, review preferences, things to always check. Only add it if there's something worth saying.

Example shape (adapt to what the project actually has — do not include sections that don't apply):

# <Project> Review Brief

Tells the review skill where this project keeps its standards. Each pass reads
the docs mapped below. Edit by hand, or re-run `/document-conventions` to regenerate.

## Stack

<framework(s) and key libraries>

## Mission

- <where the PR description / issue / PRD lives, and what defines "done">

## Architecture

Architecture generally lives in `<folder>`. The key docs are:

- `<path>` — <what it covers>
- `<path>` — <what it covers>

## Implementation

- `<conventions path>` — behavioral conventions, authoritative
- `<testing path>` — how this project tests

## Security

- see `<conventions path>` for security rules

## Notes

- <anything worth saying that doesn't fit above>

Step 3 — Commit

Stage and commit REVIEW.md. Follow the project's commit conventions.