Knowledge Architecture

flowchart LR
    A["Capture\n\nClaude discovers\nsomething non-obvious"] --> B["Classify\n\nAssign importance tier\nquick-tip to never-forget"]
    B --> C["Store\n\nSessionEnd hook\nMERGEs into Neo4j"]
    C --> D["Retrieve\n\nNext session queries\nNeo4j for relevant knowledge"]
    D --> A
    C --> E["Maintain\n\nPeriodic pruning\nrespects tiers"]
    E --> C

    style A fill:#1e3a5f,stroke:#4a9eff,color:#e0e0e0
    style B fill:#3d3a1a,stroke:#ffa500,color:#e0e0e0
    style C fill:#1a3d2e,stroke:#50c878,color:#e0e0e0
    style D fill:#3d1a3d,stroke:#c77dff,color:#e0e0e0
    style E fill:#3d1a1a,stroke:#ff6b6b,color:#e0e0e0

flowchart TD
    A["Claude encounters\na UE API behavior"] --> B{"Was it expected?"}
    B -->|"Yes, routine"| C["Skip -- no capture"]
    B -->|"No, surprising or\nnon-obvious"| D["Record to\nknowledge queue"]
    D --> E{"How important?"}
    E -->|"Trivial"| F["quick-tip"]
    E -->|"Useful, learned through work"| G["life-experience"]
    E -->|"Took real debugging"| H["hard-won"]
    E -->|"User says: never forget"| I["never-forget"]
    F --> J["Appended to\n.claude/knowledge-queue.md"]
    G --> J
    H --> J
    I --> J
    J --> K["Session ends"]
    K --> L["Hook parses queue\nMERGEs into Neo4j"]
    L --> M["Queue cleared"]

    style C fill:#2a2a2a,stroke:#666,color:#999
    style F fill:#2a3a2a,stroke:#50c878,color:#e0e0e0
    style G fill:#1e3a5f,stroke:#4a9eff,color:#e0e0e0
    style H fill:#3d3a1a,stroke:#ffa500,color:#e0e0e0
    style I fill:#3d1a1a,stroke:#ff6b6b,color:#e0e0e0

flowchart TB
    subgraph TIERS["Importance Tiers -- Highest to Lowest Protection"]
        direction TB
        NF["never-forget\n\nIMMUNE to all pruning\nNever demoted\nUser explicitly requested"]
        HW["hard-won\n\nFlagged for human review only\nNever auto-deleted\nLearned from real failures"]
        LE["life-experience\n\nDefault tier\nOnly pruned if contradicted\nDemotion requires 2-session grace"]
        QT["quick-tip\n\nAll pruning checks apply\nDeleted after 2-session grace\nEasily re-discovered"]
    end

    NF --- HW --- LE --- QT

    style NF fill:#3d1a1a,stroke:#ff6b6b,color:#e0e0e0
    style HW fill:#3d3a1a,stroke:#ffa500,color:#e0e0e0
    style LE fill:#1e3a5f,stroke:#4a9eff,color:#e0e0e0
    style QT fill:#2a3a2a,stroke:#50c878,color:#e0e0e0
    style TIERS fill:#0d1117,stroke:#30363d,color:#e0e0e0

flowchart LR
    subgraph START["Session Start"]
        A["Startup hook fires"] --> B["Cheatsheet loads\n5 critical gotchas\npath rules, error codes"]
    end

    subgraph WORK["During Work"]
        C["User asks about\nlighting setup"] --> D["Claude queries Neo4j"]
        D --> E["get_skill_knowledge\nlighting-fundamentals"]
        D --> F["get_test_knowledge\nviewport camera"]
        E --> G["Returns relevant entries\nwith importance tier shown"]
        F --> G
        G --> H["Claude applies knowledge\navoids known pitfalls"]
    end

    B --> C

    style START fill:#0d1117,stroke:#4a9eff,color:#e0e0e0
    style WORK fill:#0d1117,stroke:#50c878,color:#e0e0e0

flowchart TD
    A["Maintenance triggered\nautomatically every 24h\nor manually via /knowledge-maintenance"] --> B["Inventory all entries\nwith importance tiers"]
    B --> C{"Check importance"}
    C -->|"never-forget"| D["IMMUNE\nSkip all checks"]
    C -->|"hard-won"| E["REVIEW ONLY\nFlag for human, never auto-delete"]
    C -->|"life-experience"| F["PARTIAL SHIELD\nOnly contradictions can drop"]
    C -->|"quick-tip"| G["NO SHIELD\nAll 6 checks apply"]
    G --> H["Contradictory?\nSelf-evident?\nUnverifiable?\nDuplicate?\nLow-value?\nUncertain?"]
    H -->|"Flagged"| I{"First time flagged?"}
    I -->|"Yes"| J["Mark for pruning\nGrace period starts"]
    I -->|"Already marked\nfrom last run"| K["Delete entry\nGrace period served"]
    H -->|"Passed all checks"| L["Keep entry\nClear any marks"]

    style D fill:#2d5a27,stroke:#50c878,color:#e0e0e0
    style E fill:#3d3a1a,stroke:#ffa500,color:#e0e0e0
    style K fill:#5a1a1a,stroke:#ff6b6b,color:#e0e0e0
    style J fill:#3d3a1a,stroke:#ffa500,color:#e0e0e0
    style L fill:#2d5a27,stroke:#50c878,color:#e0e0e0

flowchart TB
    subgraph LAYER1["Layer 1: Slim Stubs"]
        A["SKILL.md\n60-150 lines each\nIdentity + execution steps"]
    end

    subgraph LAYER2["Layer 2: Graph Knowledge"]
        B["1,400+ SkillKnowledge nodes\nin Neo4j\nPatterns, anti-patterns,\nqueries, escalation rules"]
    end

    subgraph LAYER3["Layer 3: MCP Query Interface"]
        C["get_skill_knowledge tool\nSearch by skill, topic,\nor natural language"]
    end

    A -->|"Claude triggers\na skill"| C
    C -->|"Queries Neo4j\nfor concepts"| B
    B -->|"Returns self-contained\nconcept nodes"| C

    style LAYER1 fill:#0d1117,stroke:#4a9eff,color:#e0e0e0
    style LAYER2 fill:#0d1117,stroke:#50c878,color:#e0e0e0
    style LAYER3 fill:#0d1117,stroke:#c77dff,color:#e0e0e0