diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 62e2fb5..d05a397 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -225,7 +225,7 @@ "description": "Optimize user CLAUDE.md files by applying progressive disclosure principles. This skill should be used when users want to reduce CLAUDE.md bloat, move detailed content to references, extract reusable patterns into skills, or improve context efficiency. Triggers include optimize CLAUDE.md, reduce CLAUDE.md size, apply progressive disclosure, or complaints about CLAUDE.md being too long", "source": "./", "strict": false, - "version": "1.0.0", + "version": "1.0.1", "category": "productivity", "keywords": ["claude-md", "progressive-disclosure", "optimization", "context-efficiency", "configuration", "token-savings"], "skills": ["./claude-md-progressive-disclosurer"] diff --git a/CHANGELOG.md b/CHANGELOG.md index b2cb178..460a401 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Security - None +## [1.18.2] - 2026-01-05 + +### Changed +- **claude-md-progressive-disclosurer**: Enhanced workflow with safety and verification features + - Added mandatory backup step (Step 0) before any modifications + - Added pre-execution verification checklist (Step 3.5) to prevent information loss + - Added post-optimization testing (Step 5) for discoverability validation + - Added exception criteria for size guidelines (safety-critical, high-frequency, security-sensitive) + - Added project-level vs user-level CLAUDE.md guidance + - Updated references/progressive_disclosure_principles.md with verification methods +- Updated claude-md-progressive-disclosurer plugin version from 1.0.0 to 1.0.1 + ## [1.18.1] - 2025-12-28 ### Changed diff --git a/claude-md-progressive-disclosurer/SKILL.md b/claude-md-progressive-disclosurer/SKILL.md index 6ecf2dd..a5628a8 100644 --- a/claude-md-progressive-disclosurer/SKILL.md +++ b/claude-md-progressive-disclosurer/SKILL.md @@ -9,10 +9,13 @@ Analyze and optimize user CLAUDE.md files to reduce context overhead while prese ## Quick Start -1. Read the user's `~/.claude/CLAUDE.md` -2. Analyze each section using the classification criteria below -3. Propose optimizations with before/after line counts -4. Execute approved changes +1. **Backup** the original file first +2. **Audit** the current state (list all sections with line counts) +3. **Classify** each section using the criteria below +4. **Propose** optimizations with before/after comparison table +5. **Verify** information completeness checklist before executing +6. **Execute** approved changes +7. **Test** that moved content remains discoverable ## Section Classification @@ -25,12 +28,44 @@ Analyze each section and classify: | **Extract to skill** | Reusable workflows, scripts, domain-specific knowledge | Create skill in skills repository | | **Remove** | Duplicates existing skills, outdated, or unnecessary | Delete after confirmation | +### Exceptions to Size Guidelines + +Even if a section is >50 lines, **KEEP in CLAUDE.md** if any of these apply: + +| Exception | Reason | Example | +|-----------|--------|---------| +| **Safety-critical** | Consequences of forgetting are severe | Deployment protocols, "never force push to main" | +| **High-frequency** | Referenced in most conversations | Core development patterns, common commands | +| **Easy to violate** | Claude tends to ignore when not visible | Code style rules, permission requirements | +| **Security-sensitive** | Must be always enforced | Production access restrictions, data handling rules | + +**Rule of thumb**: If forgetting the rule could cause production incidents, data loss, or security breaches, keep it visible regardless of length. + ## Optimization Workflow +### Step 0: Backup Original File + +**CRITICAL**: Always create a backup before any changes. + +```bash +# Create timestamped backup +cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S) + +# For project-level CLAUDE.md +cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S) +``` + +If issues found after optimization: +```bash +# Restore from backup +cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md +``` + ### Step 1: Audit Current State ``` Task Progress: +- [ ] Create backup (Step 0) - [ ] Read ~/.claude/CLAUDE.md - [ ] Count total lines - [ ] List all ## sections with line counts @@ -62,14 +97,84 @@ Present optimization plan in this format: | Section C | 5 | Keep | - | ``` +### Step 3.5: Pre-execution Verification Checklist + +**CRITICAL**: Before executing any changes, verify information completeness. + +For each section being moved or modified: + +1. **Extract key items** to verify: + - Credentials/passwords/API keys + - Critical rules ("never do X", "always do Y") + - Specific values (ports, IPs, URLs, paths) + - Code snippets that are frequently referenced + - Cross-references to other sections + +2. **Create verification checklist**: + ```markdown + ## Verification Checklist for [Section Name] + + | Key Item | Original Location | New Location | Verified | + |----------|-------------------|--------------|----------| + | Server IP 47.96.x.x | Line 123 | infrastructure.md:15 | [ ] | + | "Never push to main" rule | Line 45 | Kept in CLAUDE.md | [ ] | + | Login credentials | Line 200 | api-login.md:30 | [ ] | + ``` + +3. **Check cross-references**: + - If Section A references Section B, ensure links work after moving + - Update any relative paths to absolute paths if needed + ### Step 4: Execute Changes -After user approval: +After user approval AND verification checklist complete: 1. Create reference files in `~/.claude/references/` 2. Update CLAUDE.md with pointers to moved content 3. Create skills if applicable -4. Report final line count +4. **Verify each checklist item exists in new location** +5. Report final line count + +### Step 5: Post-optimization Testing + +Verify that Claude can still discover moved content: + +1. **Test discoverability** - Ask questions that require moved content: + ``` + Test queries to run: + - "How do I connect to the production database?" + - "What are the deployment steps for [service]?" + - "Show me the credentials for [system]" + ``` + +2. **Verify pointer functionality** - Each "See `reference.md`" link should work: + ```bash + # Check all referenced files exist + grep -oh '`~/.claude/references/[^`]*`' ~/.claude/CLAUDE.md | \ + sed 's/`//g' | while read f; do + eval test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f" + done + ``` + +3. **Compare with backup** - Ensure no unintended deletions: + ```bash + diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20 + ``` + +4. **Document results**: + ```markdown + ## Optimization Results + + | Metric | Before | After | + |--------|--------|-------| + | Total lines | X | Y | + | Reduction | - | Z% | + | References created | - | N files | + | Skills extracted | - | M skills | + + **Verification**: All N checklist items verified ✓ + **Testing**: All K test queries returned correct information ✓ + ``` ## Reference File Format @@ -111,3 +216,42 @@ Replace moved sections with: ### Pattern: Reusable Workflows **Before**: Complete scripts embedded in CLAUDE.md **After**: Extract to skill with scripts/ directory + +## Project-Level vs User-Level CLAUDE.md + +This skill handles both types, but strategies differ: + +### User-Level (`~/.claude/CLAUDE.md`) + +| Aspect | Approach | +|--------|----------| +| **Reference location** | `~/.claude/references/` | +| **Scope** | Personal preferences, global rules | +| **Sharing** | Not shared, personal only | +| **Size target** | 100-200 lines ideal | + +### Project-Level (`/path/to/project/CLAUDE.md`) + +| Aspect | Approach | +|--------|----------| +| **Reference location** | `docs/` or `.claude/` in project root | +| **Scope** | Project-specific patterns, architecture | +| **Sharing** | Committed to git, shared with team | +| **Size target** | 300-600 lines acceptable (more project context needed) | + +### Key Differences + +1. **Reference paths**: Use relative paths for project-level (`docs/best-practices/`) +2. **Git considerations**: Project references are versioned with code +3. **Team alignment**: Project CLAUDE.md should reflect team consensus +4. **Update frequency**: Project-level changes more often as code evolves + +### Project-Level Pointer Format + +```markdown +## [Section Title] + +[Summary]. See `docs/06-best-practices/[topic].md` +``` + +**Note**: For project CLAUDE.md, prefer `docs/` over hidden directories for discoverability by human team members. diff --git a/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md b/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md index 2a4f205..f872173 100644 --- a/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md +++ b/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md @@ -46,7 +46,20 @@ Every line in CLAUDE.md consumes context tokens on EVERY conversation. Moving 10 | 1-10 | Keep in CLAUDE.md | | 11-30 | Consider consolidating or moving | | 31-50 | Strongly consider moving to references | -| 50+ | Must move to references or extract to skill | +| 50+ | Move to references or extract to skill | + +### Exceptions (Keep Regardless of Size) + +**Do NOT move** even if >50 lines: + +| Category | Reason | Examples | +|----------|--------|----------| +| **Safety-critical** | Severe consequences if forgotten | Deployment protocols, production access rules | +| **High-frequency** | Used in most conversations | Core commands, common patterns | +| **Easily violated** | Claude ignores when not visible | Style rules, permission checks | +| **Security-sensitive** | Must always be enforced | Data handling, access restrictions | + +**Rule**: If forgetting causes production incidents, data loss, or security breaches → keep visible. ## Reference File Organization @@ -86,3 +99,49 @@ After optimization, verify: 2. **Information preserved**: All functionality still accessible 3. **Discoverability**: Claude finds moved content when needed 4. **Maintenance**: Easier to update individual reference files + +### Verification Methods + +#### 1. Information Preservation Check + +Before executing, create a checklist of key items from each moved section: + +```markdown +| Key Item | Original Line | New Location | Verified | +|----------|---------------|--------------|----------| +| Server IP | L123 | infra.md:15 | [ ] | +| Password | L200 | infra.md:42 | [ ] | +| Critical rule | L45 | Kept | [ ] | +``` + +#### 2. Discoverability Test + +After optimization, test with real queries: + +``` +Test: "How do I deploy to production?" +Expected: Should find deployment steps in reference file + +Test: "What's the database password?" +Expected: Should find in infrastructure reference + +Test: "Can I force push to main?" +Expected: Should find rule (ideally still in CLAUDE.md) +``` + +#### 3. Pointer Verification Script + +```bash +# Check all referenced files exist +grep -oh '`[^`]*\.md`' ~/.claude/CLAUDE.md | \ + sed 's/`//g' | while read f; do + test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f" + done +``` + +#### 4. Backup Comparison + +```bash +# See what was removed +diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" +```