insights-apply

Extract CLAUDE.md improvement suggestions from the /insights report and apply them through the sync pipeline. Targets the global CLAUDE.md only (insights are cross-project).

When to Use

• User says "apply insights", "update rules from insights"
• After running /insights and seeing claude_md_additions suggestions
• User wants to incorporate session learnings into CLAUDE.md
• Insights data exists at ~/.claude/usage-data/

Prerequisites

• Insights report must exist (~/.claude/usage-data/report.html or facets data)
• Global CLAUDE.md at ~/.claude/CLAUDE.md
• Python3 available (for sync pipeline)

Insights Apply Pipeline

Execute these steps in order.

Step 1: Parse Insights Report

Locate and parse the insights data:

# Check for insights data
if [ -f ~/.claude/usage-data/report.html ]; then
    echo "Found insights report"
elif [ -d ~/.claude/usage-data/facets/ ]; then
    echo "Found facets data"
else
    echo "No insights data found. Run /insights first."
    exit 1
fi

Extract the claude_md_additions array from the report. These are structured suggestions with:

• title: Section heading for CLAUDE.md
• content: The actual rules/guidance to add
• source: Which sessions/patterns generated this suggestion
• priority: How impactful the suggestion is (high/medium/low)

Step 2: Present Suggestions

Show each suggestion with context for user review:

┌───────────────────────────────────────────────────────────────┐
│ INSIGHTS SUGGESTIONS (N found)                                │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│ Suggestion 1/N: <title>                                       │
│ Source: <N sessions with this pattern>                         │
│ Priority: <high|medium|low>                                   │
│                                                               │
│ Proposed CLAUDE.md addition:                                  │
│ ┌─────────────────────────────────────────────────────────┐   │
│ │ ## <Title>                                               │   │
│ │ - <rule 1>                                               │   │
│ │ - <rule 2>                                               │   │
│ │ - <rule 3>                                               │   │
│ └─────────────────────────────────────────────────────────┘   │
│                                                               │
└───────────────────────────────────────────────────────────────┘

For each suggestion, ask the user:

{
  "questions": [{
    "question": "Apply this suggestion to global CLAUDE.md?",
    "header": "Apply",
    "multiSelect": false,
    "options": [
      {
        "label": "Apply (Recommended)",
        "description": "Add this section to ~/.claude/CLAUDE.md"
      },
      {
        "label": "Skip",
        "description": "Don't add this suggestion"
      },
      {
        "label": "Edit first",
        "description": "Let me modify the content before applying"
      }
    ]
  }]
}

Step 3: Apply via Sync Pipeline

For each approved suggestion, use the CLAUDE.md sync pipeline:

# Apply using the sync pipeline
python3 utils/claude_md_sync.py ~/.claude/CLAUDE.md --add-section "<title>" "<content>"

If sync pipeline is not available, fall back to direct append:

# Fallback: Direct append to CLAUDE.md
echo "" >> ~/.claude/CLAUDE.md
echo "## <Title>" >> ~/.claude/CLAUDE.md
echo "" >> ~/.claude/CLAUDE.md
echo "<content>" >> ~/.claude/CLAUDE.md

Step 4: Budget Check

After applying all approved suggestions, verify the CLAUDE.md stays within budget:

# Run budget enforcer
python3 utils/claude_md_optimizer.py ~/.claude/CLAUDE.md --check

# If over budget, the optimizer will:
# 1. Report which sections exceed limits
# 2. Suggest P2 content to move to detail files
# 3. Offer to auto-optimize

If the CLAUDE.md exceeds the line budget after additions:

┌───────────────────────────────────────────────────────────────┐
│ ⚠️  BUDGET WARNING                                            │
├───────────────────────────────────────────────────────────────┤
│ CLAUDE.md is now N lines (budget: 200 lines)                  │
│ Over budget by M lines                                        │
│                                                               │
│ Options:                                                      │
│   1. Run optimizer to trim P2 content                         │
│   2. Keep as-is (will be truncated at 200 lines)              │
│   3. Manually edit to reduce size                             │
└───────────────────────────────────────────────────────────────┘

Step 5: Report

Summarize what was applied:

┌───────────────────────────────────────────────────────────────┐
│ INSIGHTS APPLY REPORT                                         │
├───────────────────────────────────────────────────────────────┤
│ Suggestions found:    N                                       │
│ Applied:              M                                       │
│ Skipped:              P                                       │
│ Edited:               Q                                       │
│                                                               │
│ CLAUDE.md status:     Within budget / Over budget             │
│ File:                 ~/.claude/CLAUDE.md                     │
│                                                               │
│ Applied sections:                                             │
│   ✅ Branch Guard & Git Hooks                                  │
│   ✅ Worktree Best Practices                                   │
│   ⏭️  Release Pipeline (skipped)                               │
│   ✅ Testing Conventions (edited)                              │
└───────────────────────────────────────────────────────────────┘

Output Format

Use craft box-drawing format throughout. Show step progress:

[1/5] Parse insights ........... DONE (N suggestions found)
[2/5] Present suggestions ...... DONE (user reviewed N)
[3/5] Apply approved ........... DONE (M applied)
[4/5] Budget check ............. DONE (within budget)
[5/5] Report ................... SHOWN

Error Recovery

| Error | Recovery | |-------|----------| | No insights data | Suggest running /insights first | | CLAUDE.md not found | Suggest the docs/claude-md skill (init) | | Sync pipeline fails | Fall back to direct append | | Over budget | Offer optimizer or manual edit | | Parse error | Show raw data for manual review |

Scope

Global CLAUDE.md only. Insights are cross-project patterns, so they belong in ~/.claude/CLAUDE.md, not project-specific files.

See Also

• /insights — Generate the insights report
• docs/claude-md skill (sync) — CLAUDE.md sync pipeline
• utils/claude_md_sync.py — 4-phase sync pipeline
• utils/claude_md_optimizer.py — Budget enforcement