knowledge-bank-lookup

name	knowledge-bank-lookup
description	Delegates knowledge bank lookups to Explore subagents with reflections-first strategy that learns from past mistakes. Checks /reflections/ directory before documentation to extract documented failures to avoid and proven approaches to apply. Automatically triggers when user mentions services ([project-a], [project-b], [project-c], Claude Code), requests investigations, or queries past lessons. Returns structured, actionable insights achieving 69-94% context reduction. (project, gitignored)
user-invocable	true
context	fork
agent	Explore

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

Setting	Value	Effect
user-invocable	true	Visible in slash menu, Skill tool allowed
context	fork	Runs in isolated subagent (Explore agent)
agent	Explore	Uses Explore agent optimized for codebase research

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 for details.

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:

Type	When to Use	Context Budget	Model
Quick	Service mention, component reference	~900 lines → 300 returned	haiku
Standard	Investigation, implementation planning	~1950 lines → 600 returned	sonnet
Deep	Architectural decisions, cross-service	~7300 lines → 1500 returned	sonnet

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/ BEFORE technical documentation

• 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]]). The skill uses Depth-First Search (DFS) to traverse these connections, ensuring comprehensive coverage of related knowledge.

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) for efficient filtering without reading full content.

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:

Field	Description
executive_summary	Key findings and recommended action
reflection_insights	Past mistakes, proven approaches, workflow gotchas
relevant_patterns	Technical patterns with gotchas
related_concepts	Prerequisites and alternatives
linked_concepts	Concepts discovered through WikiLink traversal
best_practices	Reusable methodologies
cross_references	Follow-up topics
link_traversal	WikiLink traversal statistics
metadata	Analysis depth, document counts, limitations

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 for audit trail:

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

Practice	Rationale
Always check reflections first	Learn from past mistakes before technical docs
Use MOC-first navigation	94% context reduction vs reading all documents
Specify JSON output format	Ensures structured, parseable responses
Include user context	Improves relevance of findings
Choose appropriate lookup type	Don't use Deep for simple queries
Integrate insights naturally	Present as main agent knowledge, not "I looked this up"

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