Executing Comprehensive Reviews

Guide for content review workflows including clarity improvements, question generation, and book-implementation alignment validation.

Instructions

Step 1: Parse Review Requirement

Extract from request:

• •Target: Specific file, chapter, or pattern
• •Review Type: clarity | questions | alignment | comprehensive
• •Scope: Single file, chapter, full codebase

Type Detection:

• •Contains "clarity" or "clear" -> Clarity review
• •Contains "question" or "deeper" -> Questions review
• •Contains "align" or "implementation" -> Alignment check
• •Contains "comprehensive" or "full" -> All types
• •Ambiguous -> Ask user which type(s)

Step 2: Optional Exploration

If requirement is broad or exploratory:

1. •

   Search for relevant content

   code

   Glob: chapters/**/*.md
   Grep: {topic keywords}
   

2. •

   Read identified files to assess coverage

3. •

   Create exploration summary:

   • •Relevant entries discovered
   • •Content gaps identified
   • •Relationship mappings

Skip exploration if:

• •Specific file path provided
• •Review type is alignment (has own discovery)
• •User requests direct review only

Step 3: Execute Review Type(s)

Clarity Review

For improving readability without changing voice:

1. •Read target content completely
2. •Identify clarity issues:
   • •Ambiguous sentences
   • •Missing transitions
   • •Jargon without context
   • •Overly complex structure
3. •Propose improvements preserving authorial voice
4. •Present suggestions to user for approval
5. •Apply approved changes
6. •Update last_updated in frontmatter

Voice preservation checklist:

• •Maintains first-person where used
• •Keeps practical, experience-based tone
• •Preserves original examples
• •Doesn't over-formalize

Questions Review

For generating follow-up questions to deepen content:

1. •Read target content completely
2. •Identify deepening opportunities:
   • •Claims that could use evidence
   • •Patterns that could use examples
   • •Concepts that connect to other chapters
   • •Edge cases not addressed
3. •Generate 3-5 follow-up questions
4. •Present questions to user for selection
5. •Add selected questions under "### Follow-up" heading
6. •Update last_updated in frontmatter

Question quality criteria:

• •Answerable from experience/research
• •Leads to actionable content
• •Not already covered in file
• •Connects to reader needs

Alignment Check

For validating book-implementation consistency:

1. •

   Inventory phase:

   • •Scan CLAUDE.md for documented commands/agents
   • •List all .claude/ files and structures
2. •

   Cross-reference phase:

   • •Check each documented item exists
   • •Check each implemented item is documented
3. •

   Pattern validation:

   • •Verify documented patterns match implementation
   • •Check file paths are accurate
4. •

   Link validation:

   • •Test internal links in documentation
   • •Verify file references resolve
5. •

   Report findings:

   • •Orphans: Exist but undocumented
   • •Phantoms: Documented but missing
   • •Broken links: Invalid references
   • •Pattern compliance: Match/mismatch

Alignment is read-only - no modifications, just diagnostics.

Step 4: Synthesize Findings

Collect outputs from all executed reviews:

From Exploration (if run):

• •Entries discovered
• •Gaps identified
• •Relationships mapped

From Clarity:

• •Issues found
• •Suggestions approved
• •Files modified

From Questions:

• •Questions generated
• •Questions added
• •Themes identified

From Alignment:

• •Orphan count
• •Phantom count
• •Broken links
• •Compliance status

Step 5: Prioritize Recommendations

High Priority (Breaking issues)

• •Alignment: Missing implementations, broken links
• •Clarity: Confusing core concepts

Medium Priority (Content gaps)

• •Questions: Unanswered follow-ups
• •Exploration: Missing relationships

Low Priority (Polish)

• •Clarity: Minor improvements
• •Style: Consistency tweaks

Step 6: Report Results

## Review Complete

**Requirement:** {original requirement}

### Reviews Executed

| Type | Status | Key Findings |
|------|--------|--------------|
| Exploration | Complete/Skipped | {entries} found |
| Clarity | Complete/Skipped | {issues} found, {applied} fixed |
| Questions | Complete/Skipped | {count} generated |
| Alignment | Complete/Skipped | {gaps} identified |

### Priority Recommendations

**High:** {numbered list}
**Medium:** {numbered list}
**Low:** {numbered list}

### Files Modified

{list with brief descriptions}

### Next Steps

- {context-specific actions}

Key Principles

Type Routing Matrix

Sequential Execution

• •Exploration -> Review -> Synthesis
• •Each stage informs the next
• •Don't parallelize within a review

User Choice Points

• •Which review types to run
• •Whether to apply clarity suggestions
• •Which questions to add
• •Alignment runs automatically (read-only, safe)

Synthesis Over Pass-Through

• •Don't concatenate reports
• •Extract key findings across reviews
• •Prioritize by impact
• •Provide actionable next steps

Examples

Example 1: Clarity review on specific file

Request: "Review chapters/6-patterns/2-self-improving-experts.md for clarity"

Execute:
- Skip exploration (file specified)
- Read file completely
- Identify 3 clarity issues
- Present suggestions
- User approves 2
- Apply changes
- Update frontmatter

Report: "2 clarity improvements applied"

Example 2: Generate questions for content

Request: "Suggest follow-up questions for chapter 8"

Execute:
- Explore chapter 8 structure
- Find 4 relevant entries
- Generate questions for each
- Present: 12 questions total
- User selects 5
- Add to respective files

Report: "5 questions added across 4 files"

Example 3: Alignment check

Request: "Check alignment between book and implementation"

Execute:
- Inventory CLAUDE.md references
- Scan .claude/ structure
- Cross-reference

Findings:
- 2 orphan commands (exist, undocumented)
- 1 phantom reference (documented, missing)
- 3 broken internal links

Report: "6 alignment issues found, 1 high priority"

Example 4: Comprehensive chapter review

Request: "Comprehensive review of chapter 7"

Execute:
- Explore: Find 6 entries
- Alignment: Check chapter references
- Clarity: Review each entry
- Questions: Generate follow-ups

Synthesize:
- High: 1 broken link
- Medium: 3 clarity issues
- Low: 8 potential questions

Report with prioritized action list