Documentation Refresh

Documentation Refresh Skill (Experimental)

Purpose: Maintain accurate, consistent, and synchronized project documentation across multiple files as the repository state evolves.

> Experimental: Developed against a single large review project. > Verification scripts and file hierarchy may need adaptation.

When to Use This Skill

Use this skill when:

• Project state has changed (new features, completed phases, updated statistics)
• Documentation files are out of sync with current reality
• Need to verify documentation accuracy and consistency
• Major milestone reached requiring documentation update
• Multiple documentation files need coordinated updates

Core Principles

Single source of truth: Each fact should be documented in one authoritative location and referenced elsewhere.

Consistency: Same information must be identical across all files where it appears.

Currency: Documentation must reflect current state, not historical state (unless explicitly historical).

Verification: After updates, verify all cross-references and numbers match reality.

Distillation: Each document has a specific purpose and size target. See the auto-memory skill for the full documentation hierarchy.

---

Complete Workflow

Phase 1: Identify What Changed

Goal: Determine what needs updating before making changes.

1. Review Recent Work

Check conversation history, commits, or recent changes:

• What phases completed?
• What statistics changed?
• What new workflows were established?
• What files were added/removed?
• What principles were learned?

2. List Affected Documentation

Common documentation files:

• CLAUDE.md: Repository instructions and essentials
• MEMORY.md: Current state and complete workflows
• README.md: Public-facing overview
• docs/*.md: Detailed process documentation
• Tracking documents (e.g., MRS_BY_AUTHOR.md)

3. Identify Inconsistencies

Compare numbers across files:

# Example: Check if MR counts match
grep -E "Open MRs|Total MRs|MR.*:" CLAUDE.md MEMORY.md docs/*.md

# Check dates
grep -E "Last updated|Updated:" CLAUDE.md MEMORY.md docs/*.md

# Check statistics
grep -E "authors|branches|reviews" CLAUDE.md MEMORY.md

Phase 2: Update Documentation Files

Order matters: Update from specific → general (detailed docs first, overview docs last).

1. Update Detailed Process Documentation (docs/*.md)

These contain procedures, examples, and detailed workflows.

What to update:

• Current statistics (counts, percentages)
• File structure diagrams
• Example commands with current data
• Quality checklists
• Last updated dates

Example: docs/REVIEW_PROCESS.md

**Last updated**: YYYY-MM-DD
**Open MRs**: XX
**Review files**: XX (.md) + XX (_reasoning.txt)
**Master base**: 

Preserve:

• Procedures and workflows (unless changed)
• Examples (update numbers, not methodology)
• Commands and code blocks (unless improved)

2. Update Repository Memory (MEMORY.md)

Update all sections: Current Status, Key Files, Workflows, Recent Work, Statistics, and "Last updated" date. Update ALL statistics, not just some. See the auto-memory skill for MEMORY.md structure and maintenance guidelines.

3. Update Repository Instructions (CLAUDE.md)

Bare essentials only — no detailed procedures. Update: Completed Work Summary, Core Principles, File Organization, Restrictions. Keep concise (~100-150 lines). Detailed workflows belong in MEMORY.md, procedures in docs/*.md.

4. Update Tracking Documents

Documents that track current state (e.g., MRS_BY_AUTHOR.md, status files):

What to update:

• Header statistics (total counts)
• Remove closed/completed items
• Update counts per category/author
• Verify accuracy against source of truth files

Always verify:

# Example: Verify tracking doc matches data file
grep -c 'pattern' TRACKING_DOC.md
wc -l /dev/null | wc -l)"

4. Check Cross-References

Verify references between files work:

# Check if referenced files exist
grep -oE 'docs/[A-Za-z_-]+\.md' CLAUDE.md MEMORY.md | while read ref; do
  if [ -f "$ref" ]; then
    echo "✓ $ref exists"
  else
    echo "✗ $ref MISSING"
  fi
done

Phase 4: Garbage Collection

If any file exceeds its target size (CLAUDE.md > 200, MEMORY.md > 500) or contains information duplicated across files, trim it. See the auto-memory skill (Phase 5: Garbage Collection) for the full evaluation framework, keep/remove criteria, and target sizes.

Phase 5: Quality Checks

1. Formatting

Check line width if project has constraints:

# Example: 120 char limit
for file in CLAUDE.md MEMORY.md docs/*.md; do
  cnt=$(awk 'length > 120 {print NR": " substr($0,1,80)"..."}' "$file" | wc -l)
  if [ "$cnt" -gt 0 ]; then
    echo "$file: $cnt lines over 120 chars"
  fi
done

2. Broken Links

Check markdown links:

# Extract markdown links
grep -oE '\[.*\]\(.*\)' CLAUDE.md MEMORY.md docs/*.md | \
  grep -oE '\(.*\)' | tr -d '()' | while read link; do
    # Check local file links
    if [[ ! "$link" =~ ^http ]]; then
      if [ ! -f "$link" ]; then
        echo "✗ Broken link: $link"
      fi
    fi
  done

3. Consistency of Terminology

Ensure consistent naming:

• Same feature/phase names across docs
• Consistent file naming references
• Consistent metrics (e.g., "Open MRs" vs "Active MRs")

4. Completeness

Verify each file covers its required sections. See the auto-memory skill for CLAUDE.md and MEMORY.md structure checklists. For docs/*.md: detailed procedures, examples with current data, commands, and last updated date.

---

Common Refresh Triggers

| Trigger | Update | |---------|--------| | Milestone reached | Add to CLAUDE.md summary, update stats everywhere | | Statistics changed | Update MEMORY.md status, CLAUDE.md phase summaries, docs, verify consistency | | New workflow | Add to MEMORY.md, add principle to CLAUDE.md if foundational | | File org changed | Update CLAUDE.md file org, MEMORY.md key files, docs structure |

For all triggers: update dates everywhere and verify consistency.

---

Anti-Patterns to Avoid

Don't duplicate detailed procedures:

❌ CLAUDE.md contains step-by-step workflow (200 lines)
✓ CLAUDE.md references MEMORY.md, which has complete workflow

Don't have stale statistics:

❌ CLAUDE.md: "50 open MRs", MEMORY.md: "48 open MRs"
✓ All files: "48 open MRs" (consistent)

Don't forget dates:

❌ Last updated: 2026-03-27 (but today is 2026-04-10)
✓ Last updated: 2026-04-10

Don't update only some files:

❌ Updated MEMORY.md, forgot CLAUDE.md
✓ Updated all affected files, verified consistency

Don't make CLAUDE.md too detailed:

❌ CLAUDE.md: 300+ lines with examples and commands
✓ CLAUDE.md: ~120 lines with essentials only

Don't leave broken references:

❌ References `docs/WORKFLOW.md` which doesn't exist
✓ All referenced files exist and are current

---

Verification Checklist

Before finalizing documentation updates:

Consistency:

• [ ] All statistics match across files
• [ ] Dates are current on all updated files
• [ ] File counts match reality
• [ ] Terminology is consistent

Completeness:

• [ ] All phases documented in CLAUDE.md
• [ ] Current state accurate in MEMORY.md
• [ ] Workflows complete in MEMORY.md
• [ ] Procedures detailed in docs/*.md

Quality:

• [ ] CLAUDE.md under 150 lines (distilled)
• [ ] No duplicated procedures across files
• [ ] All file references valid
• [ ] Formatting compliant (if applicable)

Cross-references:

• [ ] CLAUDE.md points to MEMORY.md for workflows
• [ ] MEMORY.md points to docs/*.md for details
• [ ] All referenced files exist

Accuracy:

• [ ] Numbers verified against source files
• [ ] Tracking docs match data files
• [ ] No outdated information

---

Example Refresh Session

# 1. Identify changes
echo "What changed: MRs closed (50 → 48), reasoning files created (22)"

# 2. Update docs/*.md
# Updated docs/REVIEW_PROCESS.md:
# - Repository Structure (added reasoning files)
# - Added reasoning files section
# - Updated statistics (48 open MRs, 50+22 files)
# - Updated last updated date

# 3. Update MEMORY.md
# - Current Status (48 open, 15 closed)
# - Key Files (reasoning files documented)
# - Added complete Review Workflow section
# - Recent Work (added reasoning file creation)
# - Statistics (updated all numbers)
# - Last updated date

# 4. Update CLAUDE.md
# - Phase 4 summary (added reasoning files)
# - Phase 5 summary (updated counts)
# - File Organization (added reasoning files)
# - Restrictions (added reasoning file rules)
# - Last updated date
# - Trimmed from 228 → 123 lines

# 5. Verify consistency
./verify_docs.sh
# ✓ All statistics match
# ✓ All files have current dates
# ✓ File counts verified

# 6. Quality check
for file in CLAUDE.md MEMORY.md docs/*.md; do
  awk 'length > 120' "$file" | wc -l
done
# ✓ All compliant

---

Quick Reference

Update order: docs/*.md → MEMORY.md → CLAUDE.md → tracking docs.

Essential commands:

# Compare statistics
grep -E "Open|Closed|Total" CLAUDE.md MEMORY.md docs/*.md

# Check dates
grep "Last updated" CLAUDE.md MEMORY.md docs/*.md

# Verify file counts
ls reviews/*.md | wc -l  # Compare with documented counts

# Check consistency
./verify_docs.sh  # Custom verification script

Key principles:

1. Update specific → general (detailed docs first)
2. Verify consistency after updates
3. Keep CLAUDE.md concise (essentials only)
4. MEMORY.md is self-contained (complete workflows)
5. Update ALL affected files, not just some

---

Version History

• 1.0.0 (2026-04-11): Initial version with update, verify, and quality check phases
• 1.2.0 (2026-07-18): Deduped with auto-memory skill
• 1.1.0 (2026-04-13): Garbage collection phase

See Also

• auto-memory - For creating and maintaining project-level MEMORY.md files
• review - After review milestones, use refresh-docs to update project documentation
• create-skill - For capturing reusable workflows as global skills

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvalena
• Source: pvalena/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.