review

name	review
description	Review all pending changes against repo conventions before committing
allowed-tools	Shell Read Glob Grep

Review — Pre-Commit Quality Gate

Systematically review all staged and unstaged changes before committing. Catches misplaced files, missing READMEs, convention violations, stale cross-references, and content issues before they enter the commit history.

This command is read-only. It reports findings and asks for confirmation before any commit proceeds.

- Repo conventions: `.cursor/rules/repo-structure.mdc` - Cross-linking and registry rules: `.cursor/rules/cross-linking.md` - Review frontmatter: `rules/review-tracking.md` - Current changes: `git status` - Staged diff: `git diff --cached --stat` - Unstaged diff: `git diff --stat` - Untracked files: `git ls-files --others --exclude-standard` 1. **Inventory changes** — List all new, modified, and deleted files from git status. Group by: new files, modified files, deleted files.

2. Placement check — For each new file, verify it belongs in its directory per the repo-structure rule:

   • Is a product-specific file in the right {product}/ directory?
   • Is research output in research/{topic}/?
   • Is documentation in docs/?
   • Are repo root files limited to the allowed set?
   • Flag any misplaced files with suggested locations.

3. README coverage — For each new directory, check it has a README.md. For each new file in an existing directory, check the directory's README is updated to mention it (if the README maintains a contents list).

4. Cross-reference and registry check — For new content, verify the registries from .cursor/rules/cross-linking.md are updated:

   • If new doc in docs/: is it in the track README.md and docs/README.md cross-track list?
   • If new file in library/: is it in library/README.md enriched entries table AND library/catalog.md?
   • If new research directory: is it listed in research/README.md?
   • If new skill in .agents/skills/: auto-discovered by all clients, no registry update needed.
   • If new project in .planning/: is it in .cursorrules planning section?
   • If new prompt: is it numbered correctly in .prompts/ and listed in .cursorrules?
   • If new backlog items: are dates and product tags present?
   • Quick link spot-check: For each new or modified markdown file, verify any internal links (relative paths) resolve to files that exist. Flag broken links.
   • External URL verification: For each new or modified markdown file, identify any new external URLs (http/https). Fetch each URL to confirm it resolves (not 404, not redirect to unrelated page). AI models fabricate plausible-looking URLs — this is a known failure mode, not an edge case. Flag any unverified or broken external links.
   • Red Hat docs (docs.redhat.com): Apply rules/red-hat-docs-links.md. Flag /latest/ URLs without chapter/section title in link text; flag slug-only link text; note when only /latest/ was checked and redirects were not followed to final URL.

5. Content quality — For each new or modified file:

   • Markdown files: check for title heading, no obvious structural issues
   • Artifact discipline (TAGRI + JBGE) — For new or substantially expanded markdown (not trivial README line edits):
     • TAGRI: Name the intended reader and the decision/action the doc enables. Flag if unclear or missing.
     • JBGE: Flag sections that look like template fill, duplicate structure, or verbosity beyond context (skilled audience, high change likelihood → should be lighter). Reference: submodules/zanshin-pi-extension/kit/AGILE-ARTIFACT-DISCIPLINE.md
   • Config files: check for valid syntax if tooling is available
   • Shell scripts (.sh, .bash): verify strict mode header present — #!/usr/bin/env bash + set -euo pipefail. Flag missing headers as "Missing shell strict mode". Exception: scripts with a comment explaining why strict mode is intentionally omitted are fine.
   • No secrets, credentials, or sensitive data (flag .env, *secret*, *credential*, *password*, *token* patterns in content)

6. Biographical/voice check — For new or modified files in docs/, scan for content that speaks in the author's voice or makes biographical claims. Flag lines containing:

   • Professional titles or role descriptions applied to the author
   • First-person claims about experience, training, or career ("I trained," "in my years of")
   • Personal opinions stated as fact ("I believe," "I've found that")
   • Biographical details (training history, personal philosophy, specific life events)

   Present flagged lines with their file and line number under a "Biographical Content — Needs voice-approved" section. This is the highest-priority review item — readers will attribute these statements to the author. This is NOT a blocker, but it must be visible.

7. Review staleness check — For each modified file (not new), read its frontmatter. If it contains review: status: reviewed, flag it prominently:

   • "Stale review: file.md was reviewed on DATE but is being modified in this commit. The author needs to re-read the changes."
   • If the frontmatter includes an at: SHA, include the diff command: "Run git diff SHA..HEAD -- file.md to see what changed since last review."
   • This is the highest-priority informational item — it's the easiest thing to miss and the hardest to recover from. Present it above other findings.

8. Review frontmatter check — For each new markdown file under docs/ or devops/, verify YAML frontmatter includes a review: block with status: (typically unreviewed on creation). See rules/review-tracking.md for the canonical format.

   • Flag missing blocks: "Missing review frontmatter: file.md"
   • If file has other YAML keys (description:, tags:) but no review:, flag as missing — merge into existing frontmatter, do not add a second fence
   • Remind: "Run /validate <path> read after you've reviewed these files"
   • If biographical content was flagged in step 6, remind: "Run /validate <path> voice-approved after reviewing the biographical content"

9. AI disclosure footer check — For each new markdown file under docs/ or devops/, check that it includes the standard AI disclosure footer:

   • The footer should be an italic line at the end of the file linking to AI-DISCLOSURE.md
   • Standard text: This content was created with AI assistance. See AI-DISCLOSURE.md for how to interpret AI-generated content in this workspace.
   • The relative path to AI-DISCLOSURE.md depends on file depth (e.g., ../../ for files two levels below repo root)
   • Flag missing footers: "Missing AI disclosure: file.md — new markdown file without standard footer"
   • This is a quick fix (add the footer) but easy to forget when creating new reference material

10. Backlog alignment — Read BACKLOG.md and check if the work being committed relates to a tracked item. If not, note it (not a blocker, just a reminder).

11. Present findings as a structured report:

## Pre-Commit Review

### Changes Summary
- N new files, M modified, D deleted

### Stale Reviews (re-read needed)
- [ ] `file.md` — reviewed DATE, modified in this commit → `git diff SHA..HEAD -- file.md`
(or: No reviewed files modified.)

### Biographical Content — Needs `voice-approved`
- [ ] `file.md` line N: "quote of biographical claim"
(or: No biographical content detected in changed files.)

### Issues Found
- [ ] [severity] Description — suggested fix

### Verified
- File placement: OK / issues
- README coverage: OK / issues
- Cross-references: OK / issues
- External URLs: N verified / M broken or unverified
- Content quality: OK / issues
- Artifact discipline (TAGRI/JBGE): OK / N flags
- Secrets scan: OK / issues
- Biographical scan: N lines flagged / clean
- Stale reviews: N reviewed files modified (re-read needed) / none
- Review frontmatter: OK / N new files missing `review:` block
- AI disclosure footer: OK / N new files missing footer
- Backlog alignment: tracked / untracked

### Blind Spots to Consider
- [work type] — [what was assumed but not verified]
- [work type] — [observation]
(or: No blind spots identified — change is mechanical with no conditional logic, variable inputs, or audience assumptions.)

12. Blind spots by work type — Classify the dominant type(s) of change from the diff, then surface 1-3 things that were likely assumed stable or known but not explicitly verified. This runs on every commit — the questions differ by type, but the underlying ask is always the same: "What did you assume was already handled?"

Classify by dominant change type and apply the relevant questions:

Work type	Signals in diff	Ask
Template / config	.yaml in templates/, Helm charts, Jinja	What data shapes were assumed? Which weren't rendered against? What optional or runtime-injected fields were not tested absent?
Documentation	.md in docs/, research/, essays	Who was written for? Who will also read this and find it confusing or misleading?
Framework / convention	.cursor/rules/, .agents/skills/, CLAUDE.md, .cursorrules	What inherits this convention? Are all downstream consumers consistent?
Feature addition	New functions, new template blocks, new flags	What happens at the edges — empty input, disabled flag, wrong type, missing field?
Refactor / deletion	Removed files, renamed paths, deleted blocks	What referenced the removed thing? Is anything broken silently?
Mixed	Multiple types above	Apply 1 question from each dominant type

Produce observations as a new report section:

### Blind Spots to Consider
- [work type] — [what was assumed but not verified] — e.g., "Template: groups entries tested as strings; object-shape entries (with targetRevision) not rendered separately"
- [work type] — [observation] — e.g., "Documentation: written for engineers already familiar with ArgoCD; a first-time reader has no context for what a hub is"
- [work type] — [observation] — e.g., "Deletion: option-b-applicationset.yaml removed; checked docs/ for references but not .planning/ files"

This section is never skipped. If the change is purely mechanical and no blind spots are apparent, say so explicitly: "No blind spots identified — change is mechanical with no conditional logic, variable inputs, or audience assumptions."

13. Content assumptions to challenge (for documentation and essay commits) — If the changes include docs/, research/, or essay-type content, add 1-3 brief adversarial observations on the claims the content makes. These are not blockers — they surface things the author should have considered:

### Content Assumptions to Challenge
- [observation] — e.g., "The central claim in section 3 is asserted without evidence"
- [observation] — e.g., "This contradicts the framing in docs/ai-engineering/the-shift.md section 6"
- [observation] — e.g., "The example assumes a single-region deployment"

Skip this section for non-content changes (config files, tooling, scaffolding, templates). This is only useful for prose that makes claims.

14. Brief alignment check (shoshin) — If the changes include files in docs/ or .planning/, check for framing drift:

• Read the relevant project brief (.planning/*/BRIEF.md) for any planning project connected to the changed files
• Compare the content being committed against the brief's stated scope and purpose
• Flag if the content narrows scope the brief says is broad, broadens scope the brief says is focused, or introduces framing that contradicts the style guide

### Brief Alignment
- [project]: Content aligns with brief scope.
  OR
- [project]: This essay narrows focus to [X] but the brief says the scope includes [Y]. Update the brief or broaden the essay.
  OR
- [project]: The style guide says [convention] but this content [violates it].

Skip for changes that don't touch docs or planning files. If no .planning/ project is connected to the changed files, skip.

### Recommendation
[READY TO COMMIT / FIX ISSUES FIRST]

15. If issues are found, ask: "Want me to fix these before committing? Reply with numbers or 'all'."

16. If clean, ask: "Ready to commit. Want me to proceed?"

<success_criteria>

• Every new file checked against placement rules
• Every new directory checked for README
• Cross-references verified for docs, research, and prompts
• No secrets or credentials in staged content
• Modified files with review: frontmatter flagged as stale reviews
• External URLs verified (fetched, not just eyeballed)
• New docs/ and devops/ markdown files checked for review: frontmatter
• New docs/ and devops/ markdown files checked for AI disclosure footer
• Clear recommendation: commit or fix first
• User confirms before any commit happens </success_criteria>