Build Insights Logger

Overview

Maintain a running log of meaningful insights, discoveries, and decisions made during coding sessions. Capture non-trivial learnings about requirements, edge cases, design considerations, implementation details, and coding patterns that emerge during development.

Target outcome: Preserve institutional knowledge and track the evolution of the codebase by logging insights to session files in .claude/insights/, then selectively transferring valuable learnings to CLAUDE.md.

When to Use This Skill

Activate automatically when:

• •Working on complex implementations with non-trivial design decisions
• •Discovering edge cases or unexpected behaviors
• •Making architectural or performance trade-offs
• •Implementing security-sensitive features
• •Building features where institutional knowledge matters

Do not activate for:

• •Simple bug fixes or trivial changes
• •Routine refactoring without architectural impact
• •Syntax corrections or typos

File Structure & Session Management

Directory Structure

.claude/
└── insights/
    ├── session-YYYY-MM-DD-HHMMSS.md (current session)
    └── archive/
        └── session-YYYY-MM-DD-HHMMSS.md (archived sessions)

Session File Naming

• •Current session: session-YYYY-MM-DD-HHMMSS.md
• •Format: Use timestamp in YYYY-MM-DD-HHMMSS format
• •Location: .claude/insights/ for active sessions
• •Archive location: .claude/insights/archive/ for completed sessions

Session Creation

• •Create new session file when first insight is logged in a new Claude Code session
• •One file per Claude Code session
• •Each session file is independent - no cross-session merging

Session File Format

Each session file contains insights in markdown format with this structure:

# Insights Session: YYYY-MM-DD HH:MM:SS

### [Category]: [Brief Title]
Files: `path/to/file.ts`, `another/file.ts`
Tags: #tag1 #tag2 #tag3
YYYY-MM-DD HH:MM:SS

[Clear, concise description of the insight]

[Optional: Brief code snippet if essential - max 3-5 lines]

---

### [Next insight...]

Logging Insights Workflow

When to Log Insights

Automatic logging triggers (Claude decides these are insight-worthy):

• •Discovery of non-trivial edge cases
• •New requirements emerging during implementation
• •Design decisions and their rationale
• •Performance considerations or optimizations
• •Security implications discovered
• •Dependency choices and trade-offs
• •Architectural patterns adopted
• •Testing strategies implemented
• •Error handling approaches
• •API design decisions
• •State management patterns
• •Data validation rules

Explicit user requests:

• •User says "log this insight", "remember this", or "capture this learning"
• •User asks to note specific discoveries
• •User highlights something for future reference

What NOT to Log

• •Trivial or obvious details (e.g., "created a new file")
• •Standard boilerplate code
• •Common language features
• •Syntax corrections or typos
• •Routine refactoring without architectural impact
• •Self-evident code comments

Logging Process

Step 1: Identify the insight

• •Evaluate whether the discovery/decision meets insight criteria
• •When in doubt, log it (user can filter during review)

Step 2: Create or open session file

• •If no session file exists for current session, create .claude/insights/session-YYYY-MM-DD-HHMMSS.md
• •If session file exists, open it for appending

Step 3: Format the insight Use this template:

### [Category]: [Brief Title]
Files: `path/to/file.ts`, `another/file.ts`
Tags: #tag1 #tag2 #tag3
YYYY-MM-DD HH:MM:SS

[Clear, concise description of the insight]

[Optional: Brief code snippet if essential - max 3-5 lines]

Category examples:

• •Architecture, Edge Cases, Performance, Testing, Security
• •Dependencies, Patterns, API Design, State Management
• •Error Handling, Data Flow, Validation

Tag guidelines:

• •Use lowercase with hyphens: #error-handling, #api-design
• •2-4 tags per insight
• •Common tags: #performance, #security, #edge-cases, #patterns, #testing, #api, #architecture

Description guidelines:

• •Clear and concise: Get to the point quickly
• •Explain WHY: Why is this valuable? What problem does it solve?
• •Context: What led to this discovery?
• •Action taken: What decision was made?
• •1-3 paragraphs maximum

Code snippet rules (optional):

• •Only include if essential to understanding
• •Maximum 3-5 lines
• •Add comments to highlight key points
• •Label "good" vs "bad" when comparing approaches
• •Prefer conceptual explanation over code

Step 4: Append to session file

• •Add insight to the end of the session file
• •Separate insights with --- divider

Step 5: Notify user

• •Show brief notification: 📝 Logged insight about [topic]
• •Keep it one line - don't show full insight content
• •Example: 📝 Logged insight about null handling in API responses

Logging Frequency

• •Add insights progressively as discovered
• •Don't wait until end of session
• •Multiple insights per session is expected and encouraged

Review & Selection Workflow

Initiating Review

• •User-initiated only: User asks "review insights", "show me what we learned", "summarize insights"
• •No automatic suggestions: Do not proactively suggest reviewing

Review Process

Step 1: Consolidation

• •Read current session insights file from .claude/insights/session-*.md
• •Identify related or redundant insights
• •Consolidate similar insights into cohesive entries
• •Refine wording for clarity

Step 2: Present insights Present in this format:

Based on this session, here are the key insights captured:

**[Category Group]**

1/ Insight: [Brief title]
   Files: [file paths]
   Explanation: [Why this matters and what was learned]

2/ Insight: [Brief title]
   Files: [file paths]
   Explanation: [Why this matters and what was learned]

**[Another Category Group]**

3/ Insight: [Brief title]
   Files: [file paths]
   Explanation: [Why this matters and what was learned]

Which insights would you like to add to CLAUDE.md? Reply with numbers (e.g., "1, 3" or "all").

Presentation guidelines:

• •Number each insight (1/, 2/, 3/, etc.)
• •Group by category when helpful
• •Include brief explanation of value for each
• •Keep explanations concise (1-2 sentences)

Step 3: User selection

• •User responds with numbers: "1, 3" or "1,2,3" or "all" or "none"
• •Parse user's selection

Step 4: Add to CLAUDE.md

• •Read existing CLAUDE.md (or create if doesn't exist)
• •Add selected insights under appropriate section
• •Format appropriately for CLAUDE.md context
• •Create new section if needed (e.g., "## Insights & Learnings")
• •Confirm what was added to user

Step 5: Archive session file

• •After adding insights to CLAUDE.md, move session file to archive
• •Move from .claude/insights/session-*.md to .claude/insights/archive/session-*.md
• •Create archive directory if it doesn't exist
• •Confirm archiving to user

No Insights Scenario

If user asks to review and no insights were logged:

• •Respond: "No insights were captured in this session yet."
• •Don't create empty session files

Multiple Review Requests

• •User can request review multiple times per session
• •Show all insights logged so far
• •If some were previously added to CLAUDE.md, indicate which ones

CLAUDE.md Doesn't Exist

• •If CLAUDE.md doesn't exist, create it when adding insights
• •Use standard structure with appropriate sections
• •Add insights under "## Insights & Learnings" section

Archiving & Cleanup

Automatic Archiving

• •Trigger: After user selects insights and they're added to CLAUDE.md
• •Action: Move session file from .claude/insights/ to .claude/insights/archive/
• •Naming: Keep original filename (e.g., session-2025-11-17-143022.md)
• •Directory creation: Create .claude/insights/archive/ if it doesn't exist

Manual Deletion Option

User can request deletion instead of archiving:

• •Trigger phrases: "delete the insights log", "clear insights instead of archiving", "remove insights file"
• •Confirmation: Ask for confirmation before deleting
• •Action: Delete the session file completely instead of archiving

Cleanup Commands

• •"archive current session" - move to archive
• •"delete current session" - delete completely (with confirmation)
• •"clean up old archives" - user specifies which archived files to remove

Quality Guidelines

Insight Quality Criteria

1. •Non-trivial: Adds genuine value to understanding the codebase
2. •Actionable: Contains information useful for future development
3. •Specific: Tied to concrete decisions or discoveries, not generic advice
4. •Contextual: Explains why this matters for this specific project

When in Doubt

• •Better to log: If uncertain whether something is insight-worthy, log it
• •User can filter: During review, user decides what's valuable for CLAUDE.md
• •Better too many than too few: Session log is temporary; missing insights are lost

Writing Style

• •Concise: Shorter entries are better
• •Clear: Use plain language, avoid jargon unless necessary
• •Focused: One insight per entry, don't combine unrelated learnings
• •Practical: Focus on practical implications, not theoretical concepts

Category Selection

• •Choose specific, descriptive categories
• •Create new categories when existing ones don't fit
• •Avoid generic categories like "General" or "Miscellaneous"
• •Categories should help organize related insights

Tag Selection

• •Use 2-4 tags per insight
• •Tags should aid searchability and filtering
• •Use consistent tag names (check existing tags in file first)
• •Prefer specific tags over broad ones

Edge Cases & Special Scenarios

Session File Already Exists

• •If timestamp collision (unlikely), append a letter: session-2025-11-17-143022-a.md
• •Log warning about timestamp collision

Archive Directory Doesn't Exist

• •Create .claude/insights/archive/ directory when first archiving
• •Don't error if it doesn't exist

Empty Session

• •Don't create session file until first insight is logged
• •If no insights logged, no file created

Long Sessions with Many Insights

• •No limit on insights per session
• •File can grow as large as needed
• •Consolidate during review to prevent overwhelming user

Example Insight Entry

### Edge Case: Null handling in API responses
Files: `api/users.ts`, `types/user.ts`
Tags: #api #edge-cases #error-handling
2025-11-17 14:30:22

Discovered that third-party user API can return null for email field even though documentation states it's required. Added validation layer with fallback to 'no-email@placeholder.com' for system processes to prevent downstream crashes.

// Good approach
const email = userData.email ?? 'no-email@placeholder.com';

// Avoid - will crash downstream
const email = userData.email; // assumes always present