Knowledge Capture

EXTRACT INSIGHT FROM EVERY MEANINGFUL INTERACTION

AFTER completing any meaningful task:

1. REFLECT: What succeeded? What failed? What was unexpected?
2. DISTILL: What generalizable pattern or insight emerges?
3. DEDUPLICATE: Is this already recorded? Does it contradict something stored?
4. PERSIST: Write it to the appropriate memory file with date and context
5. PRUNE: Remove any prior entries that newer evidence invalidates

Omit any step = insight permanently lost

digraph capture_lifecycle {
    rankdir=TB;
    node [shape=box style=filled];

    task [label="Meaningful Task\nCompleted" fillcolor=lightyellow shape=doublecircle];

    reflect [label="REFLECT\nWhat occurred?\nWhat surprised me?" fillcolor="#ccccff"];
    distill [label="DISTILL\nAbstract the insight\nfrom the specifics" fillcolor="#ccccff"];
    exists [label="Already\nrecorded?" shape=diamond fillcolor="#fff3e0"];
    conflicts [label="Contradicts\nan existing entry?" shape=diamond fillcolor="#fff3e0"];
    persist [label="PERSIST\nSave to memory\nwith date + context" fillcolor="#ccffcc"];
    prune [label="PRUNE\nRemove outdated\nentry" fillcolor="#ffcccc"];
    cluster [label="CLUSTER\n3+ related insights?\nForm a conviction" fillcolor="#ccffcc"];
    promote [label="PROMOTE\nHigh-confidence conviction\n-> CLAUDE.md rule" fillcolor="#e8f5e9"];
    skip [label="Skip\n(already known)" fillcolor="#eeeeee"];

    task -> reflect;
    reflect -> distill;
    distill -> exists;
    exists -> skip [label="yes, identical"];
    exists -> conflicts [label="no"];
    conflicts -> prune [label="yes"];
    prune -> persist;
    conflicts -> persist [label="no"];
    persist -> cluster;
    cluster -> promote [label="3+ confirmations"];
    cluster -> task [label="await further\nevidence" style=dashed];
}

Sample entry:
  Date: 2025-04-10
  Context: Built retry logic for third-party webhook delivery
  Insight: Exponential backoff with random jitter eliminated thundering-herd spikes
  Confidence: medium (validated once)

Sample entry:
  Date: 2025-04-12
  Context: Logging middleware silently swallowed request bodies after refactor
  Insight: Any change to middleware ordering demands a full integration test pass -- blast radius is total
  Confidence: high (validated by production incident)

Sample entry:
  Date: 2025-04-13
  Context: User corrected my naming approach
  Insight: User requires camelCase for variables, PascalCase for types, and no abbreviations anywhere
  Confidence: high (direct correction)

Sample entry:
  Date: 2025-04-14
  Context: Spent 15 minutes searching for runtime config
  Insight: All runtime configuration lives in src/config/runtime.ts, not in .env files
  Confidence: high (verified in source)

### [Concise title]
- **Date:** YYYY-MM-DD
- **Context:** What was happening when this was discovered
- **Insight:** The generalized takeaway
- **Confidence:** low / medium / high
- **Confirmations:** Number of times this has been validated

Insight 1: "This project validates forms with zod" (medium confidence)
Insight 2: "API route handlers also validate payloads with zod" (medium confidence)
Insight 3: "User corrected me for using manual validation instead of zod" (high confidence)

    Converge into conviction

Conviction: "This project ALWAYS validates at every boundary using zod"
Confidence: high (confirmed across 3 interactions)

Conviction: "This project always validates with zod"
  -> Confirmed 3+ times
  -> Propose to user: "I have observed that this project consistently
    uses zod for validation. Should I codify this as a project rule in CLAUDE.md?"
  -> User approves -> add to CLAUDE.md