# Youglin Dev Aha Loop Doc Review > Doc Review Skill - Skill: `tomevault-io/youglin-dev-aha-loop-doc-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/youglin-dev-aha-loop-doc-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/youglin-dev-aha-loop-doc-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/youglin-dev-aha-loop-doc-review --- # Doc Review Skill Systematically review documentation for staleness, accuracy, and relevance. --- ## The Job 1. Scan all documentation files 2. Check for staleness indicators 3. Verify referenced code/files still exist 4. Identify outdated content 5. Generate cleanup report 6. Optionally apply fixes --- ## When to Use ### Scheduled - After each milestone completion - Monthly maintenance cycle - Before major releases ### On Demand - When documentation feels outdated - After significant refactoring - When onboarding reveals confusion --- ## Review Process ### Step 1: Inventory Documentation Scan for documentation files: ```bash find . -name "*.md" -not -path "./.git/*" -not -path "./.vendor/*" -not -path "./.worktrees/*" ``` Common locations: - `README.md` (root and subdirs) - `docs/` directory - `AGENTS.md`, `CLAUDE.md` - `.claude/skills/*/SKILL.md` - `knowledge/` directory - `scripts/aha-loop/templates/` ### Step 2: Check Staleness Indicators For each document, check: | Indicator | Check Method | Threshold | |-----------|--------------|-----------| | Last modified | `git log -1` | > 30 days | | Referenced files | grep + verify | Missing = stale | | Code examples | Syntax check | Errors = stale | | Version numbers | Compare to actual | Mismatch = stale | | Links | HTTP check | Broken = stale | ### Step 3: Verify Code References For each code reference in docs: ```markdown ## Code Reference Check File: [doc-path] Reference: `src/main.rs:45-60` Status: [Exists | Missing | Changed] If Changed: - Original: [what doc says] - Current: [what code shows] - Action: [Update doc | Flag for review] ``` ### Step 4: Check External Links ```bash # Extract URLs grep -oP 'https?://[^\s)]+' file.md # Check each URL curl -s -o /dev/null -w "%{http_code}" URL ``` ### Step 5: Generate Report Create `docs-review-report.md`: ```markdown # Documentation Review Report **Date:** [YYYY-MM-DD] **Reviewed:** [N] files **Issues Found:** [N] ## Summary | Category | Count | |----------|-------| | Stale (>30 days) | [N] | | Missing References | [N] | | Broken Links | [N] | | Outdated Examples | [N] | ## Issues by File ### [file1.md] - [ ] Line 45: Reference to `src/old.rs` - file no longer exists - [ ] Line 78: Code example uses deprecated API ### [file2.md] - [ ] Line 12: Version "1.0.0" should be "2.0.0" - [ ] Line 56: Broken link to external docs ## Recommended Actions 1. **Delete:** [files that should be removed] 2. **Update:** [files that need content updates] 3. **Review:** [files that need human review] ## Auto-fixable The following can be auto-fixed: - [ ] Update version numbers - [ ] Remove dead links - [ ] Update file paths Run `./scripts/aha-loop/doc-cleaner.sh --fix` to apply. ``` --- ## Staleness Criteria ### Definitely Stale - References files that don't exist - Contains code that doesn't compile - Links to 404 pages - Describes features that were removed ### Probably Stale - Not modified in 60+ days - Uses old API patterns - References old version numbers - No recent git commits mention the file ### Needs Human Review - Contains outdated but complex content - Describes deprecated but still-supported features - Historical documentation (changelogs, decisions) --- ## Auto-Fix Rules ### Safe to Auto-Fix - Update file paths (if clear mapping exists) - Remove broken external links - Update version numbers in dependency lists - Fix obvious typos in code references ### Requires Human Review - Content changes beyond mechanical updates - Removing entire sections - Changing technical instructions - Modifying architecture decisions --- ## Integration ### With Doc Cleaner Script ```bash # Generate report only ./scripts/aha-loop/doc-cleaner.sh --report # Apply safe fixes ./scripts/aha-loop/doc-cleaner.sh --fix # Interactive mode ./scripts/aha-loop/doc-cleaner.sh --interactive ``` ### With Observability Log review activities: ```markdown ## 2026-01-29 16:00:00 | Task: Maintenance | Phase: Doc Review ### Documentation Review Scanned 45 files, found 7 issues. ### Key Findings - AGENTS.md references outdated skill paths - README example code uses deprecated API ### Actions Taken - Auto-fixed 3 version number issues - Flagged 4 items for human review ``` --- ## Checklist Before completing review: - [ ] All markdown files scanned - [ ] Code references verified - [ ] External links checked - [ ] Report generated - [ ] Auto-fixes applied (if safe) - [ ] Human review items flagged --- ## Example Review ### Input File: `docs/api.md` last modified 90 days ago ```markdown # API Documentation ## Authentication See `src/auth/mod.rs` for implementation. Use version 0.5.0 of the auth library: ```toml auth-lib = "0.5.0" ``` More info: https://example.com/old-docs ``` ### Review Findings 1. **Stale**: Last modified 90 days ago 2. **Missing Reference**: `src/auth/mod.rs` doesn't exist (moved to `src/api/auth.rs`) 3. **Outdated Version**: Current version is 1.2.0, not 0.5.0 4. **Broken Link**: https://example.com/old-docs returns 404 ### Report Entry ```markdown ### docs/api.md **Staleness:** 90 days since last update **Issues:** - [ ] Line 5: `src/auth/mod.rs` → `src/api/auth.rs` - [ ] Line 8: Version 0.5.0 → 1.2.0 - [ ] Line 12: Broken link (404) **Recommendation:** Update file paths and versions, remove broken link ``` --- ## Prevention To reduce future staleness: 1. **Update docs with code** - When changing code, update related docs 2. **Add doc checks to CI** - Fail on broken references 3. **Schedule regular reviews** - Monthly or per-milestone 4. **Use relative links** - Easier to maintain than absolute 5. **Date-stamp examples** - "As of v1.2.0" --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/youglin-dev) — claim your Tome and manage your conversions.