distilling-plan-learnings

---

name: distilling-plan-learnings description: Extracts decisions, rejected alternatives, and patterns from recent plans into a persistent learnings document. Use after completing a plan or sprint. compatibility: Designed for Claude Code metadata: allowed-tools: Read, Grep, Glob, Edit, Write argument-hint: [time-range] [output-path] context: fork stability: development

Plan-to-Learnings Distiller

Target: $ARGUMENTS

Extracts structured learnings from Claude Code plan files. Distills decisions made, alternatives rejected, and patterns discovered into a persistent document that compounds project knowledge over time.

Arguments

Position	Name	Required	Default	Description
1	time-range	no	7d	E.g. 7d, 30d, this-week. Filter plans by modification time.
2	output-path	no	docs/learnings/from-plans.md	Where to write/append output.

Examples:

/distilling-plan-learnings                          # Last 7 days → docs/learnings/from-plans.md
/distilling-plan-learnings 30d                      # Last 30 days
/distilling-plan-learnings 7d ./my-learnings.md     # Custom output path

Data Source

~/.claude/
├── plans/*.md                       # Plan mode files (filtered by mtime)

When to Use

• After completing a plan or sprint — capture what was learned
• At week/sprint boundaries — accumulate decision history
• Before starting a new plan — review past decisions and patterns

Do Not Use

• For real-time plan editing (use plan mode directly)
• For cross-project synthesis (use /synthesizing-cc-bigpicture)
• For session-level context (use session-memory)

Workflow

1. Parse arguments — Apply defaults per Arguments table. Resolve output path. Create parent directories if needed.

2. Glob plans — Glob ~/.claude/plans/*.md. Filter by modification time against the time-range argument. Sort by mtime descending (newest first). If no plans match, report "No plans found in time range" and stop.

3. Read each plan — Read matching plan files sequentially. Extract content sections, noting plan title and date.

4. Extract learnings into three categories:

   • Decisions made — Choices that were committed to. Look for: selected approaches, accepted trade-offs, finalized designs, chosen tools/patterns.
   • Alternatives rejected — Options considered but not chosen. Look for: crossed-out items, "decided against", "considered but", trade-off discussions, pros/cons where one side won.
   • Patterns discovered — Recurring themes or insights. Look for: repeated blockers, successful strategies, workflow improvements, reusable solutions.

5. Format output — Structure with date headers per plan. Group by category within each plan section.

6. Write or append — If output file exists, append new entries below existing content with a separator. If new, write with header.

Output Format

# Learnings from Plans

## <Plan Title> — <YYYY-MM-DD>

### Decisions Made
- <decision>: <rationale>

### Alternatives Rejected
- <alternative>: <why rejected>

### Patterns Discovered
- <pattern>: <context and implication>

---

Common Pitfalls

• Inventing learnings: Only extract what is explicitly stated or strongly implied in plan text. Do not infer decisions that aren't there.
• Duplicating entries: When appending, check existing content for duplicates before adding.
• Over-extraction: Prefer fewer, high-quality entries over exhaustive lists. Each entry should be actionable or informative.

Quality Check

• Correct > Complete > Minimal (ACE-FCA)
• Every entry traces to a specific plan file
• Decisions include rationale, not just the choice
• Alternatives include why they were rejected
• Patterns are genuinely recurring (seen in 2+ plans) or significant