arscontexta 0.6.0

package/skills/ask/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: ask
+description: Query the bundled research knowledge graph for methodology guidance. Routes questions through a 3-tier knowledge base — WHY (research claims), HOW (guidance docs), WHAT IT LOOKS LIKE (domain examples) — plus structured reference documents. Returns research-backed answers grounded in specific claims with practical application to the user's system. Triggers on "/ask", "/ask [question]", "why does my system...", "how should I...".
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+context: fork
+model: opus
+allowed-tools: Read, Grep, Glob, mcp__qmd__search, mcp__qmd__vsearch, mcp__qmd__query, mcp__qmd__get
+argument-hint: "[question about knowledge systems or methodology]"
+---
+
+## 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
+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__query` (highest quality, LLM-reranked) for conceptual questions. Use `mcp__qmd__vsearch` 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__vsearch` 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 | Guidance Docs |
+| **HOW** | "how do I...", "what's the workflow for...", "how should I...", "what's the process..." | Guidance Docs | Research Graph |
+| **WHAT** | "what does X look like...", "show me an example...", "how would this work for...", "what would a Y vault..." | Domain Examples | Guidance Docs |
+| **COMPARE** | "X vs Y", "what's the difference between...", "should I use X or Y...", "trade-offs between..." | Research Graph | Examples |
+| **DIAGNOSE** | "something feels wrong...", "why isn't this working...", "my system is doing X when it should..." | Guidance Docs + Reference (failure-modes.md) | Research Graph |
+| **CONFIGURE** | "what dimension...", "how should I set...", "what configuration for...", "which preset..." | Reference (dimensions, constraints) | Research Graph |
+| **EVOLVE** | "should I change...", "my system has grown...", "this doesn't fit anymore..." | Reference (evolution-lifecycle.md) | Guidance Docs |
+
+### Multi-Tier Questions
+
+Many questions require consulting multiple tiers. The classification above shows primary and secondary tiers. Always check: would the answer be stronger with evidence from another tier?
+
+**Example multi-tier routing:**
+
+Question: "Why does my system use atomic notes instead of longer documents?"
+1. **WHY tier** — search research graph for claims about atomicity, granularity, composability
+2. **Reference** — check `dimension-claim-map.md` for the granularity dimension's informing claims
+3. **User context** — check `ops/derivation.md` for their specific granularity position and reasoning
+4. **WHAT tier** — optionally pull an example showing what atomic notes look like in a similar domain
+
+Question: "How should I handle therapy session notes that are very long?"
+1. **HOW tier** — search guidance for processing workflow, chunking strategies
+2. **WHAT tier** — check examples for therapy or personal domains with similar challenges
+3. **WHY tier** — search for claims about context degradation, chunking benefits, large source handling
+
+---
+
+## Search Strategy
+
+### Step 1: Route to Claim-Map
+
+Read `${CLAUDE_PLUGIN_ROOT}/reference/claim-map.md` first. This is the routing index — it shows which topic areas are relevant to the user's question and which claims to start with. Do NOT skip this step and search blindly.
+
+### Step 2: Search the Appropriate Tier
+
+**For WHY questions (Research Graph):**
+```
+mcp__qmd__query  query="[user's question rephrased as a search]"  collection="methodology"  limit=10
+```
+Use `mcp__qmd__query` (hybrid + LLM reranking) for conceptual questions because the best connections often use different vocabulary than the question. Results will include all kinds; prioritize `kind: research` results.
+
+**For HOW questions (Guidance Docs):**
+```
+mcp__qmd__search  query="[key terms from question]"  collection="methodology"  limit=5
+```
+Use keyword search first since guidance docs use consistent terminology. Fall back to semantic if keyword misses. Prioritize `kind: guidance` results.
+
+**For WHAT questions (Domain Examples):**
+```
+mcp__qmd__vsearch  query="[domain + what the user wants to see]"  collection="methodology"  limit=5
+```
+Use semantic search to find the most relevant domain examples even if the exact domain name differs. Prioritize `kind: example` results.
+
+**For Reference documents:**
+Read specific reference documents based on the topic. The claim-map will indicate which reference docs are relevant. Load the 2-4 most relevant — not all of them.
+
+### Step 3: Read Deeply
+
+Do NOT skim search results. For the top 3-7 results:
+1. Read the full claim note or document
+2. Follow wiki links to related claims (1 hop)
+3. Note connections between claims that strengthen the answer
+
+**The depth principle:** A shallow answer citing 10 claims is worse than a deep answer weaving 4 claims into a coherent argument. Read fewer sources more deeply.
+
+### Step 4: Check User Context
+
+If the question involves the user's specific system:
+
+1. **Read derivation** — `ops/derivation.md` contains their dimension positions, vocabulary, constraints, and the reasoning behind every configuration choice
+2. **Apply vocabulary** — use `${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md` to translate universal terms into their domain language. Answer about "reflections" not "claims" if they are running a therapy system
+3. **Check constraints** — reference `${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md` to see if their configuration creates specific pressures relevant to the question
+4. **Cite dimension-specific research** — use `${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md` to ground answers in the specific claims that inform their configuration
+
+### Step 5: Check Local Methodology
+
+Read `ops/methodology/` for system-specific self-knowledge. Methodology notes may be more current than the derivation document — they capture ongoing operational learnings that the original derivation did not anticipate.
+
+```bash
+# Load all methodology notes
+for f in ops/methodology/*.md; do
+  echo "=== $f ==="
+  cat "$f"
+  echo ""
+done
+```
+
+**When methodology notes address the user's question:**
+- Cite them alongside research claims: "Your system's methodology notes say [X], which aligns with the research claim [[Y]]"
+- If methodology notes contradict research claims, flag the tension: "Your methodology note says [X], but the research suggests [Y] — this may be worth investigating with /{DOMAIN:rethink}"
+- Methodology notes about system behavior are more authoritative for "how does MY system work" questions than the general research graph
+
+**When to prioritize methodology over research:**
+- Questions about "why does my system do X" — methodology notes capture the specific rationale
+- Questions about behavioral patterns — methodology notes capture system-specific learnings
+- Questions about configuration — methodology notes may document post-init changes not in derivation.md
+
+**When to prioritize research over methodology:**
+- Questions about "why is X a good idea in general" — research claims provide the theoretical foundation
+- Questions about alternative approaches — the research graph covers options the system did not choose
+- Questions about methodology comparisons — research claims compare traditions systematically
+
+---
+
+## Answer Synthesis
+
+### Structure
+
+Every answer follows this structure:
+
+1. **Direct answer** — Lead with the answer, not the search process. Do not say "I searched for X and found Y." Say what the answer IS.
+
+2. **Research backing** — What specific claims support this answer. Cite by title: "According to [[claim title]]..."
+
+3. **Practical implications** — What this means for the user's specific situation. Use their domain vocabulary if available from derivation.
+
+4. **Tensions or caveats** — Any unresolved conflicts, limitations, or situations where the answer might not hold. The research has genuine tensions — share them honestly.
+
+5. **Further exploration** — Related claims or topics the user might want to explore. These are departure points, not assignments.
+
+6. **Sources consulted** — Briefly note which knowledge layers were used: "Research: [N] claims consulted. Local methodology: [M] notes consulted." When local methodology was relevant, name the specific note: "Your methodology note [[title]] informed the [specific part] of this answer."
+
+### Quality Standards
+
+**Ground answers in specific claims, not general knowledge.** The knowledge base exists so answers are evidence-based. If you answer from general knowledge without consulting the graph, you are bypassing the tool.
+
+**Acknowledge gaps honestly.** When the research does not cover something, say so. "The current research graph doesn't have claims about X" is a legitimate answer. Do not fabricate coverage.
+
+**Distinguish certainty levels.** Some claims are well-established with multiple supporting claims. Others are preliminary observations or research directions. The `confidence` field in claim frontmatter signals this:
+- No confidence field — standard established claim
+- `confidence: speculative` — early-stage observation, not fully evaluated
+- `confidence: emerging` — promising but needs more support
+- `confidence: supported` — well-evidenced claim
+- `confidence: established` — foundational, widely supported
+- `status: archived` — superseded or dissolved claim
+
+**Be opinionated.** The research has positions. Share them. "The research strongly suggests X because..." is better than "some sources say X, others say Y." If there IS genuine disagreement, present it as a tension, not as false balance.
+
+**Translate to user context.** When the user has a derivation, apply findings to their system. Generic advice is less useful than specific application. "In your therapy vault, this means..." is better than "in general, this means..."
+
+### Worked Examples
+
+#### Example 1: WHY Question
+
+**Question:** "Why does my system use atomic notes instead of longer documents?"
+
+**Classification:** WHY -> Primary: Research Graph. Secondary: Reference (dimension-claim-map).
+
+**Search:**
+1. `mcp__qmd__query  query="atomic notes vs compound documents granularity"  collection="methodology"  limit=8`
+2. Read `reference/dimension-claim-map.md` — find granularity dimension's informing claims
+3. Read `ops/derivation.md` — check user's granularity position
+
+**Answer:**
+> Your system uses atomic granularity because your conversation signaled "precise claims from papers." The research shows that atomic notes enable independent linking and recombination — according to [[atomic notes maximize recombinable surface area]], each note can be linked from any context without dragging unrelated content along. Your processing pipeline (extract -> reflect -> reweave -> verify) specifically requires atomic granularity to maintain the link fabric, because [[verify phase checks link density per note]] and compound documents would inflate link counts artificially.
+>
+> The trade-off: atomic notes create more files and require denser navigation structures. [[flat organization requires semantic search at scale]] explains why your system includes semantic search — without it, finding notes in a flat atomic structure becomes impractical beyond ~50 notes.
+>
+> **Tension:** [[composability and context compete at the note level]] — making notes small enough to link cleanly sometimes makes them too small to carry their own argument. Your system handles this through the description field and topic map context phrases.
+
+#### Example 2: HOW Question
+
+**Question:** "How do I process a large research paper?"
+
+**Classification:** HOW -> Primary: Guidance Docs. Secondary: Research Graph.
+
+**Search:**
+1. `mcp__qmd__search  query="large source processing chunking"  collection="methodology"  limit=5`
+2. `mcp__qmd__query  query="context degradation large documents extraction"  collection="methodology"  limit=5`
+
+**Answer:**
+> For sources over 2500 lines, chunk into segments of 350-1200 lines and process each chunk with fresh context. [Guidance: pipeline processing workflow] explains the chunking strategy in detail.
+>
+> The reason is [[context quality degrades as conversation grows]] — your extraction quality in the later sections of a 3000-line document will be measurably worse than in the early sections. Fresh context per chunk ensures each section gets your best attention.
+>
+> **Practical steps:**
+> 1. Run /seed to create the extraction task
+> 2. /reduce will automatically detect the source size and plan chunks
+> 3. Each chunk extracts independently with a running duplicate list across chunks
+> 4. The final extraction report covers all chunks combined
+>
+> **Your config** has `processing.depth: standard`, which means chunks process sequentially in the current session. If you switch to `deep`, each chunk would get its own isolated context (maximum quality, but slower).
+
+#### Example 3: WHAT Question
+
+**Question:** "What would a cooking recipe vault look like?"
+
+**Classification:** WHAT -> Primary: Domain Examples. Secondary: Guidance Docs.
+
+**Search:**
+1. `mcp__qmd__vsearch  query="cooking recipes culinary knowledge system"  collection="methodology"  limit=5`
+2. Read closest domain examples for structural inspiration
+
+**Answer:**
+> [Answer synthesized from examples, showing concrete folder structure, note examples, topic map examples, and vocabulary choices specific to a culinary domain. References the closest existing domain example for structural patterns.]
+
+---
+
+## Anti-Patterns
+
+### What NOT to Do
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| Answer without searching | Bypasses the knowledge base entirely | Always search, even for "obvious" questions |
+| List claims without synthesis | Dumps search results, forces user to connect dots | Weave claims into a coherent argument |
+| Search only one tier | Misses HOW when answering WHY, or vice versa | Check if secondary tier strengthens the answer |
+| Ignore user's derivation | Generic advice when specific is available | Read ops/derivation.md for user context |
+| Use universal vocabulary | Says "notes" when their system says "reflections" | Apply vocabulary transforms |
+| Fabricate claim citations | Cites claims that do not exist in the graph | Only cite claims you actually read |
+| Skip the claim-map | Searches blindly without routing | Read claim-map first for topic orientation |
+| Present false balance | "Some say X, others say Y" when research has a clear position | Be opinionated — share the research's position |
+
+### The Honesty Standard
+
+If the knowledge base genuinely does not cover a topic:
+
+1. Say so explicitly: "The current research graph doesn't have claims about X."
+2. Offer what IS available: "The closest related research is about Y, which suggests..."
+3. Flag it as a gap: "This might be worth investigating as a research direction."
+
+Do NOT extrapolate wildly from tangentially related claims. An honest "I don't know, but here's what's adjacent" is more valuable than a fabricated answer.
+
+---
+
+## Domain-Aware Answering
+
+When the user's question involves their specific system (not abstract methodology):
+
+### Step 1: Read Their Derivation
+
+Check for `ops/derivation.md` to understand:
+- Their dimension positions (granularity, organization, processing depth, etc.)
+- Their vocabulary choices (what are "notes" called in their domain?)
+- Their tradition mapping (which methodology preset, if any?)
+- Their personality settings (formal/warm, clinical/conversational)
+- Their constraint profile (which interaction constraints are active?)
+
+### Step 2: Apply Domain Vocabulary
+
+Use `${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md` to translate universal terms into their domain language. This is not cosmetic — it is about making the answer *native* to their system.
+
+| Universal Term | Therapy Domain | PM Domain | Research Domain |
+|---------------|---------------|-----------|-----------------|
+| notes | reflections | decisions | claims |
+| topic map | theme map | project map | MOC |
+| reduce | surface | extract | reduce |
+| reflect | connect | link | reflect |
+| inbox | journal | intake | inbox |
+
+### Step 3: Check Interaction Constraints
+
+Reference `${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md` to understand whether their configuration creates specific pressures relevant to the question. Some dimension combinations create tensions that affect the answer:
+- High granularity + flat organization = needs strong semantic search
+- Permissive selectivity + deep processing = high volume, slower throughput
+- Self space enabled + warm personality = rich identity layer
+
+### Step 4: Cite Dimension-Specific Research
+
+Use `${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md` to ground answers in the specific claims that inform their configuration choices. This makes the answer traceable: "Your system does X because claim Y supports it for your configuration."

package/skills/ask/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "knowledge-ask",
+  "description": "Query the Tools for Thought research knowledge graph. Ask about note design, knowledge systems, agent cognition, or methodology questions. Returns research-backed answers with claim references.",
+  "version": "0.4.0",
+  "author": "arscontexta",
+  "tags": ["knowledge-management", "research", "learning"],
+  "entry": "SKILL.md",
+  "platform_hints": {
+    "claude-code": {
+      "context": "fork",
+      "model": "opus"
+    },
+    "openclaw": {
+      "type": "external"
+    }
+  }
+}