executing-comprehensive-reviews

# 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 ``` 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 ```markdown ## 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** | Pattern | Route To | |---------|----------| | "review {file} for clarity" | Clarity only | | "suggest questions for {file}" | Questions only | | "check alignment" | Alignment only | | "comprehensive review of {file}" | Clarity + Questions | | "review chapter {N}" | Explore -> Clarity + Questions | **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 ```