Ask

/ask — Question Answering

Fast answers from your vault. Uses QMD hybrid search (BM25 + vector + rerank) when available, with automatic fallback to vault grep.

Context

Config: @_core/config.yaml

Input

User input: $ARGUMENTS

Processing Steps

Step 1: Detect Search Backend

Check if QMD MCP tools are available in the current session:

1. Try qmd_status (MCP tool) to check QMD availability and index state.
2. Evaluate result:

• QMD available AND has embedded docs → use QMD mode
• QMD available but 0 embedded docs → use Fallback mode + hint
• QMD not available (tool missing/error) → use Fallback mode

Step 2: Parse Question

• Detect project if mentioned
• Identify question type:
• "what did we decide about X" → decisions
• "who's blocked" → blockers
• "find doc for X" → docs
• "status of X" → index

Step 3A: QMD Mode (preferred)

When QMD is available and indexed:

1. Deep search: Call qmd_deep_search with the user's question.

• Use collection filter from config: _core/config.yaml → qmd.collection_name (default: pm-kit)
• Cap results: use qmd.max_results from config (default: 8)

1. Retrieve top docs: Call qmd_get or qmd_multi_get for the top-scored results.

• Apply minimum score threshold from config: qmd.min_score (default: 0.35)

1. Synthesize answer: Read the retrieved content and produce a grounded answer with source citations.

Step 3B: Fallback Mode (vault grep)

When QMD is not available or not indexed:

1. Search Strategy

| Question Type | Search Path | |--------------|-------------| | Decisions | decisions/{project}/*.md | | Blockers | blockers/{project}/*.md | | Docs | docs/{project}/*.md, docs/general/*.md | | Status | 01-index/{project}.md | | General | All folders |

1. Search Methods

• Filename match first (fastest — naming-as-API)
• Frontmatter field match
• Content grep (slower)

Step 4: Return Answer

Output Format

With results

## Answer

{Direct answer — 1-3 sentences, grounded in source content}

### Sources
- `{file-path}` — {brief context why this source is relevant}
- `{file-path}` — {brief context}

### Search Mode
{QMD (deep) | Fallback (vault grep)}

No results

## No Results Found

Searched: {folders or QMD collection}
Query: "{query}"

**Suggestions**:
- Try broader terms
- Check spelling
- Run `qmd embed` if QMD is installed but not indexed

### Search Mode
{QMD (deep) | Fallback (vault grep)}

Fallback mode hint

When running in Fallback mode, append after the answer:

> Tip: Install QMD for smarter search with semantic understanding. See [handbook/QMDINTEGRATION.md](handbook/QMD_INTEGRATION.md) for setup.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kv0906
• Source: kv0906/pm-kit
• License: MIT
• Homepage: https://willtran.xyz

Install and usage instructions live in the source repository linked above.