# arc-querying-obsidian Design

## Vision

The missing third leg of the Karpathy triad. A Workflow skill that answers questions against the Obsidian vault using a structured pipeline: Orient → Search → Read → Synthesize → File Back. Completes the Write → Query → Audit cycle so that every question potentially grows the wiki.

The core insight from Karpathy: without Query as a formal operation, insights from asking questions evaporate into chat history. With it, explorations compound just like ingested sources.

## Architecture Decision

### New standalone skill — `arc-querying-obsidian`

Three operations, three skills. Clean separation of concerns:
- `arc-writing-obsidian` — creates artifacts (Ingest)
- `arc-querying-obsidian` — retrieves knowledge (Query)
- `arc-auditing-obsidian` — maintains the graph (Lint)

### Pipeline

```
Orient → Search → Read → Synthesize → (File Back)
```

1. **Orient** — Read `index.md` (generated by auditor's LINT) for vault scope. Fall back to `obsidian-cli files` if index doesn't exist.

2. **Search** — Use `obsidian-cli search` with strategy based on question type:
   - Topic exploration → keyword search, check MOCs first
   - Relationship query → search both terms, follow `## Relationships` sections
   - Recent activity → search + sort by `created:` date, check `log.md`
   - Comprehensive summary → start from MOC, expand to linked notes

3. **Read** — Drill into matching notes. Read frontmatter for type, then content. For Syntheses, follow `sources:` array to trace provenance.

4. **Synthesize** — Answer with `[[citations]]` to wiki pages. Output format adapts:
   - Explanation → Markdown prose with citations
   - Comparison → Table with cited cells
   - Timeline → Chronological list from `created:` dates
   - Overview → Structured summary with links to deeper notes

5. **File Back** (optional) — If the answer is substantive (not a quick lookup), suggest filing via `arc-writing-obsidian` Query-as-Ingest.

### Delegation Model

Writer is source of truth for schema. Querier delegates:
- Search/read operations → `obsidian-cli`
- File-back → `arc-writing-obsidian` (Query-as-Ingest)
- Vault conventions → references writer's schema, doesn't duplicate

### Error Handling

| Scenario | Behavior |
|---|---|
| `index.md` missing | Fall back to `obsidian-cli files` + suggest running `/arc-auditing-obsidian lint` |
| obsidian-cli unavailable | Report error clearly — don't guess |
| 0 search results | "Your vault has no notes about X." Suggest ingesting via writer |
| 20+ results | Narrow by type or date, prioritize MOCs and Syntheses |
| Question outside vault scope | Answer from general knowledge but flag: "This is from training, not your vault" |

### Skill Metadata

- **Name:** `arc-querying-obsidian`
- **Type:** Workflow (sequential pipeline with handoff to writer)
- **Tier:** Standard (<1000 words)
- **Triggers:** "What do I know about...", "search my vault for...", "how does X relate to Y in my notes?", "what's the latest on X?"

---

<!-- REFINER_INPUT_START -->

## Requirements for Refiner

### Functional Requirements

- REQ-F001: Querier reads `index.md` first for vault orientation before searching
- REQ-F002: Querier uses `obsidian-cli search` to find relevant notes
- REQ-F003: Answers cite wiki pages using `[[wikilinks]]`, not raw sources
- REQ-F004: Output format adapts to question type (prose, table, timeline, overview)
- REQ-F005: Substantive answers trigger file-back suggestion via `arc-writing-obsidian` Query-as-Ingest
- REQ-F006: Clearly distinguishes vault knowledge from general knowledge in answers
- REQ-F007: Falls back gracefully when `index.md` doesn't exist
- REQ-F008: Appends query activity to `log.md` using writer's format

### Non-Functional Requirements

- REQ-N001: Skill stays under 1000 words (Standard tier)
- REQ-N002: No page type schema duplication — references writer as source of truth
- REQ-N003: Vault path resolution follows same 3-step pattern as sibling skills

### Constraints

- Delegates to `obsidian-cli` for all vault operations (search, read, backlinks)
- Delegates to `arc-writing-obsidian` for file-back (Query-as-Ingest)
- Never modifies existing notes — querier is read-only (auditor modifies, writer creates)
- Page type schema defined by writer — querier references it
<!-- REFINER_INPUT_END -->
