acostanzo/query

Inkwell:query

Answer a writer's or LLM's question by pulling top-N chunks from the FTS5 index over docs/, synthesising a one-paragraph answer from those chunks, and returning the answer in a fixed shape — claim, sources, corroboration. The synthesis is the only LLM-shaped part of the path; everything else (retrieval, anchor resolution, citation formatting, corroboration field) is produced deterministically by bin/inkwell-query-retrieve.sh.

Behaviour

1. Retrieve

Run the retrieval script with the user's question verbatim:

bash "${CLAUDE_PLUGIN_ROOT}/bin/inkwell-query-retrieve.sh" "<QUESTION>" "<REPO_ROOT>"

<REPO_ROOT> is the absolute path to the target repository, typically the working directory when /inkwell:query was invoked. The script:

• Calls bin/inkwell-search.sh to get the top-5 FTS5 hits.
• For each hit, resolves the enclosing heading anchor by walking back to the nearest preceding #-rule heading (falling back to the doc's H1 if the match falls in YAML frontmatter).
• Slugifies the heading text per GitHub anchor rules (lowercase, non-alphanumerics → -, runs collapsed, leading/trailing - stripped) so the citation path#anchor is the link a reader can click.
• Extracts the section body from the heading line through the next heading of equal or higher rank, capped at 60 lines.
• Pipes the chunks block to bin/inkwell-corroborate.sh, which classifies each citation's claims into Tier 1 (deterministic name-resolution), Tier 2 (subagent-judged behavioural verification), or Tier 3 (annotated "could not corroborate"). The dispatcher's per-citation verdicts populate the Corroboration block.
• Renders the Sources block and the Corroboration block in the locked contract shape (see "Response contract" below).

2. Read and synthesise

The script's stdout is one combined block. Above the ---END-OF-CHUNKS--- sentinel is the chunks payload — one section per cited doc, each prefixed ### path#anchor. Below the sentinel is the rendered tail (Sources + Corroboration), which is appended to the response unchanged.

Read the chunks. Synthesise one paragraph answering the user's question, drawing only from those chunks. Be honest about scope:

• If the chunks answer the question directly, say so and cite which ones support which part of the claim.
• If the chunks only partially answer the question, name the gap.
• If the chunks don't actually answer the question, say so plainly. Do not invent facts the chunks do not contain.

The synthesis paragraph is the only non-deterministic part of the response. Everything else — citations, snippets, corroboration — comes from the script unchanged.

3. Emit the response

Concatenate, in this exact order:

1. **Answer.** followed by the synthesised paragraph.
2. A blank line.
3. The Sources: block (verbatim, copied from the script output below the ---END-OF-CHUNKS--- sentinel).
4. A blank line.
5. The Corroboration: block (verbatim, copied from the script output) — one bullet per citation/claim with the dispatcher's verdict.

If the script's stdout is the literal *No matching documentation found.* line, return that string as-is. The empty-docs/ branch and the no-FTS5-hits branch share this sentinel; do not retry, do not fabricate citations.

Response contract — locked at M3, populated at M5

This contract is load-bearing. The M3 stub and the M5 verdicts share the same field name, ordering, and citation format — downstream consumers of /inkwell:query output can rely on the field's existence and position from M3 onward; M5 only changes the content of the Corroboration block.

The response, in order:

| Field | Source | M3 behaviour | M5 behaviour | |---|---|---|---| | Answer. (one paragraph) | LLM synthesis from chunks | Synthesised | Unchanged | | Sources: list, one per cited doc | bin/inkwell-query-retrieve.sh | - [path#anchor](path#anchor) — <one-line snippet> | Unchanged | | Corroboration: block, one bullet per claim | bin/inkwell-corroborate.sh (via inkwell-query-retrieve.sh) | Single literal stub line not yet implemented | - path#anchor — <verdict> per claim — verdict ∈ verified / drift detected (see …) / could not corroborate |

The M5 Corroboration block looks like:

**Corroboration:**
- docs/auth/session.md#sessions — verified
- docs/auth/session.md#sessions — could not corroborate
- docs/concepts/auth.md#authentication — drift detected (see src/auth/login.ts: symbol 'foo' not found)

Multiple lines per citation are normal — Tier 1 emits one verdict per inline code span; Tier 2 emits one verdict per behavioural claim batch; Tier 3 emits a single fallback line for citations with no code-shape signal.

If the dispatcher is unavailable, fails, or returns empty stdout, /inkwell:query falls back to one could not corroborate bullet per cited Source — the field is always populated, the shape is always stable, the response always ships. Per ADR-007: "corroboration never blocks the response."

The architectural rationale is in project/adrs/007-inkwell-corroboration-architecture.md.

Empty-scope contract

If docs/ is missing, empty, or no hits resolve to a real heading, the response is the single line:

*No matching documentation found.*

Exit cleanly. Never crash on a fresh repo.

What this skill does not do

• No vector search. v1 is FTS5 only. Vector retrieval is deferred to v2.
• No mutation of docs/ or any consumer artefact. ADR-006 §2 holds: read-only retrieval surface. The corroboration dispatcher is also read-only against the consumer's source tree.
• No inventing citations. Every entry in Sources: comes from inkwell-query-retrieve.sh's deterministic output. If the chunks don't answer the question, say so — do not fabricate sources to pad an answer.
• No inventing verdicts. Every entry in Corroboration: comes from inkwell-corroborate.sh's deterministic / subagent-dispatched output. Do not synthesise verdicts in the answer paragraph.