Knowledge Bank Lookup

What's New

Latest: v2.4.0 - Structure refactoring with improved clarity and terminology. See CHANGELOG.md for details.

Invocation

Automatic (Recommended)

This skill triggers automatically when Claude detects patterns listed in Trigger Detection. No manual invocation needed.

Manual Invocation

• Slash command:

  /second-brain:knowledge-bank-lookup

• Skill tool:

  Skill({ skill: "second-brain:knowledge-bank-lookup" })

Visibility Settings

user-invocable

true

context

fork

agent

Explore

See references/examples.md for detailed integration examples.

Overview

This skill enables efficient lookup of service documentation, architectural patterns, best practices, and reflections from the knowledge bank by delegating research to specialized subagents. Rather than consuming main agent context with large documentation reads, subagents perform deep analysis and return only distilled, actionable insights.

Key Benefits:

• Context Efficiency: 69-94% context reduction per lookup
• Reflections-First: Learn from past mistakes before consulting documentation
• WikiLink Following: DFS traversal of interconnected docs for complete coverage
• Frontmatter Filtering: Property-based document discovery
• Structured Insights: JSON responses with reflection_insights, patterns, linked_concepts, gotchas
• Automatic Activation: Triggers on service mentions and investigation keywords

Configuration

Knowledge bank path is dynamically resolved via common utilities.

Setup:

skills/common/setup_kb_path.sh --configure

Verify:

skills/common/setup_kb_path.sh --show

Usage in Scripts:

source skills/common/get_kb_path.sh && KB_PATH=$(get_kb_path)

See

skills/common/README.md

Trigger Detection

Automatic Triggers

Automatically invoke knowledge bank lookup when detecting:

1. Service Mentions: [project-a], [project-b-server], [project-b], [project-c], Claude Code, CC, ClaudeCode, Migration
2. Investigation Requests: "investigate:", "analyze:", "create investigation plan:", "understand X"
3. Component References: filter, cache, LiveConfig, plugin, EnrichmentGraph, creative, DLQ, hook, subagent, build-interceptor, build-executor
4. Best Practice Queries: "how should I", "what's the pattern for", "best practice"
5. Implementation Planning: "implement", "refactor", "migrate"
6. Documentation Requests: "recap the session", "document this"
7. Process Learning: "how did we handle X before", "past lessons on", "what went wrong with"

Lookup Type Selection

Choose lookup type based on trigger context:

Knowledge Bank Overview

Base Path: Dynamically resolved via common utilities (see Configuration)

Total: 172 markdown files across 4 projects ([project-a], [project-b], CC, [project-c])

Key Directories:

• projects/{service}/

  - Service-specific documentation (concepts, components, best-practices)

• _index/

  - Maps of Content (MOCs) for efficient navigation

• reflections/

  - Process reflections (⚠️ CHECK FIRST before technical docs)

• manual/

  - Documentation and integration manuals

• rules/

  - Cross-project process rules

See references/knowledge-bank-structure.md for detailed structure.

Lookup Workflows

All workflows follow this pattern:

1. Step 0: Check reflections first (learn from past mistakes)
2. Step 1: Read service MOC (Map of Content)
3. Steps 2-3: Identify and read relevant documents
4. Step 4: Follow WikiLinks for connected knowledge
5. Step 5: Synthesize with reflection insights and linked concepts

Quick Lookup

When: Service mention, simple component reference

Workflow: Check 3-5 recent reflections → Read MOC → 2-3 docs → 1-hop WikiLinks (2-3 additional docs)

Invocation: See Quick Lookup Template

Standard Lookup

When: Investigation mode, implementation planning, best practice queries

Workflow: Search reflections for topic → Read MOC → 5-7 docs → 1-2 hop WikiLinks (5-7 additional docs)

Invocation: See Standard Lookup Template

Deep Lookup

When: Major refactoring, architectural decisions, cross-service analysis

Workflow: Comprehensive reflection analysis → All MOCs → 10+ docs → Full DFS (up to 20 docs, 3 hops)

Invocation: See Deep Lookup Template

CC (Claude Code) Lookup

When: User mentions Claude Code, CC, hooks, subagents, AI agent patterns

Note: No CC MOC exists yet; navigate directly to

/knowledge-bank/projects/cc/

Workflow: Check CC-related reflections → Navigate to project files → Synthesize meta-pattern insights

Navigation Strategy

Index or MOC-First: Start with the best available navigation entry point

• _meta/index.md

  : Auto-generated catalog of all KB documents — always available, covers every project
• Service MOCs in

  _index/

  : Human-curated, deeper context — available for [project-a] and [project-b]
• For projects without MOCs (CC, [project-c]): use

  _meta/index.md

  to find relevant documents
• MOCs achieve 94% context reduction vs reading all documents; index achieves similar reduction with broader coverage

Reflections-First: Check

/reflections/

• Learn from documented failures
• Apply proven approaches
• Understand workflow friction points

Advanced Features

WikiLink Following (v2.2.0+)

Documents are interconnected using Obsidian WikiLinks (

[[Document Name]]

Key Concepts:

• Hop count: Distance from primary documents (1-3 hops depending on lookup type)
• Link prioritization: Scored by keyword relevance (+10 exact match, +5 pattern/principle)
• Cycle prevention: Each document visited once per traversal

See references/wikilink-traversal.md for complete details.

Frontmatter-Based Retrieval (v2.3.0+)

Documents use LLM-optimized frontmatter properties (

type

status

complexity

relevance-to

Key Concepts:

• Property filtering: Filter by type, status, complexity before reading
• Graph traversal: Follow

  related-concepts

  ,

  related-components

  properties
• Version awareness: Track

  superseded-by

  chains to find current docs

See references/frontmatter-retrieval.md for complete details.

Progressive Refinement

For follow-up queries, reference previous lookup context so subagent can reuse cached data:

• Subagent preserves its own context
• No need to re-read MOC
• Main agent context stays clean

See references/optimization-techniques.md for details.

Subagent Communication

Request Structure (Main → Subagent)

Include in subagent prompts:

1. Role: "You are a knowledge bank exploration agent"
2. Task: Specific lookup objective
3. Knowledge Bank Location: Full base path
4. Workflow: Step-by-step instructions (reflections-first, then MOC-first)
5. Output Format: JSON structure specification
6. Context: User intent, focus areas, current working files

Response Format (Subagent → Main)

Subagents return JSON with:

executive_summary

reflection_insights

relevant_patterns

related_concepts

linked_concepts

best_practices

cross_references

link_traversal

metadata

See references/json-schemas.md for complete schema.

Query Write-Back

After presenting lookup results, if the synthesis is high-value (cross-cutting insight, novel connection, or actionable recommendation), offer to file it as a KB document:

1. Ask the user: "This synthesis could be saved to the knowledge bank. Would you like to file it?"
2. If accepted, construct a document from the subagent's response fields:

   • executive_summary

     → Overview section

   • relevant_patterns

     → Patterns section

   • best_practices

     → Best Practices section

   • reflection_insights

     → Lessons Learned section
3. Follow the kb-ingest workflow (see

   skills/kb-ingest/SKILL.md

   ):
   • Use existing templates from

     session-recap/references/

   • Target 5-8 WikiLinks (use

     search_cross_references.sh

     )
   • Frontmatter:

     source-type: synthesis

     ,

     query: "{original query}"

     ,

     synthesized-from: [list of source doc paths]

4. Run integration steps:

   source skills/common/generate_index.sh && generate_index "$KB_PATH"
   source skills/common/obsidian_helpers.sh && append_kb_log "$KB_PATH" "query-writeback" "kb-lookup" "Filed synthesis: [doc title]"
   

When NOT to write back: Simple lookups, single-document answers, or when the synthesis doesn't add value beyond what's already in the referenced docs.

Operation Logging

After completing a lookup, the main agent SHOULD log the query to

_meta/log.md

source skills/common/obsidian_helpers.sh
append_kb_log "$KB_PATH" "query" "kb-lookup" "[lookup-type] query for [topic] — [N] docs consulted"

This is lightweight (single line append) and enables the lint operation to track KB usage patterns.

Best Practices

Reference Documentation

• KB Schema - Unified conventions for all KB documents
• Prompt Templates - Complete subagent prompts for Quick/Standard/Deep lookups
• Integration Examples - Usage scenarios and response construction
• JSON Schemas - Response format specifications
• Knowledge Bank Structure - Directory organization and document counts
• WikiLink Traversal - DFS traversal details and utilities
• Frontmatter Retrieval - Property-based filtering and search
• Optimization Techniques - Context efficiency methods
• Session Documentation - Documentation process guidelines