Project Q&A

Answers a free-form question about the project in one pass. Reads context from the Knowledge Base, the live codebase, and in-flight AID work state, then replies with source citations.

Write scope (gap-capture only). /aid-ask writes to exactly one place and only when the context is insufficient to answer: it appends a ### Q{N} Query-Gap entry to a ## Q&A (Pending) section of a STATE.md backlog file. No KB doc, settings file, or code file is ever written. The answer path stays fully read-only; only the gap-append branch writes (NFR-6/C4: capture-and-flag, never auto-apply).

Not a numbered pipeline phase. /aid-ask is an optional, on-demand skill outside the Discover-Execute flow. No work folder, no STATE.md of its own.

Single-shot, no state machine. One pass: read context -> answer -> exit.

Pre-flight

Confirm a question was supplied. If /aid-ask is invoked with no argument, print:
```
Usage: /aid-ask <question>
Example: /aid-ask "Which agent tier handles code review?"
```
Then exit without answering.

Execution: answer the question

Step 1 — Classify the question

Decide whether the question is trivial or broad/expensive:

Trivial: answerable by reading a small number of known KB docs or a specific file path. Examples: "What does aid-housekeep do?", "Where does the generator output go?", "What is the allowed-tools list for aid-researcher?"
Broad/expensive: requires deep codebase traversal, cross-file pattern matching, or analysis of many files. Examples: "What are all the places where STATE.md is written?", "Summarize every Q&A in the current discovery cycle", "How does the render pipeline handle tool-name remapping across all profiles?"

Step 2a — Trivial question: answer inline

Read only the files needed to answer:

Load .aid/knowledge/INDEX.md to identify which KB docs are relevant.
Read the relevant KB docs (e.g., architecture.md, coding-standards.md, module-map.md, pipeline-contracts.md, schemas.md, etc.) using Read.
Glob or Grep specific files as needed (e.g., locate a SKILL.md or AGENT.md, check a script header, read a work STATE.md).
Compose the answer with inline citations:
- KB doc: cite as "architecture.md §Section" or coding-standards.md §7b.
- File path: cite as .agents/skills/aid-ask/SKILL.md.
- Work state: cite as work-001-kb-skills STATE.md or work-NNN STATE.md §Section.

Step 2b — Broad/expensive question: dispatch aid-researcher

Dispatch aid-researcher with this prompt structure:

TASK: Answer the following question about the project. Operate strictly
read-only — return your analysis as your message; do NOT write, create, edit,
or delete any file.

QUESTION: <the user's question verbatim>

INSTRUCTIONS:
1. Load .aid/knowledge/INDEX.md to navigate the KB.
2. Read the KB docs relevant to the question.
3. Glob or Grep the codebase as needed to gather evidence.
4. Read .aid/works/work-*/STATE.md files if the question concerns in-flight works.
5. Return a structured answer with source citations (KB doc names, file paths,
   work-NNN STATE references). Do not fabricate facts; if the context cannot
   answer the question, state the gap explicitly.
6. Write nothing. Return everything as your message.

Wait for aid-researcher to complete. Use its returned message as the answer body for Step 3.

Step 2c — Connector enrichment (optional)

When the question concerns a specific item tracked in a catalogued connector (e.g. "what's the status of PROJ-45?"), fetch it by invoking /aid-read-ticket [<connector>:]<ticket-id> — the connector resolution and host-MCP fetch live there (feature-001); no direct-fetch recipe is re-implemented here — and fold what it returns into the answer, cited the same way as any other source (Step 3). Skip silently when no matching connector is catalogued — this never blocks or replaces the KB/codebase/in-flight-work answer path above; the delegated read is non-destructive, so no extra confirm is added.

Step 3 — Compose and emit the reply

Format the answer as:

## Answer

<answer text, grounded in the evidence gathered>

## Sources

- <citation 1>  (e.g., `architecture.md §Thin-Router state machine`)
- <citation 2>  (e.g., `.agents/skills/aid-housekeep/SKILL.md`)
- <citation 3>  (e.g., `work-NNN STATE.md §Goal`)

If context is insufficient to answer, emit the reply AND then capture the gap:

Reply (always emit first):

## Answer

The available context does not contain enough information to answer this
question: <restate the question briefly>.

## Gap

<Describe specifically what is missing -- which KB doc lacks the data, which
codebase subtree was not reachable, or which work STATE.md did not exist.>

## Sources

- <doc or path checked>
- <doc or path checked>

Gap capture (Step 4) -- append after emitting the reply:

Resolve the target backlog file using the rule in Step 4 below, determine the next free Q{N} in that backlog (never renumber), then append the entry.

Do NOT fabricate an answer. Stating the gap and capturing it is the correct response when context is insufficient.

Step 4 -- Gap capture

When Step 3 emits a gap reply, immediately capture the gap into the Q&A backlog.

Target-file resolution:

If the query was about an in-flight work (the question concerns a specific .aid/works/work-NNN-*/ effort whose STATE.yml exists), write to that work's .aid/works/work-NNN-*/STATE.yml qa sequence -- on the flattened Lite layout, the work-root STATE.yml carries this key directly; on a full multi-delivery work, the work-root file carries no qa key at all (full-layout omission rule), so the actual target there is the relevant delivery's own deliveries/delivery-NNN/STATE.yml qa sequence instead.
Otherwise write to the knowledge backlog at .aid/knowledge/STATE.md ## Q&A (Pending).
When ambiguous (the query touches both a work and the KB), default to .aid/knowledge/STATE.md and name the alternative work in the entry's Context field. (A Q&A append is non-destructive, so default-and-name is the proportionate choice over asking the user.)

Determine N: read the target backlog's qa sequence, find the highest existing id, and set N = highest + 1. If the sequence is empty, set N = 1. Never renumber existing entries. (The knowledge backlog target above is unaffected -- it stays the markdown ### Q[0-9]+ scheme, since discovery-state-template.md is out of this task's scope.)

Classify the gap flavor:

KB-contradicts-code: the KB asserts a fact that directly contradicts what the live code says. Impact = High.
KB-cannot-answer: the KB simply lacks coverage for the question. Impact = Medium.

Append the following entry to the qa sequence (work-level target; the knowledge-backlog target keeps its own markdown ### Q{N} shape, unchanged by this task):

- id: {N}
  category: 'Query-Gap / <KB-cannot-answer | KB-contradicts-code>'
  impact: <High | Medium>
  state: Pending
  context: '/aid-ask was asked "<question verbatim>". The available
    context could not answer it: <the specific gap -- which KB doc lacks the
    data, OR the exact KB claim that contradicts the code with both citations>.
    Sources checked: <docs/paths>.'
  suggested: 'Run /aid-update-kb "<the gap as an update prompt>" (or fold
    into the next /aid-housekeep KB-DELTA) to close the gap, then
    REVIEW -> APPROVAL.'

Write-scope constraint (hard): writes are restricted to appending a Query-Gap entry to a qa sequence (work-level target) or the knowledge backlog's ## Q&A (Pending) section; no KB doc, settings, or code file is ever written. If the resolved work-level target file's qa key does not yet exist, create it (create-parent-if-absent, matching writeback-state.sh's own convention). Do not modify any other part of the file.

Dispatch table

Condition	Worker	Output
Trivial question	inline (Read / Glob / Grep)	Answer in conversation
Broad/expensive question	`aid-researcher` (read-only)	Answer in conversation
Insufficient context	inline + gap-capture write	Gap reply + Q{N} entry appended to the `qa` sequence (STATE.yml)

The dispatched aid-researcher MUST be instructed to operate strictly read-only (return analysis as its message; write nothing). See Step 2b for the required prompt.

Constraints

Write scope (gap-capture only). Writes are restricted to appending a Query-Gap entry (id/category/impact/state/context/suggested) to a qa sequence (work-level target) or the knowledge backlog's ## Q&A (Pending) section. No KB doc, settings, or code file is ever written. The answer path stays read-only; only the gap-append branch writes.
No work folder. /aid-ask does not create .aid/works/work-*/ directories or STATE.yml files for its own use.
Cite sources. Every factual claim in the answer must be traceable to a KB doc, a file path, or a work STATE.yml reference.
State gaps explicitly. When the context cannot answer, say so clearly. Never invent data.
Read-only dispatch. When aid-researcher is dispatched, its prompt MUST instruct it to return analysis as its message and write nothing.

aid-ask

SKILL.md.claude/skills/aid-ask/SKILL.md