review-chapter

name	review-chapter
description	Review a workshop chapter — check content accuracy, phrasing, style, exercise coverage, and structural issues. Accepts a git ref, chapter directory, or defaults to the current diff.
disable-model-invocation	false
allowed-tools	Bash, Read, Agent, Explore
user-invocable	true

Workshop Chapter Review

Review a chapter of this proc macro workshop for quality, accuracy, and completeness.

Input

The user provides one of:

• A git ref (commit hash, branch name) or jj change ID — review all chapter files changed in that ref/change.
• A chapter directory path (e.g. book/src/01_introduction) — review that chapter.
• Nothing — review the current uncommitted changes (git diff or jj diff).

What to review

1. Content accuracy

• Are technical claims correct? Flag anything misleading or wrong.
• Are code examples valid Rust? Check that they would compile (or are clearly marked as pseudocode).
• Are macro types correctly identified? (e.g. don't call vec! a procedural macro when it's macro_rules!; don't call #[test] an attribute macro when it's a compiler built-in.)
• Do links point to real crates/docs?
• When third-party crates or macros are mentioned by name (e.g. thiserror, serde::Serialize, tokio::main), are they linked to their docs.rs documentation? Flag any unlinked crate/macro references.

2. Phrasing and style

• Compare against the tone of sibling Mainmatter workshops (see CLAUDE.md for reference paths). The tone should be: direct, second-person ("you"), concise sentences, no filler.
• Flag overly long paragraphs, passive voice, or jargon that isn't explained.
• Flag inconsistent terminology (e.g. switching between "proc macro" and "procedural macro" without reason).
• Check spelling and grammar in both book sections and exercise comments/docstrings. Flag typos, subject-verb disagreements, missing articles, incorrect punctuation, etc.

3. Book section ↔ exercise alignment

For each book section (book/src/<module>/<section>.md), find its matching exercise (exercises/<module>/<section>/). Check:

• Does the exercise test the concepts introduced in the section?
• Are there concepts in the section that the exercise doesn't touch? Flag gaps.
• Does the exercise introduce concepts not covered in the section? Flag surprises.
• Does the exercise description in the book's "## Exercise" paragraph match what the exercise actually asks?
• Are there mismatches between the book text and exercise code (e.g. book says "enum" but exercise uses a struct)?

4. Exercise quality

• Is the todo!() placement clear — does the participant know what to fill in?
• Are test assertions correct and sufficient?
• Do tests leak the answer too obviously (e.g. expected values in assertion comments)?
• Are exercise Cargo.toml dependencies correct and using workspace dependencies where appropriate?

5. Structural issues

• Are there orphaned or misplaced files (e.g. placeholder files for future modules in the wrong directory)?
• Is book/src/SUMMARY.md consistent with the actual files?
• Does the chapter match the plan in toc.md?

6. Suggestions to extend

• Are there obvious topics the section should cover but doesn't?
• Would a concrete example, number, or tip make a point more tangible?
• Are there practical tips for the workshop context (e.g. workspace-specific cargo commands)?

Output format

Structure the review as:

## Content & Phrasing

Per-section notes (use ### for each section filename). Only flag issues — don't narrate what's fine.

## Structural Issues

Problems with file organization, SUMMARY.md, toc.md alignment, placeholder files.

## Suggestions to Extend

Numbered list of concrete suggestions with rationale.

## Exercise Coverage Summary

| Section | Exercise | Coverage |
|---|---|---|
| ... | ... | Good / Adequate / Gap: <description> |

Keep it concise. Lead each finding with the specific file and line if applicable. Don't pad with praise — focus on actionable items.