| name | second-brain-query |
| description | Answer a natural-language question by synthesising content from wiki/, and save the response to outputs/. |
| argument-hint | "<question>" |
| user-invocable | true |
Second Brain — Query
Answer a natural-language question by synthesising content from wiki/, and save the response to outputs/.
Contract: specs/001-personal-knowledge-base/contracts/second-brain-query.md
Invocation
/second-brain-query "What are the main arguments for agent ownership vs. strike teams?"
/second-brain-query "What do I know about AI partnerships?"
| Argument | Required | Description |
|---|
<question> | Yes | The natural-language question to answer |
If invoked without a question argument, ask: "What would you like to know? Please provide a question."
Execution
Step 1 — Parse the question
Extract the question from the argument string. If no argument is provided, ask the user for their question.
Step 2 — Check preconditions
Check that wiki/INDEX.md exists. If it does not:
The knowledge base is empty — wiki/INDEX.md does not exist.
Run /second-brain-ingest first to populate the wiki from your raw/ content.
Stop. Write nothing.
Step 3 — Read the index and identify relevant topics
Read wiki/INDEX.md. Scan the topic list and summaries to identify which wiki articles are likely to contain relevant information for the question.
Select the most relevant topics (typically 1–5 articles depending on question scope). If no topics appear relevant, note that the question may not be covered.
Step 4 — Read relevant wiki articles
Read the full content of each selected wiki article from wiki/<topic>.md.
If a referenced article does not exist as a file (only in INDEX), skip it and note the gap.
Step 5 — Synthesise the answer
Using only the content read from wiki articles, synthesise a clear, grounded answer to the question:
- Answer directly — lead with the key point, then support with detail
- Use
[[topic-name]] wikilink citations inline to attribute claims to their source article
- Structure with headings or bullet points if the answer spans multiple sub-topics
- Do NOT fabricate information not present in the wiki articles
Freshness rules — apply these when synthesising:
- When claims are date-stamped (e.g., "As of Jan 2026:" or "(May 2026)"), prioritise the most recent information. If a newer source contradicts an older one on the same claim, lead with the newer fact and note the older one only as historical context.
- When surfacing a status, metric, or decision, always include the date it was recorded — e.g., "As of May 2026, AI-assisted PRs are at 25%" — so the reader can judge freshness.
- If a claim has no date, note it as "(date unknown)" rather than presenting it as current.
- When the question is explicitly about current state (e.g., "what is our status", "how are we doing"), flag any response built primarily from sources older than 3 months with a warning like: "Note: the most recent source on this topic is from [date] — newer context may exist."
If no relevant wiki content exists for the question:
This topic is not yet in your knowledge base.
To add it, you could:
- Import relevant Craft notes with /second-brain-import-craft
- Import a PDF with /second-brain-import-pdf
- Add a markdown file to raw/ and run /second-brain-ingest
Do not attempt to answer from general knowledge. Write an output file noting the gap (see Step 6) and stop.
If only partial content exists (question is partly covered): answer the parts that are covered, then explicitly note which aspects are not in the wiki.
Step 6 — Generate output filename
Generate the output slug from the first 5–6 words of the question:
- Lowercase all words
- Replace spaces with hyphens
- Remove characters that are not alphanumeric or hyphens
- Truncate to 40 characters maximum
Output path: outputs/YYYY-MM-DD_thread-<slug>.md
Example: "What do I know about AI partnerships?" → outputs/2026-06-16_thread-what-do-i-know-about-ai.md
Step 7 — Write the output file
Check that outputs/ directory exists. If not, create it.
Write the output file in thread format. Use the current date (YYYY-MM-DD) for the timestamps:
<!-- sb:thread id="YYYY-MM-DD_thread-<slug>" created="YYYY-MM-DD" -->
# [Original question]
<!-- sb:turn role="user" ts="YYYY-MM-DD" -->
## You
[Original question]
<!-- sb:turn role="assistant" ts="YYYY-MM-DD" -->
## Second Brain
[Synthesised answer]
*Sources: [[wiki/topic-1]], [[wiki/topic-2]]*
Where:
- The H1 heading reproduces the original question verbatim
- The
<!-- sb:thread --> comment carries the thread ID (matching the filename without the .md)
- Each
<!-- sb:turn --> comment carries the role (user or assistant) and date
- The sources line lists every wiki article that contributed to the answer (using
[[wiki/topic-name]] syntax)
- No
--- horizontal rules between turns — the comment markers delineate turns without visible dividers
- For gap responses, the assistant turn contains the gap acknowledgement and suggestions
Step 8 — Display and confirm
Display the full answer to the user in the conversation.
Then report:
Thread started: outputs/YYYY-MM-DD_thread-<slug>.md
Sources: [[wiki/topic-1]], [[wiki/topic-2]]
Invariants
- Never modifies any file in
raw/ or wiki/
- Always cites the wiki articles that informed the answer — never fabricates
- Always writes an output file, even for gap responses
- Output files are append-only — never overwrite a prior query result
Error Conditions
| Condition | Behaviour |
|---|
| No argument provided | Ask user for their question |
wiki/INDEX.md missing | Report empty knowledge base; prompt to run ingest; stop |
| No relevant wiki content | Acknowledge gap; suggest how to fill it; write gap-noting output file |
| Wiki article referenced in INDEX but file missing | Skip missing file; note in answer; continue with available articles |
outputs/ directory missing | Create it, then write the output file |
