shrink-doc

name	shrink-doc
description	Compress documentation while preserving execution equivalence (validation-driven approach)

Validation-Driven Document Compression

Task: Compress the documentation file: {{arg}}

Goal: Reduce document size while preserving execution equivalence using objective validation instead of prescriptive rules.

---

Workflow

Step 1: Validate Document Type

BEFORE compression, verify this is a Claude-facing document:

ALLOWED (Claude-facing):

• .claude/ configuration files:
  • .claude/agents/ - Agent definitions (prompts for sub-agents)
  • .claude/commands/ - Slash commands (prompts that expand when invoked)
  • .claude/hooks/ - Hook scripts (execute on events)
  • .claude/settings.json - Claude Code settings
• CLAUDE.md and project instructions
• docs/project/ development protocol documentation
• docs/code-style/*-claude.md style detection patterns

Why slash commands are Claude-facing: When you invoke /shrink-doc, the contents of .claude/commands/shrink-doc.md expand into a prompt for Claude to execute. The file is NOT for users to read - it's a configuration that defines what Claude does when the command is invoked.

FORBIDDEN (Human-facing):

• README.md, changelog.md, CHANGELOG.md
• docs/studies/, docs/decisions/, docs/performance/
• docs/optional-modules/ (potentially user-facing)
• todo.md, docs/code-style/*-human.md

⚠️ SPECIAL HANDLING: CLAUDE.md

When compressing CLAUDE.md, use content reorganization instead of standard compression:

Step 1: Analyze Content Location Before compressing, categorize ALL content into:

Category	Action
Duplicates skills	REMOVE - reference skill instead
Main-agent-specific	MOVE to main-agent-specific file
Sub-agent-specific	MOVE to sub-agent-specific file
Universal (all agents)	KEEP in CLAUDE.md

Step 2: Check for Duplication

# Check if content already exists in skills
ls .claude/skills/

# Check if procedural content duplicates a skill
grep -l "pattern" .claude/skills/*/SKILL.md

Step 3: Content Categories

Examples are illustrative; specific categories vary by project.

REMOVE (duplicates existing):

• Procedural content that exists in skills
• Content already documented in agent-specific files

MOVE (agent-specific):

• Main-agent-only content (e.g., multi-agent coordination, repository structure)
• Sub-agent-only content (e.g., specific workflow steps only they perform)

KEEP (universal guidance):

• Tone/style, error handling, security policies
• Content that applies equally to ALL agent types

Step 4: Result Structure

CLAUDE.md should be a slim reference document (~200 lines) that:

• Contains ONLY universal guidance for ALL agents
• Instructs agents to read their agent-specific files (e.g., "MAIN AGENT: Read {file}.md")
• References skills for procedural content (not duplicate them)

Hub-and-Spoke Pattern:

CLAUDE.md (universal, ~200 lines)
  ├── "MAIN AGENT: Read {main-agent-file}.md"
  └── "SUB-AGENTS: Read {sub-agent-file}.md"

Agent-specific files contain the detailed content moved out of CLAUDE.md. Create these files if they don't exist. CLAUDE.md becomes a routing document that directs agents to their specialized guidance.

Why This Approach: Standard compression preserves all content in place. CLAUDE.md benefits from reorganization because much content is duplicated elsewhere or is agent-specific. Moving content to appropriate locations reduces redundancy across the entire documentation system.

Validation: After reorganization, verify:

# CLAUDE.md should be ~200-250 lines (not 800+)
wc -l CLAUDE.md

# No procedural duplication with skills
grep -c "Step 1:" CLAUDE.md  # Should be minimal

---

⚠️ SPECIAL HANDLING: Style Documentation Files

When compressing .claude/rules/*.md or docs/code-style/*-claude.md:

Preserve style rule sections (lines starting with ### ). These are intentionally-added detection patterns and rules. Compression can:

• ✅ Condense explanatory text within sections
• ✅ Shorten verbose rationale paragraphs
• ✅ Combine redundant examples
• ❌ Deleting entire ### Section Name blocks breaks detection
• ❌ Removing detection patterns or code examples breaks detection

Verification Required: After compression, count section headers:

ORIGINAL_SECTIONS=$(grep -c "^### " /tmp/original-{filename})
COMPRESSED_SECTIONS=$(grep -c "^### " /tmp/compressed-{filename}-v${VERSION}.md)
if [ "$COMPRESSED_SECTIONS" -lt "$ORIGINAL_SECTIONS" ]; then
  echo "❌ ERROR: Section(s) removed! Original: $ORIGINAL_SECTIONS, Compressed: $COMPRESSED_SECTIONS"
  echo "   Style rule sections must be preserved. Iterate to restore missing sections."
fi

Why This Protection Exists: Session from 2025-12-19 had documentation update remove intentionally-added "Use 'empty' Not 'blank'" style rule section, causing repeated data loss during subsequent rebases.

If forbidden, respond:

This compression process only applies to Claude-facing documentation.
The file `{{arg}}` appears to be human-facing documentation.

Examples:

• ✅ ALLOWED: .claude/commands/shrink-doc.md (slash command prompt)
• ✅ ALLOWED: .claude/agents/architect.md (agent prompt)
• ❌ FORBIDDEN: README.md (user-facing project description)
• ❌ FORBIDDEN: changelog.md (user-facing change history)

---

Step 2: Check for Existing Baseline

Check if baseline exists from prior iteration:

BASELINE="/tmp/original-{{filename}}"
if [ -f "$BASELINE" ]; then
  BASELINE_LINES=$(wc -l < "$BASELINE")
  CURRENT_LINES=$(wc -l < "{{arg}}")
  echo "✅ Found existing baseline: $BASELINE ($BASELINE_LINES lines)"
  echo "   Current file: $CURRENT_LINES lines"
  echo "   Scores will compare against original baseline."
fi

If NO baseline exists, optionally check git history for prior compression:

if [ ! -f "$BASELINE" ]; then
  RECENT_SHRINK=$(git log --oneline -5 -- {{arg}} 2>/dev/null | grep -iE "compress|shrink|reduction" | head -1)
  if [ -n "$RECENT_SHRINK" ]; then
    echo "ℹ️ Note: File was previously compressed (commit: $RECENT_SHRINK)"
    echo "   No baseline preserved. Starting fresh with current version as baseline."
  fi
fi

---

Step 3: Invoke Compression Agent

Use Task tool with subagent_type: "general-purpose" and simple outcome-based prompt:

Agent Prompt Template:

**Document Compression Task**

**File**: {{arg}}

**Goal**: Compress while preserving **perfect execution equivalence** (score = 1.0).

**Compression Target**: ~50% reduction is ideal, but lesser compression is acceptable. Perfect equivalence (1.0) is mandatory; compression amount is secondary.

---

## What is Execution Equivalence?

**Execution Equivalence** means: A reader following the compressed version will achieve the same results as someone following the original.

**Preserve**:
- **YAML frontmatter** (between `---` delimiters) - REQUIRED for slash commands
- **Decision-affecting information**: Claims, requirements, constraints that affect what to do
- **Relationship structure**: Temporal ordering (A before B), conditionals (IF-THEN), prerequisites, exclusions (A ⊥ B), escalations
- **Control flow**: Explicit sequences, blocking checkpoints (STOP, WAIT), branching logic
- **Executable details**: Commands, file paths, thresholds, specific values

**Safe to remove**:
- **Redundancy**: Repeated explanations of same concept
- **Verbose explanations**: Long-winded descriptions that can be condensed
- **Meta-commentary**: Explanatory comments about the document (NOT structural metadata like YAML frontmatter)
- **Non-essential examples**: Examples that don't add new information
- **Elaboration**: Extended justifications or background that don't affect decisions

---

## Compression Approach

**Focus on relationships**:
- Keep explicit relationship statements (Prerequisites, Dependencies, Exclusions, Escalations)
- Preserve temporal ordering (Step A→B)
- Maintain conditional logic (IF-THEN-ELSE)
- Keep constraint declarations (CANNOT coexist, MUST occur after)

**Condense explanations**:
- Remove "Why This Ordering Matters" verbose sections → keep ordering statement
- Remove "Definition" sections that explain obvious terms
- Combine related claims into single statements where possible
- Use high-level principle statements instead of exhaustive enumeration (when appropriate)

---

## Output

Read `{{arg}}`, compress it, and **USE THE WRITE TOOL** to save the compressed version.

**⚠️ CRITICAL**: You MUST actually write the file using the Write tool. Do NOT just describe
or summarize the compressed content - physically create the file.

**Target**: ~50% word reduction while maintaining execution equivalence.

Execute compression:

# Invoke agent
Task tool: general-purpose agent with above prompt

---

Step 4: Validate with /compare-docs

⚠️ CRITICAL: Before saving compressed version, read and save the ORIGINAL document state to use as baseline for validation.

After agent completes:

1. Save original document (ONLY if baseline doesn't exist):

   BASELINE="/tmp/original-{{filename}}"
   if [ ! -f "$BASELINE" ]; then
     cp {{arg}} "$BASELINE"
     echo "✅ Saved baseline: $BASELINE ($(wc -l < "$BASELINE") lines)"
   else
     echo "✅ Reusing existing baseline: $BASELINE"
   fi
   

   Why baseline is preserved: Baseline is kept until user explicitly confirms they're done iterating (see Step 5). This ensures scores always compare against the TRUE original, not intermediate compressed versions.

2. Determine version number and save compressed version:

   VERSION_FILE="/tmp/shrink-doc-{{filename}}-version.txt"
   
   # Get next version number from persistent counter (survives across sessions)
   if [ -f "$VERSION_FILE" ]; then
     LAST_VERSION=$(cat "$VERSION_FILE")
     VERSION=$((LAST_VERSION + 1))
   else
     # First time: check for existing version files to continue numbering
     HIGHEST=$(ls /tmp/compressed-{{filename}}-v*.md 2>/dev/null | sed 's/.*-v\([0-9]*\)\.md/\1/' | sort -n | tail -1)
     if [ -n "$HIGHEST" ]; then
       VERSION=$((HIGHEST + 1))
     else
       VERSION=1
     fi
   fi
   
   # Save version counter for next iteration
   echo "$VERSION" > "$VERSION_FILE"
   
   # Save with version number for rollback capability
   # Agent output → /tmp/compressed-{{filename}}-v${VERSION}.md
   echo "📝 Saved as version ${VERSION}: /tmp/compressed-{{filename}}-v${VERSION}.md"
   

   Why persistent versioning: Version numbers continue across sessions (v1, v2 in session 1 → v3, v4 in session 2) so older revisions are never overwritten. This enables rollback to any previous version and maintains complete compression history.

3. Verify YAML frontmatter preserved (if compressing slash command):

   head -5 /tmp/compressed-{{filename}}-v${VERSION}.md | grep -q "^---$" || echo "⚠️ WARNING: YAML frontmatter missing!"
   

4. Run validation AGAINST ORIGINAL:

   # ALWAYS compare against original baseline, NOT current file state
   /compare-docs /tmp/original-{{filename}} /tmp/compressed-{{filename}}-v${VERSION}.md
   

   ⚠️ IMPORTANT: The validation score reflects execution equivalence between:

   • Document A: Original document state BEFORE /shrink-doc was invoked in this session
   • Document B: Newly compressed candidate version

   NOT a comparison against any intermediate compressed versions.

5. Parse validation result:

   • Extract execution_equivalence_score
   • Extract warnings and lost_relationships
   • Extract structural_changes

Scoring Context: When reporting the score to the user, explicitly state:

Score {score}/1.0 compares the compressed version against the ORIGINAL document
state from before /shrink-doc was invoked (not against any intermediate versions).

⚠️ CRITICAL REMINDER: On second, third, etc. invocations:

• ✅ REUSE /tmp/original-{{filename}} from first invocation
• ✅ Always compare against original baseline (not intermediate versions)
• The baseline is set ONCE on first invocation and REUSED for all subsequent invocations

---

Step 5: Decision Logic

Threshold: 1.0

Report Format (for approval):

1. What was preserved
2. What was removed
3. Validation Details (claim/relationship/graph scores)
4. Results (original size, compressed size, reduction %, execution equivalence score)
5. Version Comparison Table (showing all versions generated in this session)

⚠️ CRITICAL: List execution equivalence score at bottom for easy visibility.

Version Comparison Table Format:

After presenting validation results for ANY version, show comparison table.

Table format:

Version	Lines	Size	Reduction	Score	Status
Original	{n}	{n}K	baseline	N/A	Reference
V{n}	{n}	{n}K	{n}%	{n}	{status}

Expected output format:

Version	Lines	Size	Reduction	Score	Status
Original	{n}	{n}K	baseline	N/A	Reference
V1	{n}	{n}K	{n}%	{n}	Rejected
V2	{n}	{n}K	{n}%	{n}	Applied

Status values:

• Approved = Score equals 1.0
• Rejected = Score below 1.0
• Applied = Currently applied to original file

Example:

Version	Lines	Size	Reduction	Score	Status
Original	1,057	48K	baseline	N/A	Reference
V1	520	26K	51%	0.89	Rejected
V2	437	27K	59%	0.97	Applied

---

If score = 1.0: ✅ APPROVE

Validation passed! Execution equivalence: {score}/1.0

✅ Approved version: /tmp/compressed-{{filename}}-v${VERSION}.md

Writing compressed version to {{arg}}...

→ Overwrite original with approved version → Clean up versioned compressions: rm /tmp/compressed-{{filename}}-v*.md → KEEP baseline: /tmp/original-{{filename}} preserved for potential future iterations

After applying changes, ASK user:

Changes applied successfully!

Would you like to try again to generate an even better version?
- YES → I'll keep the baseline and iterate with new compression targets
- NO → I'll clean up the baseline (compression complete)

If user says YES (wants to try again): → Keep /tmp/original-{{filename}} → Future /shrink-doc invocations will reuse this baseline → Scores will reflect cumulative compression from true original → Go back to Step 3 with user's feedback

If user says NO (done iterating): → rm /tmp/original-{{filename}} → rm /tmp/shrink-doc-{{filename}}-version.txt → Note: Future /shrink-doc on this file will use compressed version as new baseline

If score < 1.0: ❌ ITERATE

Validation requires improvement. Score: {score}/1.0 (threshold: 1.0)

Components:
- Claim preservation: {claim_score}
- Relationship preservation: {relationship_score}
- Graph structure: {graph_score}

**Why < 1.0 requires iteration**:
Scores below 1.0 indicate relationship abstraction or loss that creates
interpretation vulnerabilities. See /compare-docs § Score Interpretation
for detailed vulnerability analysis.

**Common issues at this score range**:
- Abstraction ambiguity (e.g., "ALL of X" → separate statements)
- Lost mutual exclusivity constraints
- Conditional logic flattening (IF-THEN-ELSE → flat list)
- Temporal dependencies implicit rather than explicit

Issues found:
{list warnings from /compare-docs}

Specific relationship losses:
{list lost_relationships with details}

Re-invoking agent with feedback to fix issues...

→ Go to Step 6 (Iteration)

⚠️ MANDATORY: Score Validation Gate (M254)

BLOCKING REQUIREMENT: Complete this validation BEFORE making any approval decision.

Step 1: Extract exact score value

SCORE={exact decimal from /compare-docs execution_equivalence_score}

Step 2: Perform explicit comparison

THRESHOLD=1.0
IS_EXACTLY_ONE=$(echo "$SCORE == $THRESHOLD" | bc -l)

Step 3: Decision based ONLY on comparison result

if [ "$IS_EXACTLY_ONE" -eq 1 ]; then
  DECISION="APPROVE"
else
  DECISION="ITERATE"  # ANY value less than 1.0, including 0.99, 0.999, etc.
fi

Step 4: State decision with explicit score verification

Score: {SCORE}/1.0
Comparison: {SCORE} == 1.0 → {true|false}
Decision: {DECISION}

FAIL-FAST: If DECISION=ITERATE, STOP. Do not ask user for approval. Proceed directly to Step 6 (Iteration Loop).

Why this gate exists (M254): Completion bias causes agents to rationalize "close enough" scores. Only exact equality (score == 1.0) permits approval. No exceptions.

Anti-patterns (blocked by this gate):

• ❌ "Score 0.97, close enough to 1.0" → BLOCKED (0.97 ≠ 1.0)
• ❌ "Score 0.99, good enough" → BLOCKED (0.99 ≠ 1.0)
• ❌ "Score 0.999, essentially perfect" → BLOCKED (0.999 ≠ 1.0)
• ✅ "Score 1.0" → APPROVED (1.0 == 1.0)

---

Step 6: Iteration Loop

If score < 1.0, invoke agent again with specific feedback:

Iteration Prompt Template:

**Document Compression - Revision Attempt {iteration_number}**

**Previous Score**: {score}/1.0 (threshold: 1.0)

**Issues Identified by Validation**:

{warnings from /compare-docs}

**Lost Relationships**:

{for each lost_relationship:}
- **{type}**: {from_claim} → {to_claim}
  - Constraint: {constraint}
  - Evidence: {evidence}
  - Impact: {violation_consequence}
  - **Fix**: {specific recommendation}

**Your Task**:

Revise the compressed document to restore the lost relationships while maintaining compression.

**Original**: /tmp/original-{{filename}}
**Previous Attempt**: /tmp/compressed-{{filename}}-v${VERSION}.md

Focus on:
1. Restoring explicit relationship statements identified above
2. Maintaining conditional structure (IF-THEN-ELSE)
3. Preserving mutual exclusivity constraints
4. Keeping escalation/fallback paths

**⚠️ CRITICAL**: USE THE WRITE TOOL to save the revised document to the specified path.
Do NOT just describe or return the content - you MUST physically write the file.

After iteration:

• Save revised version as next version number (v${VERSION+1})
• Re-run /compare-docs validation AGAINST ORIGINAL BASELINE
• Apply decision logic again (Step 5)

🚨 MANDATORY: /compare-docs Required for EVERY Iteration

CRITICAL: You MUST invoke /compare-docs (SlashCommand tool) for EVERY version validation. There are NO exceptions. Manual validation, estimation, or checklist-based scoring is PROHIBITED.

Why This Is Non-Negotiable:

• Session 7937e222: Agent manually validated v2/v3 with self-created checklist → score 0.97
• Independent re-analysis: Actual score was 0.72 (25% inflation)
• Result: Compression approved that lost critical content

Validation Anti-Patterns (ALL are violations):

❌ WRONG #1: Manual checklist validation

"Let me assess v2 improvements..."
| Category | Original | v2 | Preserved |
| State machine | ✅ | ✅ | 100% |
[creates own checklist, assigns 100% to all]
"Estimated Score: 0.97"

Why wrong: Agent knows what SHOULD be there, confirms it exists (confirmation bias)

❌ WRONG #2: Estimation without /compare-docs

"Good progress on v2. Estimated Score: ~0.88"

Why wrong: No independent extraction, just subjective assessment

❌ WRONG #3: Custom Task prompt with items to verify

Task: "Verify these 6 improvements are present: 1. X, 2. Y..."

Why wrong: Primes validator to confirm checklist, misses other losses

✅ CORRECT: Invoke /compare-docs for EVERY version

# v1 validation
/compare-docs /tmp/original-{filename} /tmp/compressed-{filename}-v1.md

# v2 validation (after iteration)
/compare-docs /tmp/original-{filename} /tmp/compressed-{filename}-v2.md

# v3 validation (after iteration)
/compare-docs /tmp/original-{filename} /tmp/compressed-{filename}-v3.md

Enforcement: Score is ONLY valid if it comes from /compare-docs output. Any score derived from manual assessment, estimation, or targeted validation is INVALID.

Self-Check Before Reporting Score:

1. Did I invoke /compare-docs (SlashCommand tool) for this version? YES/NO
2. Is the score from /compare-docs output, not my own calculation? YES/NO
3. If either is NO → STOP and invoke /compare-docs

Maximum iterations: 3

• If still < 1.0 after 3 attempts, report to user and ask for guidance
• All versions preserved in /tmp for rollback
• User may choose to accept best attempt or abandon compression

---

Implementation Notes

Agent Type: MUST use subagent_type: "general-purpose"

Validation Tool: Use /compare-docs (SlashCommand tool)

Validation Baseline: On first invocation, save original document to /tmp/original-{filename} and use this as baseline for ALL subsequent validation comparisons in the session.

Versioning Scheme: Each compression attempt is saved with incrementing version numbers for rollback capability.

File Operations:

• Read original: Read tool
• Save original baseline: Write tool to /tmp/original-{filename} (once per session)
• Save versioned compressed: Write tool to /tmp/compressed-{filename}-v1.md, /tmp/compressed-{filename}-v2.md, etc.
• Overwrite original: Write tool to {{arg}} (only after approval)
• Cleanup after approval: rm /tmp/compressed-{filename}-v*.md /tmp/original-{filename}

Rollback Capability:

• If latest version unsatisfactory, previous versions available at /tmp/compressed-{filename}-v{N}.md
• Example: If v3 approved but later found problematic, can review v1 or v2
• Versions automatically cleaned up after successful approval

Iteration State:

• Track iteration count via version numbers
• Provide specific feedback from validation warnings
• ALWAYS validate against original baseline, not previous iteration

---

Success Criteria

✅ Compression approved when:

• Execution equivalence score = 1.0

✅ Compression quality metrics:

• Word reduction: ~50% (target)
• Execution equivalence: = 1.0
• Claim preservation: = 1.0
• Relationship preservation: = 1.0
• Graph structure: = 1.0
• No critical relationship losses

---

Edge Cases

Abstraction vs Enumeration: When compressed document uses high-level constraint statements (e.g., "handlers are mutually exclusive") instead of explicit pairwise enumerations, validation may score 0.85-0.94. System will automatically iterate to restore explicit relationships, as abstraction creates interpretation vulnerabilities (see /compare-docs § Score Interpretation).

Score Plateau: If multiple iterations needed but score plateaus (no improvement after 2 attempts, e.g., v1=0.87, v2=0.88, v3=0.89), compression may be hitting fundamental limits. After 3 attempts below 1.0, report best version to user and explain compression challenges encountered.

Multiple Iterations: Each iteration should show improvement. Monitor progression toward 1.0 threshold.

Large Documents: For documents >10KB, consider breaking into logical sections and compressing separately to improve iteration efficiency.

---

Example Usage

/shrink-doc /workspace/main/.claude/commands/example-command.md

Expected flow:

1. Validate document type ✅
2. Save original to /tmp/original-example-command.md (baseline) ✅
3. Invoke compression agent
4. Save to /tmp/compressed-example-command-v1.md (version 1) ✅
5. Run /compare-docs /tmp/original-example-command.md /tmp/compressed-example-command-v1.md
6. Score 1.0 → Approve v1 and overwrite original ✅
7. Cleanup: Remove /tmp/compressed-example-command-v*.md and /tmp/original-example-command.md ✅

If iteration needed:

• v1 score < 1.0 → Save v2, validate against original
• v2 score < 1.0 → Save v3, validate against original
• v3 score = 1.0 → Approve v3, cleanup v1/v1/v3 and original
• v3 score < 1.0 (after max iterations) → Report to user with best version