@oneie/claude 0.5.0 → 0.6.0

package/skills/rag-canary/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: rag-canary
+description: Pattern 7 of the RAG query library - a recall canary. Run a fixed set of known-answer queries and assert the expected source file/chunk comes back in the top-k. If recall degrades (embedding drift, bad sync, data loss), it fails loud and halts downstream RAG work. Triggers when Donal says "rag canary", "is the RAG healthy", "recall test", or on the daily/pre-sprint cron.
+model: claude-haiku-4-5-20251001
+source: oo-internal
+---
+
+# Skill: /rag-canary - RAG Recall Health Check
+
+**Purpose:** Cheap, deterministic confidence that the RAG still retrieves what it should. A set of known-answer queries each expect a specific source file in the top-k. Pass = RAG healthy. Fail = embedding drift / broken sync / data loss → halt downstream RAG-dependent work. Pattern 7 of `docs/rag-query-pattern-library.md`.
+**Output:** `deliverables/_internal/skill-overhaul-2026-05-28/rag-canary-<date>.md` (PASS/FAIL per probe + overall verdict). Cron-safe.
+**Time to run:** <1 min for the default ~12-probe set.
+**Cost:** ~$0.10/run (searches only, no synthesis). Daily cron OK. Hard-cap $1.
+
+---
+
+## HARD RULES
+
+- **Closed-loop non-negotiable.** Each canary probe = one `search_notes` + one `mark_retrieval`. Outcome `mark` if expected file in top-k, `warn` if not (a recall miss).
+- **Deterministic assertion.** A probe PASSES iff the expected `file_path` (or chunk excerpt substring) appears in the top-k results. No fuzzy judgment - it's a regression gate, not an opinion.
+- **Fail loud, halt downstream.** If overall pass-rate < the threshold (default 90%), emit a LOUD failure and recommend halting any RAG-dependent skill (`/rag-fanout`, `/rag-synthesize`, audits that cite RAG) until investigated. Do not silently proceed.
+- **The canary set is version-controlled.** Probes live in `knowledge/rag/canary-set.yaml` (created on first run if absent). Each entry: `query`, `vault`, `expect_file` (or `expect_excerpt`), `k`. Adding/removing probes is a deliberate, reviewed change.
+- **No API model call needed.** Pure retrieval + string assertion → Haiku/deterministic. Rule 15 cost is near-zero; still close the loop.
+
+## When to use
+- Daily / pre-sprint RAG health heartbeat (cron)
+- Before any large RAG-dependent run (a 30-query `/rag-skill-discovery`, an audit that cites RAG)
+- After a vault sync, re-embed, or schema change - confirm recall survived
+- When a chat reports "the RAG isn't finding obvious things" - canary confirms drift vs query problem
+
+**Not for:** answering questions; coverage auditing (that's `/rag-skill-discovery`).
+
+## Input
+**Optional:**
+- `--set <path>` canary set (default `knowledge/rag/canary-set.yaml`)
+- `--threshold <0-1>` min pass-rate before FAIL (default 0.90)
+- `--out <path>` report destination
+- `--add "<query>|<vault>|<expect_file>|<k>"` append a new probe to the set (then exit)
+
+## Default canary set (seed - 12 probes, extend in canary-set.yaml)
+Each is a known-answer fact whose source file is stable:
+1. "OO retainer pricing baseline" → `knowledge/agency/revenue-model.md` (oo-brain or agency-operator)
+2. "Cloudflare Pages 100 project cap" → `.claude/rules/14-cf-pages-economy.md`
+3. "no auto-send client email rule" → `.claude/rules/12-no-auto-email.md`
+4. "em dash ban client-facing" → `.claude/rules/06-output-style.md`
+5. "competitor filtering blocklist Yelp BBB" → `.claude/rules/09-competitor-filtering.md`
+6. "AI ranking GEO delivery SOP" → `sops/ai-ranking/`
+7. "mover niche KPIs competitors" → `knowledge/niches/movers.md`
+8. "form pipeline CF Worker Resend default" → `.claude/rules/16-form-pipeline-default.md`
+9. "model routing Sonnet decides Haiku processes" → `.claude/rules/08-model-routing.md`
+10. "Anthropic API cost preflight rule" → `.claude/rules/15-anthropic-api-cost.md`
+11. "client data source of truth profile.md" → `.claude/rules/02-client-data.md`
+12. "audit coverage gate Kiba Zucity" → `.claude/rules/18-audit-coverage-gate.md`
+
+(All in agency-operator vault. On first run, write these to `knowledge/rag/canary-set.yaml`.)
+
+## Process
+
+### Step 1: Load (or seed) the canary set
+If `knowledge/rag/canary-set.yaml` absent, write the 12 seed probes above. Else read it. Honor `--add`.
+
+### Step 2: Run each probe
+For each: `mcp__search_notes(query, k, vault)`. Record whether `expect_file` (or `expect_excerpt`) is in the top-k. PASS/FAIL per probe.
+
+### Step 3: Verdict
+```markdown
+# RAG Canary - <date>
+## Overall: <pass_count>/<total> = <pct>% — PASS | FAIL (threshold <t>%)
+| # | Query | Vault | Expected | Found@rank | Verdict |
+|---|---|---|---|---|---|
+## On FAIL
+HALT recommendation: do not run RAG-dependent skills until investigated.
+Likely causes: embedding drift, failed sync (.rag-include), vault param wrong, data loss.
+First check: re-run the failing probe with vault=null; check last sync commit.
+```
+
+### Step 4: Close the loop
+`mark_retrieval` per probe: `mark` on PASS, `warn` on FAIL (recall miss is real signal).
+
+### Step 5: Emit
+Write report. Print one line: `RAG CANARY <date>: <pct>% PASS|FAIL (<n>/<total>). <halt note if FAIL>`. Non-zero exit on FAIL (cron-detectable).
+
+## Quality Checks
+- [ ] One mark_retrieval per probe
+- [ ] Assertion is deterministic (expected file in top-k), not fuzzy
+- [ ] FAIL emits a halt recommendation + first-check guidance
+- [ ] canary-set.yaml exists + is the source of probes
+- [ ] Non-zero exit on FAIL
+
+## Escalation rules
+Escalate to Donal immediately if: pass-rate < threshold (RAG integrity issue - this gates other work); a previously-passing probe newly fails (regression - name the probe + likely cause); the canary set itself can't load (missing/corrupt yaml).
+
+## Cost note (Rule 15)
+~12 searches, no synthesis ≈ $0.10. Daily cron ≈ $3/mo. Hard-cap $1. Pure retrieval = Haiku/deterministic.
+
+## Composition
+`composes_with_sesh: false`. A health probe, never a sprint.
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+- Pattern source: `docs/rag-query-pattern-library.md` (Pattern 7)
+- Canary set: `knowledge/rag/canary-set.yaml`
+- Gates: `/rag-fanout`, `/rag-synthesize`, `/rag-skill-discovery`, any RAG-citing audit
+- Closed-loop: CLAUDE.md MCP contract
+- Rules: 08, 15; Sub-plan 15
+
+## Pickup Prompt
+```
+/rag-canary
+/rag-canary --threshold 0.95 --out /tmp/canary.md
+/rag-canary --add "OO chatbot pilot pricing|agency-operator|knowledge/agency/chatbot-pricing.md|5"
+```

package/skills/rag-fanout/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: rag-fanout
+description: Pattern 2 of the RAG query library - decompose one broad question into 5-10 sub-queries, run search_notes for each in parallel across the chosen vault, synthesize across 15-30 chunks into a structured answer with per-chunk citations. Each sub-query fires its own mark_retrieval close-loop. Triggers when Donal asks a broad RAG question, says "fanout this", "fan out", "search RAG with multiple angles", or when /rag-deep-question delegates.
+model: claude-sonnet-4-6
+source: oo-internal
+---
+
+# Skill: /rag-fanout - Multi-Query RAG Fan-Out
+
+**Purpose:** Convert one broad question into N targeted sub-queries, run them in parallel, synthesize the chunks into a cited answer. Pattern 2 of the RAG query library (`docs/rag-query-pattern-library.md`).
+**Output:** Markdown answer with per-claim citations + per-sub-query `mark_retrieval` calls completing the closed-loop contract
+**Time to run:** 2-4 min depending on N sub-queries
+**Cost:** Tier 1 (Max sub, $0 Anthropic) if invoked in-chat. Hard-cap if scripted: ~$2 per invocation at N=6, k=3.
+
+---
+
+## HARD RULES
+
+- **Closed-loop is non-negotiable.** Every `search_notes` call MUST be followed by `mark_retrieval(query_id, outcome)` before the skill returns. Skipping pollutes the `retrieval_outcomes` table. Outcomes: `mark` (chunks helped) / `warn` (didn't help) / `unsure` (couldn't tell).
+- **Default vault per question.** Operational questions → `agency-operator`. Frameworks / courses / intel → `oo-brain`. Personal → `personal-brain`. Cross-cutting → `vault=null`. Skill auto-routes per question keywords; operator can override with `--vault`.
+- **Sub-query cap = 10.** Above that, the synthesis loses coherence and cost climbs. Operator gets `--max-subqueries` flag but skill refuses N>15.
+- **Dedup for cost (sub-token discipline, per `docs/rag-cost-optimization.md`).** (a) Before firing, drop near-duplicate sub-queries (same core terms) - saves OpenAI embeddings AND the duplicate chunks they'd return. (b) Before synthesis, dedup chunks by id / file+offset - fan-out's N×k returns overlap; ~18 raw → ~10-12 unique = ~35% fewer synthesis input-tokens for free. Cheapest win available; do it every run.
+- **W1-W4 routing per `feedback_w1_w4_sandwich_default_for_multi_step_builds`:** W1 (decompose) = Haiku. W2 (judge sub-queries) = Sonnet. W3 (synthesize) = Sonnet. W4 (verify citations) = Haiku.
+- **Citation traceability mandatory.** Every claim in the synthesis cites at least one source chunk by file path + chunk excerpt. No claim without source = hallucination risk.
+
+---
+
+## When to use
+
+- Broad research questions: "How should we price the chatbot pilot?" / "What's the OO strategy for AI ranking 2026?" / "What patterns do we have for Hostinger cutovers?"
+- Pre-call prep where one angle isn't enough
+- Cross-topic synthesis (e.g. "what's our position on chatbot + ads + AI ranking combined")
+- When Pattern 1 (single query) returns weak hits and you want to widen the net
+
+**Not for:** narrow factual lookups (Pattern 1 is faster); time-sensitive recall tests (Pattern 7); persona-driven questions (Pattern 10 / `/persona-council`); adversarial framing (Pattern 12 / `/rag-adversarial`).
+
+---
+
+## Input
+
+**Required:**
+- `<question>` - natural-language broad question (positional arg or stdin)
+
+**Optional:**
+- `--vault <name>` - override auto-routing (oo-brain | agency-operator | personal-brain | null for cross-vault)
+- `--max-subqueries <N>` - cap on sub-query count (default 6, max 10)
+- `--k <N>` - chunks per sub-query (default 3, max 5)
+- `--out <path>` - write synthesis to file instead of stdout
+- `--dry-run` - emit the sub-query list without firing search_notes (preview the decomposition)
+- `--no-mark` - skip mark_retrieval (DANGEROUS - violates closed-loop contract; only for debugging)
+
+---
+
+## Process
+
+### Step 1 (W1, Haiku): Decompose the question
+
+Read the question. Identify:
+- The CORE concept (one phrase capturing the question's essence)
+- 4-8 ANGLES that illuminate the question (different facets: pricing / competitive / historical / framework / niche / risk / etc.)
+
+Generate sub-queries. Each sub-query is a focused search string (NOT a question - search_notes does keyword + vector search, not Q&A).
+
+Example for "How should we price the chatbot pilot?":
+- Core: "chatbot pilot pricing"
+- Angles:
+  - "chatbot pilot pricing tiers"
+  - "BOQ pilot 1 spec pricing"
+  - "Hormozi value-based pricing chatbot"
+  - "Tony McKinsey chatbot economics"
+  - "competitor chatbot retainer pricing 2026"
+  - "OO retainer chatbot upsell pricing history"
+
+**Acceptance check:** sub-query count between 4 and `--max-subqueries`. Each sub-query is concrete (not "things related to X" generic).
+
+### Step 2 (--dry-run exit): Preview decomposition
+
+If `--dry-run`: print the sub-query list + chosen vault + estimated cost. Exit. No search_notes calls.
+
+### Step 3 (W2, Sonnet): Vault routing
+
+Determine vault per question keywords:
+
+| Question signal | Vault |
+|---|---|
+| "OO clients" / "retainer" / "Tomas" / "John" / specific skill / SOP | agency-operator |
+| "course" / "Hormozi" / "Tony" / "framework" / "intel" / scraped content | oo-brain |
+| Personal (health / lifestyle / cycle / persona) | personal-brain |
+| Cross-cutting OR uncertain | null (search all vaults) |
+
+If `--vault` flag passed: skip auto-routing, use the explicit vault.
+
+### Step 4 (W3, Sonnet → Haiku fan-out): Run sub-queries in parallel
+
+For each sub-query:
+1. Call `mcp__search_notes(query=sub_query, k=<k>, vault=<vault>)`
+2. Capture: `query_id`, top-k chunks (each: file_path, chunk_excerpt, score)
+3. Track in working set
+
+**Acceptance check:** every sub-query returned at least 1 chunk OR was tracked as zero-hit (zero-hit is meaningful signal for skill-discovery).
+
+### Step 5 (W3, Sonnet): Synthesize across chunks
+
+Aggregate all chunks (typically 15-30 chunks for N=6, k=3-5). Synthesize into a structured answer:
+
+```markdown
+# <question> - Fan-out Synthesis
+
+## TL;DR
+<2-3 sentence answer to the question>
+
+## Per-angle findings
+
+### <angle 1>
+- <fact / framework / data point> [source: <file_path>, "<chunk excerpt>"]
+- <fact / framework / data point> [source: <file_path>, "<chunk excerpt>"]
+
+### <angle 2>
+[same shape]
+
+## Cross-angle synthesis
+<what emerges when angles combine - the real answer to the broad question>
+
+## Gaps surfaced (potential skill candidates)
+<sub-queries that returned zero or weak hits = skill gaps - feed to /rag-skill-discovery>
+
+## Sub-queries fired (with mark status)
+| Sub-query | Vault | k | Chunks | Status |
+|---|---|---|---|---|
+| <q1> | <v> | <k> | <count> | mark/warn/unsure |
+```
+
+**Acceptance check:** every claim in TL;DR + Per-angle findings has at least one citation. Cross-angle synthesis cites at least 3 distinct files.
+
+### Step 6 (W4, Haiku): Close the loop
+
+For each sub-query in the working set, call `mcp__mark_retrieval(query_id, outcome, notes)`:
+- `mark` if at least 1 chunk made it into the synthesis
+- `warn` if 0 chunks were useful (low score AND no fit to synthesis)
+- `unsure` if chunks returned but couldn't be classified
+
+If `--no-mark` flag: SKIP this step + emit a loud warning to stdout. Default behavior: mark all.
+
+**Acceptance check:** mark_retrieval count == search_notes count. No orphan queries.
+
+### Step 7: Emit + log
+
+If `--out <path>`: write synthesis to file.
+Otherwise: print to stdout.
+
+Always print summary:
+```
+RAG FAN-OUT: <N> sub-queries fired, <M> useful chunks, <K> gaps surfaced.
+Synthesis: <path or "stdout">
+Closed-loop: <N>/<N> marked (mark=<x> warn=<y> unsure=<z>).
+```
+
+---
+
+## Quality Checks
+
+Before marking done:
+
+- [ ] Sub-query count 4-10
+- [ ] Every search_notes had a paired mark_retrieval (unless --no-mark)
+- [ ] Every claim in TL;DR + Per-angle has a citation
+- [ ] Cross-angle synthesis cites at least 3 distinct files
+- [ ] Zero-hit sub-queries flagged in "Gaps surfaced" section
+- [ ] Vault auto-routing matches question signals (or --vault used)
+- [ ] Summary printed to stdout
+
+---
+
+## Escalation rules
+
+Escalate to Donal if:
+- All sub-queries return zero hits (RAG quality issue OR vault choice wrong - try `--vault=null`)
+- 50%+ sub-queries returned chunks but synthesis couldn't be cited (hallucination risk)
+- Cost exceeds estimated cap (rate-limit or k=5 expansion)
+- Cross-vault routing returns contradictions (e.g. agency-operator says X, oo-brain says NOT-X)
+- Question is genuinely a Pattern 9 (decomposition agent) candidate - hand off to `/rag-deep-question` when that skill ships
+
+---
+
+## Cost note (per Rule 15)
+
+- N=6 sub-queries × k=3 chunks each = ~18 chunks input to synthesis
+- W1 decompose: Haiku, ~$0.05
+- W3 synthesize: Sonnet, ~$0.30 for 18 chunks + Q + structure
+- Total typical: ~$0.40 per invocation
+- Hard-cap recommended: $2 (allows for N=10, k=5 if needed)
+- Tier 1 in-chat: $0 (Max sub absorbs)
+
+If invoked at batch / script time: pass `--hard-cap-usd 2` to the wrapping script.
+
+---
+
+## Composition
+
+`composes_with_sesh: false`. /rag-fanout is a single-shot synthesis, not a multi-day sprint. Results live in stdout or `--out <path>`; sprint folder not needed.
+
+If a particular fan-out reveals a multi-day investigation worth pursuing, operator runs `/sesh new <slug>` separately and references the fan-out output as input.
+
+---
+
+## Live test (post-ship)
+
+Recommended first invocation (Pattern 6 cross-check):
+
+```
+/rag-fanout "what skills do we have for handling Hostinger to CF Pages cutovers"
+```
+
+Expected: 6 sub-queries fire, agency-operator vault auto-routes, synthesis surfaces /hosting-cutover + /cf-zone-runbook-generate + /mail-provider-preservation-table + /prelaunch-checklist + /form-spam-fix as the existing skill cluster. Any gaps surfaced = skill-discovery signal.
+
+---
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+
+- Pattern source: `agency-operator/docs/rag-query-pattern-library.md` (Pattern 2)
+- MCP tool spec: `agency-operator/docs/oo-brain-rag.md`
+- Closed-loop contract: CLAUDE.md "OO-Brain MCP - Closed-Loop Retrieval Contract"
+- Sibling skills (to be shipped): /rag-triangulate / /rag-skill-discovery / /rag-synthesize / /rag-deep-question / /rag-canary / /rag-adversarial / /persona-council
+- Memory rules: `feedback_w1_w4_sandwich_default_for_multi_step_builds`, `feedback_dry_trigger_for_new_skills`
+- Rule 08 (model routing - W1-W4 enforcement)
+- Rule 15 (cost discipline - hard-cap)
+- Sub-plan: `Plans/2026-05-28/big-skill-overhaul/15-rag-query-pattern-library.md`
+
+---
+
+## Pickup Prompt
+
+```
+/rag-fanout "<broad question>"
+/rag-fanout "<broad question>" --vault=oo-brain --max-subqueries=8 --k=5
+/rag-fanout "<question>" --dry-run    # preview the decomposition
+/rag-fanout "<question>" --out /tmp/synthesis-<topic>.md
+```

package/skills/rag-skill-discovery/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: rag-skill-discovery
+description: Pattern 6 of the RAG query library - run a batch of "what skill should I use for X" test queries against the agency-operator vault, score whether a clearly-matching skill description comes back, and emit a skill-coverage report. Weak/zero hits = skill gaps. Triggers when Donal says "what skills are we missing", "run skill discovery", "skill coverage report", or on the weekly cron (Phase 3).
+model: claude-sonnet-4-6
+source: oo-internal
+---
+
+# Skill: /rag-skill-discovery - RAG-Driven Skill Gap Finder
+
+**Purpose:** Probe the skill library THROUGH the RAG. For each common "what do I do when X" ask, search the agency-operator vault; if the top hits aren't a clearly-matching skill, that's a gap. Turns the RAG into a coverage auditor. Pattern 6 of `docs/rag-query-pattern-library.md`.
+**Output:** `deliverables/_internal/skill-overhaul-2026-05-28/skill-coverage-<date>.md` - per-query coverage verdict + ranked gap list feeding sub-plan 01 / 12 / `/skill-gap-finder`.
+**Time to run:** 3-6 min for the default 30-query set.
+**Cost:** Tier 1 in-chat $0. Scripted ~$2/run (30 searches + Sonnet grading). Hard-cap $5.
+
+---
+
+## HARD RULES
+
+- **Closed-loop non-negotiable.** Each test query fires one `search_notes` + one `mark_retrieval`. 30 queries = 30 marks. No orphans.
+- **Skills are OUT of RAG scope by design.** Per CLAUDE.md Phase 11, `.claude/skills/**` is NOT indexed. So this skill matches against skill DESCRIPTIONS via the live skill list (read `.claude/skills/*.md` frontmatter `description:` fields), NOT via search_notes on skill bodies. search_notes probes whether KNOWLEDGE/SOPs exist; the skill-name match is a separate file-read step. Do not expect search_notes to return skill files.
+- **A gap = no clearly-matching skill description AND weak knowledge hits.** If a skill exists but its description doesn't match the ask, that's a DESCRIPTION gap (routing problem), logged separately from a CAPABILITY gap (no skill at all).
+- **Never invent a skill that exists.** Before flagging a CAPABILITY gap, grep the live skill list - the gap is real only if no skill's description covers the ask.
+- **W1-W4:** W1 (load query set + skill descriptions) Haiku · W2/W3 (grade coverage) Sonnet · W4 (close loop) Haiku.
+
+## When to use
+- Weekly skill-coverage heartbeat (Phase 3 cron)
+- After a niche/ICP expansion ("we now take tax-prep clients - are we covered?")
+- Pre-quarterly-review skill audit
+- When `/rag-fanout` or `/rag-triangulate` surfaces a [BUILD] gap and you want to confirm it against the full query set
+
+**Not for:** answering a real question (this probes coverage, not content); single-skill lookup.
+
+## Input
+**Optional:**
+- `--query-set <path>` custom query file (one ask per line). Default: the built-in 30-ask set below.
+- `--niche <slug>` inject niche-specific asks from `knowledge/niches/<slug>.md`
+- `--out <path>` report destination
+- `--threshold <0-1>` match-confidence below which an ask is flagged (default 0.5)
+
+## Default query set (30 common Donal asks - extend over time)
+Mover prospect · dentist niche · roofer niche · tax-prep niche (likely gap) · Hostinger→CF cutover · diagnostic snapshot dental · AI visibility audit cold prospect · warm lead closing package · monthly retainer report · client churn save · reprice conversation · cold email sequence · LinkedIn outreach · sales deck post-discovery · pre-call brief · DNS zone snapshot · form spam fix · schema deploy · GMB optimization · review-generation campaign · backlink audit · competitor SERP analysis · i18n/multilingual audit · ads account audit · landing page CRO · VSL video outreach · enterprise/RFP plan · strat hub for tier-1 lead · R&D idea capture · plan health check.
+
+## Process
+
+### Step 1 (W1, Haiku): Load
+- Read the query set (default 30 or `--query-set`).
+- Read live skill descriptions: `grep -h "^description:" .claude/skills/*.md .claude/skills/*/SKILL.md`.
+
+### Step 2 (W3): Probe each ask
+For each ask:
+1. `mcp__search_notes(query="<ask> SOP process steps", k=5, vault="agency-operator")` - tests whether KNOWLEDGE backs the ask.
+2. Match the ask against the loaded skill descriptions (keyword + intent). Record best-match skill + confidence.
+
+### Step 3 (W2/W3, Sonnet): Grade coverage
+Per ask, assign a verdict:
+- **COVERED** - a skill description clearly matches AND/OR strong knowledge hits.
+- **DESCRIPTION-GAP** - a capable skill exists but its `description:` wouldn't route this ask (fix the description).
+- **CAPABILITY-GAP** - no matching skill AND weak/zero knowledge hits → BUILD candidate.
+
+```markdown
+# Skill Coverage Report - <date>
+## Summary: <COVERED>/<DESC-GAP>/<CAP-GAP> of <N> asks
+## Per-ask
+| Ask | Best-match skill | Conf | Knowledge hits | Verdict |
+|---|---|---|---|---|
+## Capability gaps (BUILD candidates, ranked by ask-frequency)
+## Description gaps (cheap fixes - reword the skill `description:`)
+```
+
+### Step 4 (W4, Haiku): Close the loop
+`mark_retrieval` per probe: `mark` if knowledge hits informed the verdict, `warn` if zero/irrelevant, `unsure` if ambiguous.
+
+### Step 5: Emit + route
+Write report to `--out` (default `deliverables/_internal/skill-overhaul-2026-05-28/skill-coverage-<date>.md`). Print summary. Append CAPABILITY-GAPs to sub-plan 12 gap catalog + flag to `/skill-gap-finder`.
+
+## Quality Checks
+- [ ] One mark_retrieval per search_notes
+- [ ] Every CAPABILITY-GAP verified against the live skill list (not a skill that already exists)
+- [ ] DESCRIPTION-GAPs separated from CAPABILITY-GAPs
+- [ ] Gaps ranked by ask-frequency / business value
+- [ ] Report written + summary printed
+
+## Escalation rules
+Escalate to Donal if: >30% of asks are CAPABILITY-GAPs (library has a real hole or query set is mis-calibrated); a high-frequency ask (mover/dentist/roofer - core niches) is a gap; DESCRIPTION-GAPs cluster (the routing layer needs a sweep, not point fixes).
+
+## Cost note (Rule 15)
+30 searches × k=5 + Sonnet grading ≈ $2. Hard-cap $5. Weekly cron ~$8/mo. Tier 1 in-chat $0.
+
+## Composition
+`composes_with_sesh: false`. Produces a report, not a sprint. A confirmed cluster of gaps may spawn `/sesh new skill-gap-fill-<date>`.
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+- Pattern source: `docs/rag-query-pattern-library.md` (Pattern 6)
+- Consumes gaps from: `/rag-fanout`, `/rag-triangulate`
+- Feeds: sub-plan 01 (discovery wave), sub-plan 12 (gap catalog), `/skill-gap-finder`
+- Niche data: `knowledge/niches/<slug>.md`
+- Rules: 08, 15; Sub-plan 15
+- Phase 3 cron: this skill is the weekly-run target.
+
+## Pickup Prompt
+```
+/rag-skill-discovery
+/rag-skill-discovery --niche movers
+/rag-skill-discovery --query-set /tmp/my-asks.txt --out /tmp/coverage.md
+```

package/skills/rag-synthesize/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: rag-synthesize
+description: Pattern 8 of the RAG query library - pull a wide slice (k up to 20) on one topic from a vault and synthesize it into a structured 2-3 page document with per-claim citations to source files. For "give me everything we have on X as a written brief". Triggers when Donal says "synthesize everything on X", "write up what we know about X", "RAG brief on X", or when /rag-fanout's breadth isn't enough and depth on ONE topic is wanted.
+model: claude-sonnet-4-6
+source: oo-internal
+---
+
+# Skill: /rag-synthesize - Wide-Slice Topic Synthesis
+
+**Purpose:** One topic, one deep retrieval (k up to 20), one structured written synthesis. Where `/rag-fanout` widens via many sub-queries, this deepens via one wide query - turning a scattered knowledge base into a readable brief with citations. Pattern 8 of `docs/rag-query-pattern-library.md`.
+**Output:** A 2-3 page markdown brief (TL;DR → themed sections → open questions) with every claim cited to a source file, written to `--out` (default `/tmp/synthesis-<topic>.md`).
+**Time to run:** 2-4 min.
+**Cost:** Tier 1 in-chat $0. Scripted ~$0.40 (1 wide search + Sonnet synthesis of ~20 chunks). Hard-cap $2.
+
+---
+
+## HARD RULES
+
+- **Closed-loop non-negotiable.** The wide search fires one `search_notes` + one `mark_retrieval` before return.
+- **Every claim cites a source file.** A synthesis without per-claim citations is indistinguishable from a hallucination. No source = cut the claim or label it `[inference, not in corpus]`.
+- **Synthesize, don't concatenate.** The output is a coherent brief that finds the THREADS across chunks - not 20 bullet points pasted in retrieval order. Group by theme, resolve overlaps, note contradictions.
+- **Wide-slice cap = 20 chunks.** Above 20 the synthesis dilutes and cost climbs. `--k` max 20.
+- **Recall gate.** If the wide search returns <3 chunks, the topic is thin in the corpus - say so plainly ("corpus has limited coverage of <topic>") rather than padding.
+- **W1-W4:** W1 (frame query + vault) Haiku · W3 (synthesize) Sonnet · W4 (close loop + citation check) Haiku.
+
+## When to use
+- "Write up everything we know about chatbot pilots" / "synthesize our AI-ranking position" / "brief on our cutover playbook"
+- Onboarding a new topic area into a single readable doc
+- Pre-deck / pre-proposal source-gathering on one theme
+- Converting scattered intel into a citeable internal reference
+
+**Not for:** broad multi-angle questions (`/rag-fanout`); coverage audits (`/rag-skill-discovery`); narrow facts (Pattern 1).
+
+## Input
+**Required:** `<topic>` - the subject to synthesize.
+**Optional:**
+- `--vault <name>` (auto-routes per topic; override available)
+- `--k <N>` chunks to pull (default 15, max 20)
+- `--out <path>` (default `/tmp/synthesis-<topic-slug>.md`)
+- `--audience <internal|client>` - if `client`, apply Rule 06 (no em dashes) + plain-English framing
+- `--dry-run` show the query + vault + k, no fire
+
+## Process
+
+### Step 1 (W1, Haiku): Frame
+Turn the topic into a wide search string. Pick the vault (operational → agency-operator; intel/courses → oo-brain; cross → null).
+
+### Step 2 (W3): Wide retrieval
+`mcp__search_notes(query=<topic>, k=<k>, vault=<vault>)`. Capture query_id + chunks (file_path, excerpt, score). If <3 chunks, note thin coverage.
+
+### Step 3 (W3, Sonnet): Synthesize
+```markdown
+# <Topic> - Synthesis (<date>)
+_Sources: <N> chunks from <vault>; generated by /rag-synthesize_
+
+## TL;DR
+<3-5 sentence distillation>
+
+## <Theme 1>
+<synthesized narrative> [source: <file>, "<excerpt>"]
+
+## <Theme 2>
+...
+
+## Contradictions / tensions
+<where sources disagree, named explicitly>
+
+## Open questions / thin spots
+<what the corpus does NOT cover - feeds skill/research gaps>
+
+## Sources cited
+- <file_path> (<n> chunks)
+```
+If `--audience client`: scan for em dashes (Rule 06), use plain English, drop internal jargon.
+
+### Step 4 (W4, Haiku): Citation check + close loop
+- Verify every section claim has a `[source: ...]`. Flag any uncited claim.
+- `mark_retrieval(query_id, mark|warn|unsure)`: `mark` if chunks fed the brief.
+
+### Step 5: Emit
+Write to `--out`. Print: `SYNTHESIS: <topic> | <N> chunks | <themes> themes | <uncited> uncited claims | → <path> | closed-loop 1/1.`
+
+## Quality Checks
+- [ ] mark_retrieval fired for the search
+- [ ] Every claim cited (or explicitly `[inference]`)
+- [ ] Output is themed synthesis, not retrieval-order bullets
+- [ ] Contradictions + thin spots sections present
+- [ ] If `--audience client`: zero em dashes, plain English
+- [ ] Thin coverage (<3 chunks) stated honestly, not padded
+
+## Escalation rules
+Escalate to Donal if: the topic returns thin coverage but is business-critical (research/build gap); sources contradict on something material (don't auto-pick a side); `--audience client` output would make a claim we can't verify (Rule 06 verify-before-cite - flag it).
+
+## Cost note (Rule 15)
+1 wide search + Sonnet over ~15-20 chunks ≈ $0.40. Hard-cap $2. Tier 1 in-chat $0.
+
+## Composition
+`composes_with_sesh: false`. Produces one document. If the synthesis seeds a multi-day effort, `/sesh new` separately and cite this brief as input.
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+- Pattern source: `docs/rag-query-pattern-library.md` (Pattern 8)
+- Sibling: `/rag-fanout` (breadth), `/rag-deep-question` (decomposition then synthesis)
+- Rule 06 (client-facing output, em-dash ban), Rules 08, 15
+- Sub-plan 15
+
+## Pickup Prompt
+```
+/rag-synthesize "chatbot pilots"
+/rag-synthesize "our AI ranking position 2026" --vault oo-brain --k 20
+/rag-synthesize "cutover playbook" --audience internal --out /tmp/cutover-brief.md
+```