Wiki Query

Log unavailable tiers:

• If T1 unavailable: "T1 not available — NotebookLM config not found at {vault_path}/.notebooklm/config.json or .notebooklm/config.json. Falling back to T4."
• If T2 unavailable: "T2 not available — MemPalace wing '{wing}' not found. Run: bash skills/shared/mine-vault.sh. Falling back to T4."
• If T4 unavailable (no index.md): "No retrieval backends available. Run /wiki-update to generate index.md or configure T1/T2/T3."

Workflow

Step 1: Classify Query

Determine query type:

• Factual lookup — "What is X?", "How does Y work?", "What did we decide about X?"
• Relationship — "How does X relate to Y?"
• Synthesis — "What have we learned about X?", "Why did we decide X?"
• Gap — "What don't we know about X?"
• Search — "Find all mentions of X"
• Browse — "What pages exist about X?"

Step 2: Route to Best Available Tier

Factual lookup:

1. If T1 available → query NotebookLM:
   • Read .notebooklm/config.json (check {vault_path}/.notebooklm/ first, then project root .notebooklm/) to get notebook ID
   • Run: notebooklm ask "{query}" --notebook {notebook_id}
   • If answer is sufficient, return it with NotebookLM citations. Done.
2. Fallback → T4 (Step 3 below)

Synthesis / Relationship:

1. If T2 available → query MemPalace:
   • Derive wing name (same logic as availability check above)
   • For shared vaults, also search the conversation wing: $(echo "$PWD" | sed 's|[/.]|-|g')
   • Run: mempalace search "{query}" --wing="$PROJECT_WING" --results 10
   • If shared vault, also: mempalace search "{query}" --wing="$CONVO_WING" --results 5
   • Synthesize answer from returned chunks. Cite source files. Done.
2. Fallback → T4 (Step 3 below)

Gap (what don't we know):

1. If T2 available → query MemPalace (surfaces what WAS discussed/tried)
2. If T1 available → query NotebookLM (cross-reference what's documented vs what MemPalace found)
3. Synthesize the gap: what T2 found (experiential) vs what T1/T4 found (documented) reveals what's known but not yet captured. Done.
4. If neither T2 nor T1 available → Fallback → T4 (Step 3 below)

Search (find all mentions):

1. If T3 available → invoke obsidian:obsidian-cli skill:
   • Run: obsidian search query="{search term}" limit=10
   • Read top 3-5 results with obsidian read file="{name}"
   • Done.
2. Fallback → T4 (Step 3 below). Note: T4 searches index.md titles/tags/summaries only — it returns likely matches, not an exhaustive search. Inform the user: "Obsidian not available for full-text search. Showing likely matches from index.md."

Browse (what pages exist):

• Always → T4 (Step 3 below). index.md is the structured catalog.

Step 3: T4 Fallback — index.md Scan

This is the existing retrieval flow, renamed from "Tiered Retrieval" to avoid collision with T1-T4.

Step 3a — Index scan (always): Read {vault_path}/index.md. Search for pages matching the query by title, tags, and summary. Build a candidate list of 5-10 pages.

Step 3b — Summary scan (if needed): For each candidate, read the summary: field from frontmatter. Filter to the 3-5 most relevant pages based on summary content.

Step 3c — Full read (selective): Read full content of the top 3 candidates only. Follow up to 1 wikilink hop for additional context.

Step 4: Synthesize Answer

Compose the answer with citations using [[page-name]] wikilink notation. Include:

• Direct answer to the question
• Which tier was used (e.g., "Source: NotebookLM" or "Source: MemPalace search")
• Supporting evidence from vault pages or search results
• Related pages for further reading
• If the vault doesn't contain the answer, say so explicitly

Quick Mode

If the user says "quick answer" or "just scan": use only T4 Step 3a (index scan). Return matching page titles and summaries without reading full pages.

Warmup Contract

Machine-readable subcontract consumed by /ark-context-warmup. Spec: docs/superpowers/specs/2026-04-12-ark-context-warmup-design.md. Calling convention: docs/superpowers/plans/2026-04-12-ark-context-warmup-implementation.md D6.

Wiki-query already exposes the right behavior as a skill — this contract just tells warm-up which scenario-aware queries to run and how to extract findings. The actual implementation lives in the /wiki-query workflow; warm-up invokes it via the inline command pattern below.

warmup_contract:
  version: 1
  commands:
    - id: scenario-query
      # Warm-up invokes wiki-query inline via its T4 scan path (index.md + summaries).
      # For the warm-up's purposes, we only need the top-3 most relevant summaries, not the full T1/T2/T3 routing.
      shell: 'python3 "$ARK_SKILLS_ROOT/skills/wiki-query/scripts/warmup_scan.py" --vault {{vault_path}} --query {{query}} --top 3 --json'
      inputs:
        vault_path:
          from: env
          env_var: WARMUP_VAULT_PATH
          required: true
        query:
          from: template
          template_id: scenario_query
      output:
        format: json
        extract:
          matches: '$.matches'            # [{title, summary, path}]
          tier_used: '$.tier'             # always "T4" for warmup
        required_fields: [matches]
  prompt_templates:
    # Two-layer indirection: /ark-context-warmup sets WARMUP_SCENARIO_QUERY_TEMPLATE
    # to the appropriate scenario_templates entry below before dispatching the
    # wiki lane. The executor's _interpolate_template iterates until a fixed
    # point, so the outer {WARMUP_SCENARIO_QUERY_TEMPLATE} expansion plus the
    # inner {WARMUP_TASK_TEXT} in the scenario template both resolve in one
    # resolve_input call. Use single-brace — shell-style ${VAR} is not a
    # supported placeholder form.
    scenario_query: |
      {WARMUP_SCENARIO_QUERY_TEMPLATE}
  scenario_templates:
    # Picked by warm-up based on WARMUP_SCENARIO env var; template substituted into scenario_query above.
    greenfield: 'Has anything like {WARMUP_TASK_TEXT} been built before? Existing components or prior design decisions?'
    bugfix: 'Have we seen bugs related to {WARMUP_TASK_TEXT} before? Known failure modes, incident notes, prior fixes?'
    migration: 'Past migration notes for {WARMUP_TASK_TEXT}? Rollback procedures, prior framework changes?'
    performance: 'Past optimization work on {WARMUP_TASK_TEXT}? Benchmarks, bottleneck analyses?'
    hygiene: 'Related refactors or audits on {WARMUP_TASK_TEXT}? Tech debt notes, prior cleanup?'
    ship: 'Deploy runbooks, rollback steps, prior incidents for {WARMUP_TASK_TEXT}? Environment-specific gotchas?'
    knowledge-capture: 'What vault pages already exist on {WARMUP_TASK_TEXT} topic? Recent session coverage?'