ask

/ask — Query-Driven Knowledge Creation

Research a question, check if the answer already exists in the knowledge base, and if not, draft a knowledge doc that saves directly to promoted files after user review. Fast path from question to knowledge — no backlog intermediary.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Cowork variant — namespaced-only. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /ask resolves to aria-knowledge's variant — Code is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. To reach this skill, use the namespaced form: /aria-cowork:ask. Do NOT match bare /ask — that belongs to aria-knowledge.

Before Step 0: Check whether the Bash tool is available in this session. If Bash IS available (you are running in Claude Code or another runtime with shell access), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-cowork's /ask from a runtime with shell access.

Behavior is largely the same in both runtimes; for the Code-native variant (uses ~/.claude/aria-knowledge.local.md config and the full Code tool surface), use /ask (the aria-knowledge canonical).

Use /ask instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke ask (the bare-slash canonical, which routes to aria-knowledge when both ports are loaded) with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the aria-knowledge variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.
• n / no — Proceed with this (aria-cowork) variant anyway despite the runtime mismatch. The user has explicitly opted in.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.

If Bash is NOT available (normal Cowork runtime), proceed to Step 0.

Step 0: Resolve config

The default knowledge folder is ~/Projects/knowledge/ (expand ~ to your home directory's absolute path). Read <knowledge_folder>/aria-config.md and extract knowledge_folder. If aria-config.md doesn't exist, stop: "aria-cowork is not configured. Run /aria-setup to get started."

Use <knowledge_folder> for all file operations during this session.

Step 1: Parse question

The user provides a question as the argument. If no argument is provided, ask: "What would you like to know?"

Extract the core topic and likely tags from the question for use in Step 2.

Step 2: Check existing knowledge

Before researching, check if the answer already exists:

1. Resolve aliases first (added v0.3.0 — parity with aria-knowledge v2.16.0): if <knowledge_folder>/aliases.md exists, parse the alias→canonical map and replace any tag token in the question that matches an alias with its canonical form before the index lookup. No notification line needed — this is internal to /ask's coarse check (/context is the surface that surfaces resolution notifications).

If <knowledge_folder>/index.md exists, extract tags from the (post-alias-resolution) question and check for matching files in both the ## Tag Index section AND the ## Semantic Hints Index section. Tag matching is exact equality (existing behavior); hint matching is substring (case-insensitive, hyphen-normalized) — same rule as /aria-cowork:context Step 3. A hint match counts the same as a tag match for partial-match detection.

1. Scan headings of files in approaches/, guides/, references/, decisions/ for topic overlap.
2. Check intake/ backlogs for pending items on the same topic.

If a strong match is found: Present the existing file(s) to the user:

"This may already be covered in [filename]. Want me to load it? Or research fresh?"

• If user says load: read and present the file, done.
• If user says research: proceed to Step 3.
• If partial match: note it for Step 5 ("related existing doc found — consider updating instead of creating new").

If no match: Proceed to Step 3.

Step 3: Research

Answer the question using available sources:

1. Knowledge base — scan relevant files for partial answers or related context.
2. Web — use WebSearch and WebFetch for external information (APIs, frameworks, best practices).
3. MCP-connected tools (when available in v0.2.0+) — query connected ~~docs, ~~project tracker for org-internal context.

Synthesize a clear, complete answer. Focus on practical, actionable knowledge — not textbook definitions.

Step 4: Determine category

Based on the answer content, suggest where it belongs:

| Content type | Category | Example | |---|---|---| | How to do X (proven method) | approaches/ | API pagination patterns | | How X works (operational) | guides/ | Supabase auth setup | | What others say about X | references/ | Stripe webhook best practices | | We chose X because Y | decisions/ | Why cursor over offset pagination | | X must/must not (principle) | rules/ | Rare — usually via /audit-knowledge |

Step 5: Draft knowledge doc

Write a draft in the standard format for the suggested category:

---
tags: [detected tags from question and answer]
---

# [Title]

**Last updated:** YYYY-MM-DD

[Answer content — structured with sections as appropriate]

## Related
[Links to any existing knowledge files that connect to this topic]

If Step 2 found a partial match, note: "Related: [existing file] — consider whether this should update that file instead of creating a new one."

Step 6: Present for review

Show the draft with metadata:

## /ask Result

**Question:** [original question]
**Category:** [suggested category]
**File:** [suggested filename in kebab-case]
**Tags:** [detected tags]

[Draft content]

Save to <knowledge_folder>/[category]/[filename]? (yes / edit / change category / reject / update <existing-file>)

Step 7: Save or discard

Based on user response:

• "yes" — write the file to the suggested location.
• "edit" — user provides edits, then save.
• "change category" — user specifies different category/filename, then save.
• "update [existing file]" — merge content into the specified existing file instead of creating new.
• "reject" — discard, nothing saved.

After saving, confirm: "Saved to [path]. Run /aria-cowork:index to update the tag index."

Rules

• Check existing first — never create a duplicate when an update would serve better.
• Skip backlogs — the user is reviewing in real-time, no need for staging.
• Respect copyright — for web-sourced answers, synthesize in your own words. Include source URLs in a References section but don't copy content.
• Practical over theoretical — answers should help future sessions, not read like documentation. "Here's how to do X" over "X is defined as..."
• Tag detection — match question keywords against known tags from index.md. Add new freeform tags if no known tag fits.
• One question, one doc — if the question spans multiple topics, suggest splitting into separate /ask invocations.
• Use Cowork's native I/O — never invoke a Filesystem MCP connector (per ADR-003).