# Insight Extraction

> Extract actionable insights from completed coding sessions. Use when a session completes to capture learnings for future sessions.

- Skill: `oimiragieo/insight-extraction` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add oimiragieo/insight-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/insight-extraction/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/oimiragieo/insight-extraction

---


# Insight Extraction Skill

## Overview

Analyze completed coding sessions and extract structured learnings for the memory system. Insights help future sessions avoid mistakes, follow established patterns, and understand the codebase faster.

**Core principle:** Extract ACTIONABLE knowledge, not logs. Every insight should help a future session do something better.

## When to Use

**Always:**

- After completing a coding task
- After fixing bugs
- After discovering new patterns
- After failed attempts (especially valuable)

**Exceptions:**

- Trivial changes with no learnings
- Documentation-only changes

## The Iron Law

```
NO SESSION END WITHOUT INSIGHT EXTRACTION FOR NON-TRIVIAL WORK
```

Non-trivial sessions should capture learnings before context is lost.

## Input Required

To extract insights, you need:

1. **Git diff** - What files changed and how
2. **Task description** - What was being implemented
3. **Attempt history** - Previous tries (if any), what approaches were used
4. **Session outcome** - Success or failure

## Workflow

### Phase 1: Gather Session Data

```bash
# Get the diff of changes
git diff HEAD~1 --stat
git diff HEAD~1

# Get commit message
git log -1 --pretty=format:"%s%n%n%b"

# Get list of modified files
git diff HEAD~1 --name-only
```

### Phase 2: Analyze File Insights

For each modified file, extract:

- **Purpose**: What role does this file play?
- **Changes made**: What was the modification? Focus on the "why" not just "what"
- **Patterns used**: What coding patterns were applied?
- **Gotchas**: Any file-specific traps?

**Good example:**

```json
{
  "path": "src/stores/terminal-store.ts",
  "purpose": "Zustand store managing terminal session state with immer middleware",
  "changes_made": "Added setAssociatedTask action to link terminals with tasks",
  "patterns_used": ["Zustand action pattern", "immer state mutation"],
  "gotchas": ["State changes must go through actions, not direct mutation"]
}
```

**Bad example (too vague):**

```json
{
  "path": "src/stores/terminal-store.ts",
  "purpose": "A store file",
  "changes_made": "Added some code",
  "patterns_used": [],
  "gotchas": []
}
```

### Phase 3: Extract Patterns

Only extract patterns that are **reusable**:

- Must apply to more than just this one case
- Include where/when to apply the pattern
- Reference a concrete example in the codebase

**Good example:**

```json
{
  "pattern": "Use e.stopPropagation() on interactive elements inside containers with onClick handlers",
  "applies_to": "Any clickable element nested inside a parent with click handling",
  "example": "Terminal.tsx header - dropdown needs stopPropagation to prevent focus stealing"
}
```

### Phase 4: Document Gotchas

Must be **specific** and **actionable**:

- Include what triggers the problem
- Include how to solve or prevent it
- Avoid generic advice ("be careful with X")

**Good example:**

```json
{
  "gotcha": "Terminal header onClick steals focus from child interactive elements",
  "trigger": "Adding buttons/dropdowns to Terminal header without stopPropagation",
  "solution": "Call e.stopPropagation() in onClick handlers of child elements"
}
```

### Phase 5: Document Approach Outcome

Capture the learning from success or failure:

- If **succeeded**: What made this approach work? What was key?
- If **failed**: Why did it fail? What would have worked instead?
- **Alternatives tried**: What other approaches were attempted?

This helps future sessions learn from past attempts.

### Phase 6: Generate Recommendations

Specific, actionable advice for future work:

- Must be implementable by a future session
- Should be specific to this codebase, not generic
- Focus on what's next or what to watch out for

**Good:** "When adding more controls to Terminal header, follow the dropdown pattern in this session - use stopPropagation and position relative to header"

**Bad:** "Write good code" or "Test thoroughly"

### Phase 7: Output Structured Insights

Create the structured insight output:

```markdown
# Session Insights: [Task Name]

## Date

[timestamp]

## Task

[Description of what was being implemented]

## Outcome

[SUCCESS/FAILURE]

## File Insights

### [file-path]

- **Purpose**: [what this file does]
- **Changes**: [what was changed and why]
- **Patterns**: [patterns used]
- **Gotchas**: [things to watch out for]

## Patterns Discovered

### [Pattern Name]

- **Pattern**: [description]
- **Applies to**: [when to use]
- **Example**: [file or code reference]

## Gotchas Discovered

### [Gotcha Name]

- **Issue**: [what to avoid]
- **Trigger**: [what causes it]
- **Solution**: [how to handle]

## Approach Analysis

### What Worked

[Description of successful approach]

### What Failed (if applicable)

[Description of failed approaches and why]

### Alternatives Tried

[List of other approaches attempted]

## Recommendations for Future Sessions

1. [Specific recommendation 1]
2. [Specific recommendation 2]
```

Save to `.claude/context/memory/learnings.md` (append).

## Handling Edge Cases

### Empty or Minimal Diff

If the diff is very small or empty:

- Still extract file purposes if you can infer them
- Note that the session made minimal changes
- Focus on recommendations for next steps

### Failed Session

If the session failed:

- Focus on **why it failed** - this is the most valuable insight
- Extract what was learned from the failure
- Recommendations should address how to succeed next time

### Multiple Files Changed

- Prioritize the most important 3-5 files
- Skip boilerplate changes (package-lock.json, etc.)
- Focus on files central to the feature

## Verification Checklist

Before completing insight extraction:

- [ ] Git diff analyzed
- [ ] File insights extracted for key files
- [ ] Reusable patterns documented
- [ ] Gotchas documented with triggers and solutions
- [ ] Approach outcome documented
- [ ] Recommendations are specific and actionable
- [ ] Insights saved to memory file

## Common Mistakes

### Too Vague

**Why it's wrong:** "Fixed the bug" helps no one.

**Do this instead:** "Fixed race condition in useEffect by adding cleanup function. Pattern: always return cleanup from async effects."

### Generic Advice

**Why it's wrong:** "Test your code" is not actionable.

**Do this instead:** "Run `npm test src/stores` after changing store logic - the tests catch state management bugs."

### Missing Context

**Why it's wrong:** Future sessions won't understand why.

**Do this instead:** Include file paths, function names, and specific scenarios.

## Integration with Other Skills

This skill works well with:

- **session-handoff**: Use insights in handoff documents
- **summarize-changes**: Complement change summaries with insights
- **debugging**: Extract insights from debugging sessions

## Iron Laws

1. **ALWAYS** extract insights immediately after task completion — delayed extraction loses context; the "what" can be reconstructed but the "why" evaporates within the session.
2. **NEVER** record what was done — only record what was learned; activity logs belong in task metadata, not in the learning system.
3. **ALWAYS** check for duplicate insights before writing — appending a near-duplicate insight pollutes the memory index and degrades future retrieval quality.
4. **NEVER** write vague insights like "X is good" without concrete context, file path, or example — vague insights are unfindable and unhelpful to future sessions.
5. **ALWAYS** tag insights with domain category (`[CODE]`, `[WORKFLOW]`, `[SECURITY]`, etc.) — untagged insights are effectively invisible to agents searching by domain.

## Anti-Patterns

| Anti-Pattern                                                 | Why It Fails                                                                     | Correct Approach                                                                                     |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Recording activity ("implemented auth") instead of learnings | Agents can reconstruct history from git; they cannot reconstruct tacit knowledge | Record "why" and "gotcha": "Fiber's CSRF middleware must be before route registration, not after"    |
| Skipping deduplication check                                 | Duplicate entries inflate memory size and confuse retrieval                      | `grep -i "keyword" learnings.md` before appending; update existing entry if found                    |
| Vague insights without file/function context                 | Future sessions can't locate or apply the insight                                | Include concrete path: "In `.claude/hooks/routing/routing-guard.cjs` line 47: exit 0 on parse error" |
| Extracting only at session end                               | Long sessions lose early context; critical gotchas forgotten                     | Extract after each significant task completion, not just at session boundary                         |
| Storing insights only in task metadata                       | Task metadata is not read by future sessions or agents                           | Always write to `.claude/context/memory/learnings.md` with tagged format                             |

## Memory Protocol

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**

- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.