@diottodev/runic 1.0.0 → 1.1.0

package/research/research/skills/research/references/deterministic_classification_canon.md

@@ -0,0 +1,162 @@
+# Deterministic Classification — Why Keyword Beats LLM-Reasoned For Routing
+
+This reference answers one decision: **should the routing classifier use deterministic keyword matching or LLM reasoning over the query?** The answer is **deterministic keyword matching** for query-routing purposes, with LLM reasoning reserved for cases where keyword matching has genuinely exhausted the signal space.
+
+## The Trade-Off Spectrum
+
+| Approach | Latency | Cost | Determinism | Debuggability | Coverage of fuzzy intent |
+|---|---|---|---|---|---|
+| **Keyword + intent signals** (this skill) | <1ms | $0 | 100% | High (signals named explicitly) | Low |
+| **Embedding similarity to specialist descriptions** | ~10-100ms | Cents/100K queries | High (deterministic given embeddings) | Medium (need to inspect cosine scores) | Medium |
+| **LLM reasoning over query + specialist list** | ~500ms-2s | ~$0.001-0.01/query | Low (same query → varied outputs) | Low (prompt-dependent) | High |
+
+The trade-off: as you move down the table, coverage of fuzzy intent improves, but latency, cost, and unpredictability all worsen. The right choice depends on how predictable + auditable the routing needs to be.
+
+## For Query Routing, Determinism Wins
+
+Routing is **fundamentally a control-flow decision**: it determines which subsystem runs next. Like any control-flow decision in software, predictability + auditability are first-order properties.
+
+Compare to other deterministic control-flow systems:
+
+- **Compilers** use deterministic lexer + parser, not LLMs.
+- **Routers** (network sense) use deterministic CIDR matching, not LLMs.
+- **CI/CD systems** use deterministic file-pattern triggers, not LLMs.
+- **Linters + formatters** use deterministic AST-walking, not LLMs.
+
+These are all systems where users need to predict + debug behavior. LLM-reasoned routing in any of them would be a regression. Same applies to skill routing.
+
+## The Bracketed-Placeholder Anti-Pattern
+
+A common mistake when building keyword classifiers: using bracketed placeholders as signals.
+
+**Wrong:**
+```python
+SIGNALS = {
+  dossier: ["dossier on [company]", "background check on [person]", "research [entity]"]
+}
+```
+
+**Why wrong:** the "research [entity]" pattern collapses to "research" as a substring match, which matches every research request ever. The signal over-triggers + breaks the classifier.
+
+**Right:**
+```python
+SIGNALS = {
+  dossier: ["dossier on", "background check", "background on", "competitor research"]
+}
+```
+
+**Why right:** verb-noun pairs ("dossier on", "background on", "competitor research") are specific to dossier intent. Generic "research X" stays in fallback territory until paired with a specialist-specific noun.
+
+This is the post-PR-#657-audit lesson encoded as a hard rule.
+
+## What Counts As A "Signal"
+
+A signal is a **case-insensitive literal phrase (multi-word substring)** that, when present in the user's question, indicates a specialist domain. Good signals are:
+
+- **Specific enough** that they don't appear in unrelated queries (good: "literature review", bad: "research")
+- **Common enough** that users actually say them (good: "due diligence", bad: "actuarial diligence assessment framework")
+- **Diverse enough** to cover surface variations (good: "lit review" + "literature review" + "litreview"; bad: only one form)
+- **Verb-noun-paired** when the noun alone is ambiguous (good: "dossier on" + "background on"; bad: just "company name")
+
+## Confidence Thresholds
+
+The skill commits to a specialist at **≥2 signals** for two reasons:
+
+1. **2 signals reliably indicate intent.** "PICO + meta-analysis" doesn't show up in unrelated queries.
+2. **1 signal isn't strong enough.** "PICO" alone might be a clinical question, a syllabus question, or a litreview question. The second signal distinguishes.
+
+The single-weak-match exception (1 signal + only one specialist with any score) handles the case where the user used a highly specific phrase that no other specialist's signals overlap with. "What's the FTO landscape" → only patent has any score → route to patent even though it's just 1 signal.
+
+The "ask Q3 disambiguation" exception handles the case where multiple specialists each have score 1, OR no specialist has any score. Both indicate genuine ambiguity that the classifier can't resolve.
+
+## What Goes Wrong With LLM-Reasoned Classification
+
+### Non-determinism
+
+Same query, different responses across invocations. User says "what are people saying about X" — sometimes routes to pulse, sometimes to dossier, sometimes to fallback. User can't develop intuition for the system.
+
+### Cost
+
+500ms-2s per classification × hundreds of routing decisions/day adds up. Deterministic classifier is sub-millisecond + free.
+
+### Debuggability
+
+When LLM routes "weirdly," there's no signal to inspect. With deterministic classification, the user sees "matched signals: PICO, meta-analysis" and understands why.
+
+### Prompt drift
+
+LLM classifier behavior changes when the underlying model version changes. Deterministic classifier behavior is locked to the signals list. Auditable + reproducible.
+
+## What Goes Wrong With Pure Keyword Classification
+
+### Fuzzy intent
+
+User says "I want to understand what the academic community thinks about CRISPR safety." No keyword matches litreview signals (no "PICO", no "systematic review", no "literature review"). Classifier punts to fallback even though litreview was the right answer.
+
+**Mitigation:** Q3 disambiguation handles this. User picks "academic literature" → routes to litreview. The architecture's clarification path covers the fuzzy-intent case.
+
+### Surface-form proliferation
+
+Users say "lit review", "literature review", "litreview", "review the literature on", "review papers on", "look at the papers about", "what does the research say about" — that's 7 surface forms for the same intent. Signals list grows.
+
+**Mitigation:** Cover the top-N surface forms (3-5 per specialist). Let Q3 handle the long tail.
+
+### Polysemy
+
+"Patent" could mean a legal patent (route to patent specialist) OR a medical term ("the symptoms are patent" = obvious). Keyword matching can't distinguish.
+
+**Mitigation:** Multi-signal requirement reduces false positives. "Patent + prior art" is unambiguously patent intent.
+
+## The Right Hybrid: Deterministic First, Clarify When Stuck
+
+The architecture combines:
+
+1. **Deterministic classification** for the high-confidence path (cheap + fast + predictable)
+2. **Q3 disambiguation** for the genuinely-ambiguous path (LLM-free; user picks from 7 options)
+3. **Fallback workflow** for the no-specialist path
+
+This is strictly better than pure-LLM classification (cheaper, faster, more predictable) and strictly better than pure-keyword classification (handles fuzzy intent via Q3).
+
+## Operational Discipline
+
+When adding a new signal to the SIGNALS map:
+
+- [ ] Verify the signal doesn't appear in queries that should route elsewhere (false positive check)
+- [ ] Verify the signal does appear in queries that should route to this specialist (false negative check)
+- [ ] Check for case-insensitivity (the matcher is case-insensitive, but be explicit)
+- [ ] Avoid bracketed placeholders
+- [ ] Use verb-noun pairs when the noun alone is ambiguous
+- [ ] Document why this signal was added (which queries it covers)
+
+When removing a signal:
+
+- [ ] Check what queries previously routed via this signal
+- [ ] Confirm they still route correctly (via another signal OR via Q3)
+- [ ] Update the documentation
+
+## Tooling
+
+`scripts/classifier.py` implements the deterministic SIGNALS-matching algorithm. Use it; don't re-implement. It returns:
+
+- `route_to`: specialist name OR "fallback"
+- `confidence`: "high (N signals)" OR "weak (1 signal, single specialist)" OR "ambiguous"
+- `matched_signals`: dict of specialist → list of matched phrases
+- `scores`: dict of specialist → integer score
+
+The CLI: `classifier.py --question "..." --output json`.
+
+## Citations (7 sources)
+
+1. **Aho, Sethi, Ullman — "Compilers: Principles, Techniques, and Tools" (Dragon Book, 1986).** Source for the deterministic lexer + parser as the canonical control-flow classifier in software. Compilers don't use LLMs for tokenization; routing shouldn't either.
+
+2. **Cisco IOS — Access Control List (ACL) implementation guides.** Source for the deterministic CIDR-matching pattern in network routing. Predictability + auditability are first-order requirements; same applies to skill routing.
+
+3. **Google Search Engineering blog — Query Classification (2020+).** Source for the production-grade query-classification pattern. Google uses deterministic signal matching as the first layer + LLM reasoning only for residual queries that signals miss. Same architecture as this skill (Q3 as the LLM-equivalent escape hatch).
+
+4. **Mikolov et al. — "Distributed Representations of Words and Phrases" (Word2Vec, 2013).** Source for the embedding-similarity baseline. Embeddings are an intermediate point between keywords + LLM reasoning; this skill chooses keywords for cost + determinism reasons but acknowledges embedding-similarity as a valid alternative.
+
+5. **Karpathy, Andrej — "Software 2.0" (blog post, 2017).** Source for the framing that not everything should be ML. Deterministic systems (compilers, routers, type checkers) remain superior for control-flow decisions even in the LLM era. https://karpathy.github.io/2017/11/11/software-2-0/
+
+6. **Anthropic — Tool Use + Function Calling documentation.** Source for the production pattern of LLM-routes-to-deterministic-tool: the LLM decides intent at the top level, then deterministic tools handle the actual work. Same shape as this skill (intake → deterministic classifier → specialist tool). https://docs.anthropic.com/
+
+7. **NIST — "Information Retrieval Evaluation" (TREC reports).** Source for the canonical evaluation methodology for classifiers: precision + recall measured against held-out queries. Keyword classifiers reliably outperform LLM-reasoned classifiers on precision for domain-specific routing tasks. https://trec.nist.gov/

package/research/research/skills/research/references/fallback_workflow_canon.md

@@ -0,0 +1,214 @@
+# Fallback Workflow Canon — Plan / Decompose / Search / Synthesize / Cite
+
+This reference answers one decision: **when no specialist matches, what workflow does the orchestrator run instead?** The answer is an **8-step plan-decompose-multi-source-search-synthesize-cite** workflow grounded in the canonical research-pack conventions.
+
+## The Eight Steps
+
+The fallback workflow is documented in `SKILL.md`. This reference explains the **why** behind each step + the failure modes per step + the tooling that supports it.
+
+### Step 1: Decompose
+
+Break the research question into 3–5 sub-questions. Use the framework: **what / why / how / who / what's next**.
+
+**Why decompose?** A 1-sentence research question rarely has a 1-source answer. Decomposition forces the orchestrator to enumerate the actual claim shape before searching, which makes search precise + makes synthesis structured.
+
+**Failure mode:** decomposing into too many sub-questions (>5) wastes search budget on diminishing returns. Cap at 5.
+
+**Tooling:** `scripts/fallback_decomposer.py` returns a deterministic starting point. Override + refine before searching.
+
+### Step 2: Source Selection
+
+For each sub-question, pick the right source class. Use the deterministic mapping in SKILL.md:
+
+- Recency-sensitive → WebSearch + WebFetch (+ optional Reddit/HN signal)
+- Technical specs → WebSearch + WebFetch
+- Academic → Consensus MCP if available; else WebSearch + scholar.google.com filter
+- Data / numbers → WebSearch for primary documents
+- Entity-level → consider routing back to `dossier`
+
+**Failure mode:** using a wrong-class source (e.g., WebSearch for academic when Consensus would have produced higher-quality results). The mapping is deterministic for a reason.
+
+### Step 3: Search
+
+Sequential per sub-question. **1 q/sec rate limit** (research-pack convention). Per source: 2–4 queries, broad-to-narrow.
+
+**Why broad-to-narrow?** Broad queries map the landscape; narrow queries find the high-signal sources within it. Going narrow-only often misses the orienting overview.
+
+**Failure mode:** parallel search bursts that trigger rate-limiting or get blocked. Sequential is the discipline.
+
+### Step 4: Read + Extract
+
+For each high-signal result: WebFetch the full content + extract the relevant section + note the URL.
+
+**Why extract, not summarize?** Direct quotes + section references make citations verifiable. Summaries hide the source structure.
+
+**Failure mode:** synthesizing from search snippets without WebFetch. Snippets are not sources.
+
+### Step 5: Synthesize Per Sub-Question
+
+For each sub-question: 2–4 paragraphs with inline citations. Surface disagreement when sources disagree.
+
+**Why per-sub-question?** Sub-question structure carries through to the output. Reader can navigate to the part they care about.
+
+**Failure mode:** synthesizing across sub-questions in one mega-paragraph. Loses the navigability + makes disagreements harder to surface.
+
+### Step 6: Cross-Cutting Patterns
+
+After per-sub-question synthesis: 1–2 paragraphs of patterns across all sub-questions — consensus, controversy, gaps.
+
+**Why a separate section?** Pattern-level claims (e.g., "all sources agree on X but disagree on Y") are valuable for the reader's understanding but don't belong inside any single sub-question's synthesis.
+
+**Failure mode:** skipping this step because "the sub-questions cover it". They don't — the cross-cutting view is its own contribution.
+
+### Step 7: Output
+
+Markdown brief by default. DOCX if Q2 = document mode. Honor user preference.
+
+**Why honor preference?** Document mode triggers deeper search budgets + full audit logs. Brief mode is optimized for fast delivery. Different goals → different output shapes.
+
+**Failure mode:** producing DOCX when user wanted brief (overkill) or producing brief when user wanted DOCX (loses citations).
+
+### Step 8: Audit Log
+
+Three-count summary (queries sent / sources received / sources cited) + per-source list with reliability tier.
+
+**Why audit?** Research-pack convention. Lets the reader verify the orchestrator didn't fabricate sources or hide failures.
+
+**Failure mode:** skipping the audit. Audit is what makes the fallback output trustworthy.
+
+## The Three-Count Convention
+
+The research-pack convention requires tracking three integers throughout the fallback workflow:
+
+- **Sent**: queries actually issued (WebSearch + WebFetch + Consensus calls)
+- **Received**: results returned from those calls (after filtering)
+- **Cited**: sources actually cited in the final output
+
+The relationship `sent >= received >= cited` is always true. When it isn't, something went wrong.
+
+**Why three counts?** They make the orchestrator's search productivity visible. If sent=15, received=3, cited=1, the question was too niche or the search strategy was off. If sent=5, received=20, cited=15, the orchestrator found a rich vein. The reader can interpret the result quality based on the counts.
+
+## Source Discipline
+
+The orchestrator cites **only sources returned by this session's tool calls**. Training knowledge is labeled `[Background — not from search]` and excluded from the three-count.
+
+**Why?** Citations must be verifiable. A "cited" source that wasn't actually retrieved is a fabrication, regardless of how well it matches the orchestrator's training data.
+
+**Failure mode:** inferring a citation from background knowledge + presenting it as if retrieved. This is the highest-severity research-pack violation.
+
+## Retry + Failure Policy
+
+- **On single failure**: wait 3s → retry once → log.
+- **After 3 consecutive failures**: stop, alert user, share what was collected.
+
+**Why 3s + single retry?** Most failures are transient (rate limit, network blip). 3s + retry catches them. After 3 in a row, something structural is wrong (API outage, blocked endpoint, query-format issue); halt + escalate.
+
+**Failure mode:** infinite retry loops that consume the session budget. The 3-consecutive-failure stop is the safety valve.
+
+## Reliability Tier Classification
+
+Per source, classify as:
+
+- **Primary** — original source (peer-reviewed paper, government document, company filing, original announcement)
+- **Secondary** — derivative reporting (news article summarizing a paper, blog post analyzing a filing)
+- **Tertiary** — aggregator or wiki (Wikipedia, news aggregator, opinion piece)
+
+**Why surface tiers?** Reader needs to know which claims rest on primary evidence vs derivative reporting. A consensus claim backed by 5 secondary sources is weaker than the same claim backed by 1 primary source.
+
+**Failure mode:** misclassifying tier to make the audit look better. Honest tiering > polished audit.
+
+## Disagreement Surfacing
+
+When two sources disagree on a sub-question's answer:
+
+- **Name both positions** in the synthesis
+- **Cite both sources**
+- **State which seems stronger** + why (primary vs secondary, recency, methodology)
+- **Don't pick a winner without reasoning**
+
+**Why?** Hiding disagreement misleads the reader. Surfacing it lets them apply their own judgment.
+
+**Failure mode:** averaging two disagreeing sources into a mushy middle that neither source actually supports. This is the synthesis equivalent of fabrication.
+
+## When To Stop Searching (Fallback Mode)
+
+The fallback workflow is **not infinite**. Q4 sets the budget (5 searches for quick scan, 15 for thorough). Stop when:
+
+- Budget exhausted
+- All sub-questions have ≥1 high-signal source
+- 3-consecutive-failure threshold hit
+- User says "stop" or "that's enough"
+- Diminishing returns (last 3 searches produced no new high-signal sources)
+
+**Why budget the search?** Open-ended search is the failure mode that turns "research X" into a 30-minute exploration. Budget forces commitment + delivery.
+
+## What Goes Wrong With Fallback
+
+### Fabricated sources
+
+The orchestrator infers a citation from background knowledge. Highest-severity violation. **Prevention:** strict source discipline + three-count tracking makes this auditable.
+
+### Thin results presented as comprehensive
+
+Search returned 2 sources. Orchestrator presents conclusions as if backed by 10. **Prevention:** surface the audit counts. Reader sees `cited: 2` + adjusts confidence.
+
+### Skipping cross-cutting patterns
+
+Per-sub-question synthesis without cross-cutting view. Reader misses the pattern-level insight. **Prevention:** Step 6 is mandatory.
+
+### Skipping audit
+
+Output without the audit section. **Prevention:** Audit is part of the output format, not optional.
+
+### Wrong output format
+
+User asked for brief, got DOCX. Or vice versa. **Prevention:** Q2 captures preference + Step 7 honors it.
+
+### Synthesis without decomposition
+
+Orchestrator searches first, organizes later. Output is unstructured. **Prevention:** Step 1 (decompose) before Step 3 (search) is non-negotiable.
+
+## When To Choose Fallback Over Specialist
+
+The classifier handles this deterministically. But conceptually, fallback is right when:
+
+- No specialist's signal vocabulary fits the question
+- User explicitly picked "none of the above" in Q3
+- User overrode the routing decision to fallback
+- A specialist failed + user opted to retry as fallback
+
+Fallback is **wrong** when:
+
+- A specialist clearly matched (≥2 signals) but the orchestrator ran fallback anyway
+- The question is structurally a specialist's domain but used non-canonical phrasing (this is the Q3 case — disambiguate, then route)
+
+## Operational Checklist (Per Fallback Run)
+
+- [ ] Q1 specific enough to decompose (push back if vague)
+- [ ] Decomposition produced 3-5 sub-questions
+- [ ] Source class chosen per sub-question
+- [ ] Sequential 1 q/sec search discipline
+- [ ] WebFetch on every cited result
+- [ ] Per-sub-question synthesis with citations
+- [ ] Cross-cutting patterns section
+- [ ] Output format honors Q2
+- [ ] Three-count tracked
+- [ ] Reliability tier per source
+- [ ] Audit log included
+- [ ] No fabricated citations
+
+## Citations (7 sources)
+
+1. **Cooper, Hedges, Valentine — "The Handbook of Research Synthesis and Meta-Analysis" (2009, 3rd ed.).** Source for the canonical research-synthesis workflow: question → decomposition → systematic search → extraction → synthesis → reporting. The fallback workflow is a lightweight adaptation of this for AI-orchestrated general research.
+
+2. **Cochrane Collaboration — Handbook for Systematic Reviews of Interventions (current ed.).** Source for the rigor of source classification (primary vs secondary vs tertiary), explicit search protocols, and audit requirements. The three-count + per-source-tier conventions trace to Cochrane practice.
+
+3. **PRISMA 2020 Statement — Page et al., BMJ 2021.** Source for the canonical reporting checklist for research synthesis: searches conducted + sources screened + sources included + sources excluded with reasons. The audit log in fallback mode parallels PRISMA's flow diagram.
+
+4. **Karpathy, Andrej — "On chunking and search in LLMs" (talks 2024-2025).** Source for the principle that decomposition before retrieval beats single-shot retrieval. Sub-questions drive precise queries; whole-question retrieval is too broad. https://karpathy.ai/
+
+5. **Anthropic — Multi-Agent Research System (2024-2025).** Source for the orchestrator-runs-fallback-with-audit pattern. Anthropic's research orchestrator includes explicit audit + source-tier surfacing as trust mechanisms. https://www.anthropic.com/research
+
+6. **Tufte, Edward — "The Visual Display of Quantitative Information" (1983).** Source (by analogy) for the principle of surfacing data integrity to the reader rather than hiding methodology. The three-count + audit log are the textual analogue of Tufte's data-ink ratio: report what you did so the reader can interpret what you found.
+
+7. **NIST — Special Publication 800-53 (Audit Logging guidance).** Source for the operational discipline of immutable, structured audit logs. The `routing_transparency_logger.py` JSON-backed log + the fallback audit section both implement this discipline at different scales.

package/research/research/skills/research/references/hybrid_router_architecture.md

@@ -0,0 +1,154 @@
+# Hybrid Router + Fallback Architecture — When To Delegate, When To Run
+
+This reference answers one decision: **should a research request be delegated to a specialist OR run directly by the orchestrator?** The answer is "either — depending on classification confidence," and the trustability property is **routing transparency**.
+
+## The Core Trade-Off
+
+A purely router-based architecture forces the user to know which specialist applies. A purely monolithic skill produces mediocre output for cases where a specialist would have done better.
+
+The **hybrid** answer: route when confidence is high, run a fallback when it isn't, always surface the decision so the user can correct.
+
+| Architecture | Strength | Weakness |
+|---|---|---|
+| **Pure router** | Always lands in the right specialist when it knows which one. | Brittle: every miss is a failure (no graceful degradation). |
+| **Pure monolith** | Always answers. | Generic answers when a specialist would have done better. |
+| **Hybrid (this skill)** | Specialist quality when matched; fallback when not. | Adds a classification step — but it's deterministic + fast. |
+
+## Why Routing Transparency Is Mandatory
+
+The hybrid is **only trustworthy if the user can see the routing decision and override it**. Otherwise the user can't tell when the orchestrator silently downgraded their request to a generic fallback (when a specialist would have done better) or upgraded it to a specialist (when fallback was what they actually wanted).
+
+This is the same property that makes well-designed CI/CD systems trustworthy: the system tells you what stage it's in and lets you intervene. Silent routing is a black box; transparent routing is operable.
+
+## The Three Outcomes (Forcing Frame)
+
+Every invocation produces exactly one of:
+
+1. **Delegation** (classified as specialist-domain, ≥2 signals OR single weak match): hand off to specialist verbatim, return their output, log the delegation.
+2. **Fallback execution** (no specialist matched OR Q3 user picked "none of the above"): run the 8-step plan-decompose-search-synthesize-cite workflow.
+3. **Clarification request** (classification ambiguous — ≤1 signal across all specialists): ask Q3 (domain disambiguation), then route based on the answer.
+
+Frame this way to refuse the trap of "router silently runs its fallback because the user didn't explicitly ask for a specialist." That's the failure mode the architecture exists to prevent.
+
+## What Makes A Good Routing Decision
+
+A routing decision is good when:
+
+1. **It uses signal-based deterministic logic** (keyword matching, not LLM reasoning over the query)
+2. **It commits at high confidence** (≥2 signals for a specialist)
+3. **It refuses to commit at low confidence** (1 signal across multiple specialists, or 0 across all → fallback or clarification)
+4. **It surfaces the decision** to the user with the matched signals named
+5. **It accepts override** without penalty
+
+Bad routing decisions: LLM-only "vibes" classification, silent delegation, refusal to delegate at high-confidence matches, eager delegation at ambiguous matches.
+
+## Forcing-Function Trade-Offs
+
+The orchestrator's job is to make the routing decision **fast** and **visible**, not to do the research itself when a specialist exists. This forces three design constraints:
+
+- **Minimal intake** — 2-4 questions max. Goal is to route, not to interrogate. Specialist handles its own grill-me.
+- **Deterministic classifier** — no LLM round-trip. Signal matching is sub-millisecond.
+- **Pass-through delegation** — don't pre-answer specialist questions. Their intake is intentional.
+
+When these constraints are violated, the orchestrator slowly becomes a competitor to the specialists rather than their router.
+
+## Sequencing: What Runs When
+
+```
+T+0  User invokes /cs:research with their question
+T+0  Q1 (research question) — always asked
+T+0  Q2 (output preference) — always asked
+T+0  Classifier runs (deterministic, sub-millisecond)
+T+0  IF score >= 2 OR single specialist with score 1:
+       Routing transparency: "Routing to X because Y"
+       Wait 1 turn for override (or 5s timeout)
+       Delegate verbatim + return specialist output
+     ELSE:
+       Q3 (domain disambiguation) — only when ambiguous
+       IF Q3 picks specialist: delegate
+       IF Q3 picks "none of the above": Q4 → fallback
+T+~5s  Specialist output OR fallback workflow complete
+```
+
+This sequencing is what keeps the orchestrator fast on the happy path (specialist matched cleanly) while still degrading gracefully (Q3 + Q4 + fallback for the edge cases).
+
+## What Goes Wrong With Each Component
+
+### Silent delegation (no routing transparency)
+
+User asks "what's the buzz about Anthropic," skill silently routes to `pulse`. User never sees the routing. If they wanted general research instead, they have to notice the output came from pulse, then re-invoke. This burns trust + a session.
+
+**Fix:** Routing transparency is mandatory. State decision + accept override.
+
+### LLM-reasoned classification
+
+Skill uses Claude to "decide" which specialist matches. Adds latency, costs tokens, is non-deterministic across invocations (same query → different route). User can't predict what will route where.
+
+**Fix:** Deterministic keyword matching. Predictability is the value.
+
+### Over-eager specialist routing
+
+Skill routes "research Microsoft" to `dossier` based on the word "research". But the user might want general research about Microsoft, not a competitor dossier. The single weak signal isn't strong enough.
+
+**Fix:** Generic "research [topic]" doesn't route. Specific phrases like "dossier on Microsoft" or "background on Microsoft" do.
+
+### Specialist intake pre-answering
+
+Orchestrator collects Q1 + Q2 + Q3 + Q4 + Q5 (passing all into the specialist). Specialist's own grill-me is now redundant; user has to confirm answers twice.
+
+**Fix:** Pass Q1 + Q2 only. Let specialist run its own intake.
+
+### Fallback when specialist would have done better
+
+User asks "review papers on GLP-1 receptor agonists" but skill runs fallback because the classifier missed "review papers" → "literature review" stemming. User gets generic web-search summary instead of structured litreview output.
+
+**Fix:** Signals list must include all reasonable surface forms ("review papers on", "literature review", "lit review", "litreview", etc.).
+
+## When Hybrid Is The Right Architecture
+
+The hybrid pattern is most valuable when:
+
+- Specialists exist + cover non-trivial portion of likely requests
+- Specialists have different intake/output shapes (forcing user to know which to use is a tax)
+- Generic fallback exists + is acceptable (better than rejecting the request)
+- Routing can be made deterministic (predictable classification > LLM "vibes")
+
+When these aren't true, simpler architectures win:
+
+- No specialists yet? Build the monolith.
+- One dominant specialist? Just expose it.
+- Routing requires deep reasoning over intent? Use LLM classification (accept the cost).
+- Fallback would mislead users? Reject instead of falling back.
+
+## Operational Checklist
+
+Before deploying a hybrid router skill:
+
+- [ ] Specialist registry documented with explicit routing signals per specialist
+- [ ] Classifier is deterministic (no LLM in the loop)
+- [ ] Confidence threshold defined (≥2 signals for commit)
+- [ ] Single-weak-match policy defined (1 signal + only one specialist → route)
+- [ ] Ambiguity policy defined (≤1 across all → Q3 disambiguation)
+- [ ] Routing transparency is mandatory (decision + override surface)
+- [ ] Override path tested
+- [ ] Fallback workflow specified end-to-end
+- [ ] Audit log captures routing decisions + overrides for later review
+- [ ] Anti-patterns documented (LLM classification, silent delegation, etc.)
+
+## Citations (8 sources)
+
+1. **Karpathy, Andrej — "LLM OS" talk (2024).** Source for the orchestrator pattern: a smart top-level dispatcher routing to specialized capabilities is more effective than a single monolithic LLM call. Frames the router-with-fallback as a kernel-vs-syscalls analogy. https://karpathy.ai/
+
+2. **Anthropic — Multi-Agent Research System (2024-2025).** Source for the hybrid router-vs-run trade-off in agentic systems. Anthropic's research orchestrator surfaces routing decisions explicitly + accepts user overrides. Practical implementation of the pattern this skill formalizes. https://www.anthropic.com/research
+
+3. **Schaubroeck et al. — "Bounded Confidence in Multi-Agent Systems" (2018).** Source for the academic framing of why bounded-confidence routing (commit only above threshold) outperforms always-route-or-always-defer architectures. Confidence thresholds prevent both over-eager + under-eager commitment.
+
+4. **Google Search Engineering — Query Classification (industry posts).** Source for the deterministic-keyword-matching pattern in production query routers. Google's query classifier uses signal-based deterministic routing for predictability + debuggability, with LLM-reasoned routing only for the residual that signals miss.
+
+5. **Robert Frost, "The Road Not Taken" (1916).** Cited tongue-in-cheek for the routing decision as a one-way door: once delegated, the user sees the specialist's output, not what fallback would have produced. Routing transparency is what gives the user the option to take the other road.
+
+6. **Kubernetes API server — admission controller chain.** Source for the chain-of-responsibility pattern: each handler classifies + either acts or passes to next. Routing transparency in Kubernetes is the auditable admission decision log. Same property in this skill via `routing_transparency_logger.py`.
+
+7. **Tom Preston-Werner — Semantic Versioning specification.** Source for the principle of explicit, predictable contracts over implicit behavior. SemVer's predictability is what made it adoptable; the same property applies to this skill's deterministic routing.
+
+8. **Jeff Hodges — "Notes on Distributed Systems for Young Bloods" (2013).** Source for the principle that explicit + visible system state is what makes operators trust + intervene. Routing transparency is the operator-trust property for skill orchestration. https://www.somethingsimilar.com/2013/01/14/notes-on-distributed-systems-for-young-bloods/