distill

name: distill description: Distill session patterns into CLAUDE.md rules and project documentation

Distill Skill

The Insight

Sessions are rich with implicit knowledge — recurring corrections, repeated preferences, workflow adjustments — that evaporates when the session ends. This skill captures those patterns and crystallizes them into durable project documentation (CLAUDE.md, AGENTS.md, etc.) so future sessions start smarter.

The difference from /learner:

• learner: Extracts a single, specific technical skill from a debugging breakthrough → saves as a reusable .md skill file
• distill: Scans the ENTIRE session for behavioral patterns, preferences, and recurring adjustments → updates project documentation files (CLAUDE.md, AGENTS.md)

Why This Matters

Without distillation, the same corrections repeat session after session:

• "I told you to use Korean" — should be a CLAUDE.md rule
• "Always run tests before committing" — should be a documented convention
• "Don't touch the legacy module" — should be an AGENTS.md boundary
• "Use pnpm, not npm" — should be a build convention

The cost of NOT distilling: users waste time re-explaining preferences that should be permanent rules.

Recognition Pattern

Use /pepcode:distill when:

• A session involved multiple corrections or preference expressions
• The user repeatedly adjusted Claude's behavior during the session
• New workflow patterns or conventions emerged during development
• The user says "remember this", "always do X", "from now on", "update the rules"
• After a significant project setup or architectural decision session
• At the end of a productive session where conventions were established

Do NOT use when:

• The session was a simple one-off task with no reusable patterns
• The pattern is a technical debugging insight (use /learner instead)
• The change is temporary or experimental

The Approach

Step 1: Session Analysis

Scan the entire conversation for these signal categories:

A. Explicit Directives (highest priority)

• Direct instructions: "always", "never", "from now on", "remember to"
• Corrections: "no, do it this way", "I meant...", "not like that"
• Preferences: "I prefer", "use X instead of Y", "the convention is"

B. Implicit Patterns (medium priority)

• Repeated adjustments (user corrected the same thing 2+ times)
• Consistent choices (user always picked option A over B)
• Workflow sequences that emerged naturally

C. Architectural Decisions (captured as context)

• Technology choices made during the session
• Module boundaries established
• Naming conventions agreed upon
• Testing strategies adopted

Step 2: Categorize & Target

Map each discovered pattern to the right documentation file:

Step 3: Draft Updates

For each target file:

1. Read the current file to understand existing structure and avoid duplicates
2. Check for conflicts with existing rules — update rather than duplicate
3. Draft additions in the file's existing style and format
4. Preserve existing content — only add or refine, never remove unless explicitly asked

Rule writing guidelines:

• Be specific and actionable: "Use pnpm for package management" not "Consider using pnpm"
• Include the WHY when non-obvious: "Use UTC timestamps in logs (production servers span multiple timezones)"
• Use imperative tone consistent with existing rules
• Group related rules under meaningful headings
• Keep rules concise — one rule per line when possible

Step 4: Present & Apply

1. Show the user a summary of all discovered patterns with their proposed target files
2. Present each update as a diff-like preview so the user can approve/reject individual changes
3. Ask for confirmation before writing any files
4. Apply approved changes to the target files
5. Report what was updated with file paths and line references

Important Constraints

• Never remove existing rules unless the user explicitly asks to replace them
• Merge with existing sections rather than creating redundant new sections
• Respect file structure — follow the existing formatting, heading levels, and organization
• CLAUDE.md changes go in the project CLAUDE.md by default (not user-level ~/.claude/CLAUDE.md), unless the pattern is truly cross-project
• Cross-project patterns (e.g., language preference, general coding style) should target ~/.claude/CLAUDE.md — confirm with user first
• AGENTS.md updates should follow the existing hierarchical structure if one exists; create one using deepinit patterns if not

Example Session Patterns → Rules

Session pattern: User corrected Claude 3 times to write commit messages in Korean

# → CLAUDE.md addition:
<commit_convention>
커밋 메시지는 항상 한국어로 작성한다. 접두사 `[CP0-11]` 를 사용한다.
</commit_convention>

Session pattern: User always asked to run npm run build after version changes

# → CLAUDE.md addition:
## 빌드 규칙
버전 변경 후 반드시 `npm run build`를 실행하여 dist/ 파일에 반영한다.

Session pattern: User said "don't modify files in src/legacy/"

# → AGENTS.md addition:
## src/legacy/
- **Ownership**: Frozen — do not modify without explicit user approval
- **Reason**: Legacy code pending migration, changes may break downstream consumers

Session pattern: User repeatedly chose sonnet over opus for executor tasks

# → CLAUDE.md addition (model_routing section):
executor 작업은 기본적으로 sonnet 모델을 사용한다. opus는 아키텍처 수준 리팩토링에만 사용한다.

Related Commands

• /pepcode:learner - Extract a single technical skill from a debugging breakthrough
• /pepcode:deepinit - Initialize hierarchical AGENTS.md documentation from scratch
• /pepcode:note - Save quick notes that survive compaction (less formal than distill)