shrink-doc

What this skill does

# 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**
```bash
# 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:
```bash
# 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:
```bash
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**:

```bash
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:

```bash
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)
- Maint