ask

## EXECUTE NOW

**Question: $ARGUMENTS**

If no question provided, ask the user what they want to know.

**Execute these steps:**

1. **Classify the question** — determine which knowledge base tier(s) to consult (see Query Classification below)
2. **Search the knowledge base** — route to appropriate tiers based on classification
3. **Read relevant claims and docs** — load 3-7 most relevant sources fully (use `mcp__qmd__multi_get` when reading multiple IDs)
4. **Check user context** — read `ops/derivation.md` if the question involves their specific system
5. **Synthesize an answer** — weave claims into a coherent, opinionated argument
6. **Cite sources** — reference specific claims and documents so the user can explore further

**START NOW.** Reference below explains routing and synthesis methodology.

---

## The Three-Tier Knowledge Base

The plugin's knowledge base has three distinct parts, each serving a different function. Effective answers often draw from multiple tiers.

### Tier 1: Research Graph (WHY)

**Location:** `${CLAUDE_PLUGIN_ROOT}/methodology/` — filter by `kind: research`
**Content:** 213 interconnected research claims grounded in cognitive science, knowledge system theory, and agent cognition research.
**Use for:** Questions about principles, trade-offs, why things work, theoretical foundations.

**What it contains:**
- Claims about how knowledge systems work (human and agent)
- Cognitive science foundations (working memory, attention, retrieval)
- Methodology comparisons (Zettelkasten vs PARA, atomic vs compound)
- Design dimensions (trade-off spectrums with poles and decision factors)
- Failure modes and anti-patterns
- Agent-specific constraints (context windows, session boundaries)

**Search strategy:** Use `mcp__qmd__deep_search` (highest quality, LLM-reranked) for conceptual questions. Use `mcp__qmd__vector_search` for semantic exploration. Use `mcp__qmd__search` for known terminology. All searches use the `methodology` collection.

### Tier 2: Guidance Docs (HOW)

**Location:** `${CLAUDE_PLUGIN_ROOT}/methodology/` — filter by `kind: guidance`
**Content:** 9 operational documents covering procedures, workflows, and implementation rationale.
**Use for:** Questions about how to do things, operational best practices, workflow mechanics.

**Documents include:**
- Schema enforcement rationale and procedures
- Pipeline philosophy and processing workflow
- MOC methodology and navigation patterns
- Maintenance patterns and condition-based triggers
- Memory architecture and session management
- Vocabulary transformation procedures
- Failure mode prevention patterns
- Multi-domain composition rules
- Onboarding and evolution decisions

**Search strategy:** `mcp__qmd__search` with keywords from the question using the `methodology` collection. To narrow to guidance docs, add `kind:guidance` to your grep filter on results.

### Tier 3: Domain Examples (WHAT IT LOOKS LIKE)

**Location:** `${CLAUDE_PLUGIN_ROOT}/methodology/` — filter by `kind: example`
**Content:** 12 domain-specific compositions showing what generated vaults look like in practice.
**Use for:** Questions about how to apply methodology to specific domains, inspiration for novel domain mapping.

**Examples include domains like:**
- Research vaults (academic literature reviews, claim extraction)
- Personal assistant vaults (life management, therapy, health wellness)
- Project management vaults (decision tracking, stakeholder context)
- Creative vaults (worldbuilding, character tracking)
- Engineering, legal, trading, student learning, relationships

**Search strategy:** Use `mcp__qmd__vector_search` across the `methodology` collection for semantic domain matching. To list all examples: `rg '^kind: example' ${CLAUDE_PLUGIN_ROOT}/methodology/`.

### Reference Documents (structured derivation context)

**Location:** `${CLAUDE_PLUGIN_ROOT}/reference/`
**Content:** Structured reference documents supporting derivation and system architecture.
**Use for:** Deep dives into specific architectural topics, cross-referencing dimension positions, understanding interaction constraints.

**Core Architecture:**
- `methodology.md` — universal principles and processing pipeline
- `components.md` — component blueprints and feature blocks
- `kernel.yaml` — the 12 non-negotiable primitives
- `three-spaces.md` — self/notes/ops architecture and boundary rules

**Configuration & Derivation:**
- `dimension-claim-map.md` — which research claims inform which dimensions
- `interaction-constraints.md` — how dimension choices create pressure on others
- `tradition-presets.md` — named points in configuration space
- `vocabulary-transforms.md` — universal-to-domain term mapping
- `derivation-validation.md` — validation tests for derived systems

**Behavioral & Quality:**
- `personality-layer.md` — personality derivation and encoding
- `conversation-patterns.md` — worked examples of full derivation paths
- `failure-modes.md` — how knowledge systems die and prevention patterns

**Lifecycle & Operations:**
- `use-case-presets.md` — preset configurations for common domains
- `session-lifecycle.md` — session rhythm, context budget, orient-work-persist
- `evolution-lifecycle.md` — seed-evolve-reseed, condition-based maintenance
- `self-space.md` — agent identity generation, self/ architecture
- `semantic-vs-keyword.md` — search modality selection guidance
- `open-questions.md` — unresolved research questions and deferred items

**Also read:** `claim-map.md` — the routing index showing which claims map to which topics. Start here when you need to find relevant claims quickly.

---

## Query Classification

Before searching, classify the user's question to determine which tier(s) to consult.

### Classification Rules

| Question Type | Signals | Primary Tier | Secondary Tier |
|--------------|---------|-------------|----------------|
| **WHY** | "why does...", "what's the reasoning...", "what's the theory behind...", "why not just..." | Research Graph |