Wiki Query

wiki-query

When This Skill Activates

• User asks a question that should be answered from vault contents.
• A vault is resolvable (see step 0).

Output language

Run skillwiki lang at the start. Generate query-result prose and --human summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.

Pre-orientation reads

Standard four reads (SCHEMA, index, log, project context if applicable).

Steps

0. Resolve vault and language. Run skillwiki path (fail if NO_VAULT_CONFIGURED) and skillwiki lang.
1. Determine scope. Ask the user once if ambiguous: vault | current project | project+concepts.
   • Ordinary questions are typed-knowledge-first. Run skillwiki query "<text>" [vault] without widening into raw captures. Default ranking is 4-signal only. Optional skillwiki query "<text>" --hybrid RRF-fuses that ranking with a rebuildable TF-IDF cache (skillwiki vectors rebuild); if the cache is missing, stop and rebuild instead of silently falling back.
   • Explicit freshness language — new, recent, fresh, clipped, raw, pending, undigested, unprocessed, not yet ingested, or not yet integrated — requests the pending evidence channel. Run skillwiki sources pending [vault] for inventory and skillwiki query "<text>" [vault] --include-pending for synthesis support.
2. Refresh graph. If .skillwiki/graph.json is missing or older than 24h: skillwiki graph build <vault>.
3. Compute overlap. skillwiki overlap <vault>.
4. Score candidates in prompt using the 4 signals:

• Direct wikilink: 3.0×
• Source overlap: 4.0× (read from overlap output)
• Adamic-Adar: 1.5× (read from graph output)
• Type affinity: 1.0×

5. Read top candidates in full (frontmatter + body).

6. Synthesize answer with explicit citations to the candidate pages.

   • When pending evidence was requested, keep the CLI's pending_sources separate from ranked typed results. Pending captures never change typed scores or ordering.
   • Label raw captures as pending evidence, not established vault knowledge. Explain that they have not yet been distilled into a maintained page.
   • Weak typed results may justify suggesting a pending lookup, but never silently broaden the query.

7. Sensitive content guard. Before filing any query or comparison page, scan the generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact before writing. If the answer depends on preserving a live secret, STOP and ask for a redacted source or explicit rotation/remediation direction.

8. Optional file. If the user accepts, first run skillwiki page publish --help. If it is unavailable, fail closed and leave the result unpublished. Otherwise:

   1. Resolve the vault and create a temporary directory outside the vault.
   2. Write the complete query/comparison page to <temp>/page.md, including final frontmatter, citations, Sources footer, and Decision Closeout.
   3. Run skillwiki page publish <temp>/page.md <vault> --target queries/<slug>.md (or comparisons/<slug>.md) and inspect the dry-run.
   4. Run the identical command with --write only when dry-run succeeds.
   5. On any nonzero result, retain the draft path and STOP; do not edit the final target, index.md, or log.md directly.
   6. Remove the temporary directory only after the publisher returns complete success.

   If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:

## Decision Closeout

Disposition: no-op | concept | ADR | work-item | evidence-needed
Reason: ...
Follow-up: ...

Use exactly one disposition. This is a prompt convention only; do not add CLI enforcement here.

Stop conditions

• Zero matching pages.
• User declines to file.
• Generated filed content contains unredacted live credentials or other authenticating secrets.

Pitfalls

Claimed-status vs actual-state gap

When a wiki page (especially a work item tasks.md) claims that fixes were applied, features were completed, or files were removed — verify on disk before accepting the claim. In one incident, a tasks.md marked 6 items DONE but 5 were not actually applied: a script claimed "removed" was still 2020 bytes on disk, a crontab claimed "updated to 30min" was still */10, and a build target claimed "verified has consumers" had no web server serving it. Rule: After reading a work item that declares completion, run at least one verification command per critical claim (check file existence, grep a config, inspect a crontab). Documents can drift from reality — the filesystem is the source of truth.

Forbidden

• Filing without the skillwiki page publish dry-run passing.
• Directly creating a final typed page or separately editing index.md or log.md for its publication.
• Skipping the orientation reads even for "quick" queries.
• Treating a pending raw capture as integrated typed knowledge, or mixing it into typed ranking.
• Silently searching pending sources when the user did not request fresh/raw/unprocessed material.
• Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.