/ask

Ask a question to the wiki knowledge base. The LLM reads context_brief.md for global context, retrieves relevant pages, synthesizes an answer with citations. Good answers can be crystallized back into the wiki — written to outputs/, as new concept pages, or appended to an existing idea/method/output note — so exploration compounds like ingestion does.

Inputs

• question: natural-language question (e.g. "What is the core difference between LoRA and Adapter?")
• --crystallize (optional): if specified, crystallize the answer back into the wiki (default: answer only, no write)
• --format (optional): output format, default markdown, options: table / timeline / bullets

Outputs

• Always: terminal output of synthesized answer (with [[slug]] citations)
• If crystallize:
  • wiki/outputs/{query-slug}.md — query result page (default crystallize target)
  • or wiki/concepts/{slug}.md — if the answer reveals a new cross-paper concept
  • or appended to an existing wiki/ideas/{slug}.md / wiki/methods/{slug}.md / wiki/outputs/{slug}.md — if the answer adds a finding to an existing entity
  • updated wiki/graph/edges.jsonl (relationships produced by crystallize)
  • updated wiki/index.md and wiki/log.md

Wiki Interaction

Reads

• wiki/graph/context_brief.md — global compressed context (ideas, gaps, failed ideas, papers, edges)
• wiki/index.md — page catalog for locating relevant pages
• wiki/graph/open_questions.md — open questions, helps identify whether the question touches known gaps
• wiki/papers/*.md — paper pages relevant to the question
• wiki/concepts/*.md — concept pages relevant to the question
• wiki/methods/*.md — method pages relevant to the question
• wiki/topics/*.md — topic pages relevant to the question
• wiki/people/*.md — if the question involves specific researchers
• wiki/ideas/*.md — if the question involves research ideas or failed ideas
• wiki/experiments/*.md — if the question involves experiment results
• wiki/Summary/*.md — if the question involves domain-wide landscape

Writes (crystallize mode only)

• wiki/outputs/{query-slug}.md — CREATE (query result page)
• wiki/concepts/{slug}.md — CREATE (newly discovered concept) or EDIT (supplement existing concept)
• wiki/ideas/{slug}.md / wiki/methods/{slug}.md / wiki/outputs/{slug}.md — EDIT (append finding to existing page)
• wiki/graph/edges.jsonl — APPEND (relationships produced by crystallize)
• wiki/graph/context_brief.md — REBUILD (if crystallize created new pages)
• wiki/graph/open_questions.md — REBUILD (if crystallize created new pages)
• wiki/index.md — EDIT (if crystallize created new pages)
• wiki/log.md — APPEND

Graph edges created (crystallize only)

• output → paper: derived_from (papers cited in the answer)
• output → concept: derived_from (concepts cited in the answer)
• output → idea / output → method: derived_from (ideas or methods cited in the answer)
• concept → paper: supports (if a new concept is generalized from papers)

Workflow

Precondition: confirm working directory is the wiki project root (containing wiki/, raw/, tools/). Set WIKI_ROOT=wiki/.

Step 1: Load Global Context

1. Read wiki/graph/context_brief.md — get compressed snapshot of wiki's current knowledge (ideas, gaps, papers, edges)
2. Read wiki/graph/open_questions.md — understand known open questions and knowledge gaps
3. If both are missing, rebuild first:

   python3 tools/research_wiki.py rebuild-context-brief wiki/
   python3 tools/research_wiki.py rebuild-open-questions wiki/

Step 2: Retrieve Relevant Pages

1. Read wiki/index.md, match relevant slugs against question keywords
2. Extract ideas, methods, and papers semantically related to the question from context_brief.md
3. Sort by relevance, select top-K pages (K ≤ 15 to avoid exceeding context window)
4. Read full content of selected pages
5. If the question involves relationships (e.g. "difference between X and Y"), additionally read edges connecting X and Y from wiki/graph/edges.jsonl

Step 3: Synthesize Answer

1. Synthesize an answer to the user's question based on collected page content
2. Answer requirements:
   • Cited: every key statement must include a [[slug]] wikilink pointing to its source page
   • Structured: organize output according to --format parameter (markdown / table / timeline / bullets)
   • Acknowledge uncertainty: clearly flag "insufficient evidence in wiki" for parts with weak support
   • Flag knowledge gaps: if the question touches a known gap in open_questions.md, call it out explicitly
   • Cite idea status: when referencing ideas, note their status and novelty_score
3. If the question exceeds the wiki's current knowledge, honestly say so and suggest:
   • which papers to ingest to fill the gap
   • possible search directions (arXiv keywords, Semantic Scholar queries)

Step 4: Assess Crystallize Value

1. Judge whether the answer is worth writing back to the wiki (make a recommendation even if --crystallize was not specified)
2. Signals that crystallize is worthwhile:
   • The answer synthesizes information from multiple papers, forming a new cross-paper insight
   • The answer reveals a concept not yet explicitly recorded in the wiki
   • The answer adds a finding that strengthens an existing idea, method, or output note
   • The answer addresses a known gap in open_questions.md
3. Signals that crystallize is not worthwhile:
   • The answer merely restates the content of a single page
   • The question is a simple factual lookup (e.g. "What year was LoRA published?")
   • The answer relies primarily on inference rather than wiki evidence
4. Append a crystallize recommendation at the end of the answer:

   💡 Crystallize recommendation: [worthwhile / not needed] — [reason]

Step 5: Crystallize Back to Wiki (if user confirms or --crystallize was specified)

Choose the crystallize target based on answer content:

Case A — Write to outputs/ (default):

1. Generate slug: python3 tools/research_wiki.py slug "<query-summary>"
2. Create wiki/outputs/{query-slug}.md:

   ---
   title: ""
   slug: ""
   query: ""           # original question
   source_pages: []    # slugs of all pages cited in the answer
   date_created: YYYY-MM-DD
   ---

   Body is the answer content (preserve wikilinks)
3. Add a graph edge for each cited source page:

   python3 tools/research_wiki.py add-edge wiki/ --from outputs/<slug> --to papers/<source-slug> --type derived_from --evidence "query answer"

Case B — Create new concept:

1. If the answer reveals a new concept: create wiki/concepts/{slug}.md using the CLAUDE.md concept template
2. maturity: emerging
3. key_papers: extracted from answer citations
4. Add graph edges (concept → papers)
5. Append reverse links to relevant paper pages under ## Related

Case C — Append finding to an existing idea, method, or output note:

1. If the answer extends a finding tied to an existing entity, append a short paragraph (with [[slug]] citations) to the appropriate section:
   • wiki/ideas/{slug}.md → ## Lessons learned or ## Pilot results
   • wiki/methods/{slug}.md → ## Limitations or ## Tradeoff profile
   • wiki/outputs/{slug}.md → end of the body
2. Add graph edges from the touched page to the cited papers/concepts/methods (derived_from)
3. Do not create a new entity; this case only enriches an existing one

Step 6: Update Navigation and Graph (crystallize only)

1. index.md: append new page entries under the appropriate category
2. log.md:

   python3 tools/research_wiki.py log wiki/ "ask | <question-summary> | crystallized: <target-path>"

   If not crystallized:

   python3 tools/research_wiki.py log wiki/ "ask | <question-summary> | answer-only"

3. Rebuild derived graph files (only if crystallize created new pages):

   python3 tools/research_wiki.py rebuild-context-brief wiki/
   python3 tools/research_wiki.py rebuild-open-questions wiki/

Step 7: Report to User

Output a summary including:

• Number and list of retrieved pages
• Answer (with citations and formatting)
• Knowledge gap annotations (if any)
• Crystallize recommendation or execution result
• Follow-up suggestions (papers recommended for ingestion, related open questions)

Constraints

• No fabrication: answers must be grounded in actual wiki content; do not invent from LLM pre-training knowledge
• Citations must exist: every [[slug]] must point to a page that actually exists in the wiki
• raw/ is read-only: do not modify files under raw/
• graph/ only via tools: do not hand-edit files under graph/
• Crystallize requires confirmation: unless the user explicitly specifies --crystallize, only recommend but do not write
• Context limit: retrieve at most 15 pages to stay within context window
• Cite idea status: when referencing ideas, always note their status and novelty_score
• Flag gaps: if the question touches a known gap in open_questions.md, explicitly call it out
• outputs/ frontmatter must include query and source_pages: ensures traceability

Error Handling

• context_brief.md missing: run python3 tools/research_wiki.py rebuild-context-brief wiki/ to rebuild, then retry
• wiki is empty: inform the user to first run /init or /ingest to build the knowledge base
• no matching pages: honestly report that no relevant content exists in the wiki, suggest search and ingest directions
• crystallize slug conflict: append a numeric suffix (e.g. query-result-2)
• index.md missing: run python3 tools/research_wiki.py init wiki/ to initialize, then retry

Dependencies

Tools（via Bash）

• python3 tools/research_wiki.py slug "<title>" — slug generation
• python3 tools/research_wiki.py add-edge wiki/ --from <id> --to <id> --type <type> --evidence "<text>" — add graph edge
• python3 tools/research_wiki.py rebuild-context-brief wiki/ — rebuild compressed context
• python3 tools/research_wiki.py rebuild-open-questions wiki/ — rebuild knowledge gap map
• python3 tools/research_wiki.py log wiki/ "<message>" — append log entry
• python3 tools/research_wiki.py init wiki/ — initialize wiki (fallback)

Skills（via Skill tool）

• /ingest — referenced when suggesting the user supplement knowledge

Shared References

• .claude/skills/shared-references/citation-verification.md (created in Phase 3)