mia-code 0.2.0 → 0.3.0

package/skills/deep-search/agent-templates.md

@@ -0,0 +1,224 @@
+# Sub-Agent Prompt Templates
+
+Detailed templates for common research decompositions. Copy and adapt these when spawning sub-agents.
+
+## Content Platform Research (YouTube, TikTok, Shorts)
+
+### Agent 1: General Best Practices & Algorithm
+
+```
+You are researching [PLATFORM] [SPECIFIC ASPECT] best practices and current algorithm
+behavior for Olle Dyberg, a 25-year-old Swedish AI content creator (@olleai on TikTok,
+~5.5K followers, 1.1M+ views). His niche is AI tools — Claude Code, agents, context engineering.
+
+PURPOSE: Olle will feed this research into a meta-prompt that generates optimized
+[titles/descriptions/hooks/etc.] for maximum engagement, viewers, and growth. The research
+needs to be exhaustive enough to serve as the knowledge base behind that prompt.
+
+YOUR ANGLE: General best practices and algorithm mechanics for [PLATFORM] [ASPECT].
+Cover: character limits, algorithm ranking signals, what the platform rewards/penalizes,
+formatting rules, proven formulas, A/B test data, engagement metrics that matter.
+DO NOT cover: niche-specific advice (another agent handles that), X discourse, or vault knowledge.
+
+TOOLS: Use web search (mcp__exa__web_search_exa, WebSearch) to find the most current
+information. Prioritize sources from late 2025 and 2026. Fetch and deep-dive any
+particularly rich articles with WebFetch.
+
+QUALITY BAR: Be exhaustive. I need specific numbers (character counts, engagement
+percentages, algorithm thresholds), not generalities. If a source says "keep titles short,"
+I need to know EXACTLY how short and why. Include every framework, formula, and data point
+you find. Sources for everything.
+```
+
+### Agent 2: Niche-Specific Strategies
+
+```
+You are researching [PLATFORM] [SPECIFIC ASPECT] strategies specifically for the AI/tech
+content niche, for Olle Dyberg (@olleai, AI tools creator, ~5.5K TikTok followers).
+
+PURPOSE: [Same as above — what the research will be used for]
+
+YOUR ANGLE: How [ASPECT] works differently in the AI/tech/developer niche compared to
+general content. Cover: what AI creators specifically do, what hooks/formats work for
+technical content, how to translate complex topics into engaging [titles/descriptions/etc.],
+examples from successful AI/tech creators, what the AI audience responds to.
+DO NOT cover: general best practices (another agent handles that) or vault knowledge.
+
+TOOLS: Use web search to find AI/tech creator-specific advice. Search for specific creators
+in this space (Fireship, NetworkChuck, AI Jason, Matt Wolfe, etc.) and analyze their patterns.
+
+QUALITY BAR: I need SPECIFIC examples from real AI/tech creators with actual metrics where
+possible. "Tech content should be educational" is useless. "Fireship's Shorts averaging 500K
+views use [specific pattern]" is gold.
+```
+
+### Agent 3: Real Examples & Pattern Analysis
+
+```
+You are analyzing real-world examples of high-performing [PLATFORM] [ASPECT] to extract
+patterns, for Olle Dyberg (@olleai, AI tools creator).
+
+PURPOSE: [What the research will be used for]
+
+YOUR ANGLE: Find and analyze 15-30 real examples of high-performing [titles/descriptions/hooks]
+on [PLATFORM]. Extract patterns: word choice, structure, length, emotional triggers, formatting.
+Focus on both general viral content AND AI/tech niche content.
+DO NOT cover: theory or general advice (other agents handle that).
+
+TOOLS: Use web search and grep MCP if applicable. Look for case studies, creator breakdowns,
+and analysis posts that include actual performance data.
+
+QUALITY BAR: I need REAL examples with REAL numbers. Not hypothetical titles — actual titles
+from actual [videos/shorts] with actual view counts. The more examples the better. Organize
+by pattern type.
+```
+
+### Agent 4: Psychology & Copywriting
+
+```
+You are researching the psychological and copywriting principles behind high-engagement
+[PLATFORM] [ASPECT], for Olle Dyberg (@olleai, AI content creator).
+
+PURPOSE: [What the research will be used for]
+
+YOUR ANGLE: The WHY behind what works. Cover: cognitive biases exploited by viral content
+(curiosity gap, loss aversion, social proof, pattern interrupt), copywriting frameworks
+adapted for short-form, attention psychology, the neuroscience of scrolling behavior,
+power words and trigger words with data on their effectiveness.
+DO NOT cover: platform-specific algorithm mechanics (another agent handles that).
+
+TOOLS: Use web search. Look for research papers, marketing studies, copywriting resources,
+and behavioral psychology applied to short-form content.
+
+QUALITY BAR: I need frameworks I can codify into rules, not vague psychology. "Curiosity
+works" is useless. "Open loops increase watch time by 47% (Source: [study])" is gold.
+Specific power words, specific emotional triggers, specific formulas.
+```
+
+### Agent 5: X/Twitter Discourse
+
+```
+You are searching X/Twitter for current creator discourse about [PLATFORM] [ASPECT],
+for Olle Dyberg (@olleai, AI content creator, ~5.5K TikTok followers).
+
+PURPOSE: [What the research will be used for]. X discourse captures what creators are
+ACTUALLY experiencing right now vs. what blog posts from 6 months ago say.
+
+YOUR ANGLE: What are creators saying RIGHT NOW about [ASPECT] on [PLATFORM]? Recent
+algorithm changes, what's working this month, creator tips that haven't made it to blog
+posts yet, contrarian takes, pain points, and wins.
+DO NOT cover: general best practices from web search (other agents handle that).
+
+TOOLS: Use the x-research CLI:
+cd ~/clawd/skills/x-research && source ~/.config/env/global.env
+bun run x-search.ts search "[query]" --quality --quick
+
+Run 3-5 different queries to cover the topic from multiple angles.
+Include the actual tweets with engagement metrics in your findings.
+
+QUALITY BAR: I need actual tweets from actual creators with actual engagement numbers.
+Filter for signal — a tweet with 500 likes from a known creator matters more than 50
+tweets with 2 likes each.
+```
+
+### Agent 6: Vault Knowledge
+
+```
+You are searching Olle's Obsidian vault for existing knowledge about [TOPIC],
+located at /mnt/c/Users/olled/Documents/Obsidian/Notes/.
+
+PURPOSE: [What the research will be used for]. The vault contains distilled insights
+from 120+ articles, client work, and Olle's personal experience. This knowledge should
+inform the research — not be duplicated.
+
+YOUR ANGLE: Find EVERYTHING the vault already knows about [TOPIC]. Check:
+- 04 - Areas/AI Knowledge/ (distilled playbooks)
+- 02 - Content/ (Ideas.md, Strategies.md, Research/)
+- 05 - Resources/ (Tools, articles)
+- _Index.md (for navigation)
+
+DO NOT do web research — other agents handle that. Your job is internal knowledge only.
+
+TOOLS: Use Glob to find relevant files, Grep to search content, Read to extract insights.
+
+QUALITY BAR: Report everything found, organized by source file. Note what seems current
+vs. potentially outdated. Flag any contradictions with what other agents might find.
+```
+
+## Technology Research
+
+### Agent 1: Current State & Ecosystem
+
+```
+[Same WHO/WHY preamble, adapted]
+
+YOUR ANGLE: Current state of [TECHNOLOGY] as of February 2026. Ecosystem overview,
+major players, recent changes, adoption trends, key features, limitations. Focus on
+what's NEW and current — not evergreen docs.
+
+TOOLS: Web search (mcp__exa__web_search_exa, WebSearch). Prioritize 2026 sources.
+```
+
+### Agent 2: Real Code Patterns
+
+```
+[Same WHO/WHY preamble, adapted]
+
+YOUR ANGLE: How developers are ACTUALLY using [TECHNOLOGY] in real projects. Find
+shipped code patterns, not tutorial examples.
+
+TOOLS: Use mcp__grep__searchGitHub to search over a million GitHub repos. Search for
+actual code patterns like function calls, configuration, imports — not keywords.
+Examples of good searches:
+- 'import { X } from' for library usage
+- Function signatures for API patterns
+- Config file patterns for setup
+```
+
+### Agent 3: Community Sentiment (X)
+
+```
+[Same structure as X agent above, adapted for technology topic]
+```
+
+### Agent 4: Vault Knowledge
+
+```
+[Same structure as vault agent above, adapted for technology topic]
+```
+
+## Business/Strategy Research
+
+### Agent 1: Market Data & Benchmarks
+
+```
+[Same WHO/WHY preamble, adapted]
+
+YOUR ANGLE: Hard numbers. Market size, pricing benchmarks, conversion rates, revenue
+data, growth metrics. Focus on data that informs strategy decisions.
+
+TOOLS: Web search. Look for reports, surveys, creator economy data, SaaS metrics.
+```
+
+### Agent 2: Expert Frameworks & Strategies
+
+```
+[Same WHO/WHY preamble, adapted]
+
+YOUR ANGLE: Frameworks, mental models, and strategies from practitioners who've
+done this successfully. Not theory — proven approaches with results.
+
+TOOLS: Web search. Look for creator/founder breakdowns, case studies, strategy posts.
+```
+
+### Agent 3: X Discourse
+
+```
+[Same structure as X agent, adapted for business topic]
+```
+
+### Agent 4: Vault Knowledge
+
+```
+[Same structure as vault agent, adapted for business topic]
+```

package/skills/deep-search/orchestration-patterns.md

@@ -0,0 +1,95 @@
+# Multi-Agent Research Orchestration Patterns
+
+Full reference on proven patterns for multi-agent research. Extracted from Anthropic's engineering blog, production systems (GPT-Researcher, Onyx, LangChain), and 40+ sources.
+
+For the comprehensive research document with all sources, see:
+`/mnt/c/Users/olled/Documents/Obsidian/Notes/02 - Content/Research/Multi-Agent Research Orchestration Patterns 2026.md`
+
+## Key Statistics
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Multi-agent vs single-agent quality | +90.2% | Anthropic internal eval |
+| Research time reduction (parallel) | Up to 90% | Anthropic engineering blog |
+| Token usage vs single-turn chat | ~15x more | Anthropic engineering blog |
+| Token usage explains performance | 80% of variance | BrowseComp evaluation |
+| Self-improving tool descriptions | -40% completion time | Anthropic engineering blog |
+| Optimal sub-agent count | 3-5 parallel | Anthropic + OpenAI convergence |
+| Max research cycles per sub-agent | 6-8 | Onyx production system |
+| Coverage threshold | 2+ sources per sub-Q | OpenAI Deep Research |
+
+## Proven Architecture: Orchestrator-Worker
+
+Every production system converges on this:
+
+```
+User Query
+    |
+    v
+[Lead Agent / Orchestrator]
+    |
+    ├── Clarify (if needed)
+    ├── MECE decompose into sub-questions
+    ├── Spawn 3-6 parallel sub-agents
+    │     ├── Sub-agent A (angle 1) → findings
+    │     ├── Sub-agent B (angle 2) → findings
+    │     └── Sub-agent C (angle 3) → findings
+    ├── Evaluate coverage → spawn more if gaps
+    ├── Synthesize all findings
+    └── Generate final report with citations
+```
+
+**Anthropic uses**: Opus 4 lead + Sonnet 4 workers. Different models reduce single-model blind spots.
+
+## The 10 Pitfalls to Engineer Against
+
+1. **Agent spawning explosions** — Hard-cap at 6 agents. Scale to complexity.
+2. **Duplicate work** — MECE + explicit "do NOT cover X" boundaries.
+3. **Overly-specific search queries** — Explicitly prompt "start broad (2-4 words), then narrow."
+4. **SEO content farm preference** — Add source quality heuristics to every prompt.
+5. **Context exhaustion** — Sub-agents write to files, lead reads summaries.
+6. **Anchoring bias** — Batch ALL results before synthesis. Never process sequentially.
+7. **Lost nuance in compression** — Preserve: facts, numbers, quotes, citations, contradictions.
+8. **"Good enough" stopping** — Require 2+ sources per sub-question before report.
+9. **Excessive inter-agent chatter** — Sub-agents report only to lead. No broadcasting.
+10. **Single model bias** — Use Opus for lead, Sonnet for workers when possible.
+
+## Decomposition Strategies
+
+### MECE (Mutually Exclusive, Collectively Exhaustive)
+The gold standard. Each sub-question covers a distinct area. No overlaps, no gaps.
+
+### Perspective-Based
+Break by stakeholder/lens: technical, business, user experience, historical, competitive, future.
+
+### Dimension-Based
+Break by question type: what exists, what are problems, what solutions emerge, who are key players, what does evidence say.
+
+### Scale-Effort-to-Complexity
+- Simple fact-finding: 1 agent, 3-10 tool calls
+- Direct comparisons: 2-4 agents, 10-15 calls each
+- Complex multi-faceted: 5-6 agents with divided responsibilities
+
+## Synthesis Best Practices
+
+### Three-Stage Pipeline
+1. **Aggregate**: Collect all findings. Identify thematic connections.
+2. **Cross-reference**: Where do sources agree (high confidence)? Where do they contradict?
+3. **Construct narrative**: Organize by theme, not by agent. The output should feel like one coherent document, not a concatenation.
+
+### The Critique Loop (Optional)
+After synthesis, optionally spawn a critic agent that checks:
+- Completeness (all sub-agent findings reflected?)
+- Accuracy (claims properly attributed?)
+- Coherence (logical flow?)
+- Gaps (what remains unanswered?)
+
+If issues found, revise synthesis.
+
+## Production Systems to Study
+
+1. **Anthropic's multi-agent system** — Opus lead + Sonnet workers, 90.2% improvement
+2. **GPT-Researcher** (github.com/assafelovic/gpt-researcher) — 14k+ stars, editor/researcher/writer pipeline
+3. **Onyx** (github.com/onyx-dot-app/onyx) — Enterprise-grade, two-tier orchestration
+4. **LangChain Open Deep Research** (github.com/langchain-ai/open_deep_research) — StateGraph workflow
+5. **Google ADK** — ParallelAgent → SequentialAgent pattern

package/skills/miaco-pde-inquiry-routing-deep-search/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md - skills/miaco-pde-inquiry-routing-deep-search
+
+MIA:: This skill handles the external inquiry path — when local qmd collections cannot resolve a PDE ambiguity, we route outward to academic sources, GitHub repositories, and web knowledge.
+AVA:: The structural tension here is clear: PDE surfaces what we don't know, local-qmd searches what we already have, and this skill reaches into the world for what we haven't yet gathered.
+MIA:: Exactly. Each unresolved question gets classified — is it academic research, open-source discovery, or conceptual inspiration? Each classification spawns a different type of deep-search sub-agent.
+AVA:: The output mirrors the local-qmd format: QUESTION:RESOLUTION JSONL, plus recommendation-actions.jsonl for open-source fork/clone/inspire decisions.
+MIA:: Yes, and the internal-external-relationship skill orchestrates when both paths run and merges their results.
+
+## RELATED ISSUES
+
+* jgwill/src#425
+* jgwill/src#424 (local-qmd counterpart)
+* jgwill/src#426 (orchestration layer)

package/skills/miaco-pde-inquiry-routing-deep-search/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: miaco-pde-inquiry-routing-deep-search
+description: >
+  Routes PDE questions to external knowledge sources — academic papers, GitHub repositories,
+  and web research — when internal collections lack answers. Use when PDE ambiguities
+  require world knowledge, open-source discovery, or conceptual inspiration.
+  Triggers: "external inquiry", "deep search route", "academic search", "find upstream".
+version: 0.1.0
+---
+
+# PDE Inquiry Routing — Deep Search (External)
+
+Routes secondary intents and unresolved ambiguities from a PDE decomposition to external knowledge sources. Each question gets classified by type and dispatched to specialized deep-search sub-agents. Open-source discoveries produce actionable fork/clone/inspire recommendations.
+
+## Who This Is For
+
+Agents that have exhausted local knowledge (via `miaco-pde-inquiry-routing-local-qmd`) and need to reach into the world — academic literature, GitHub ecosystems, web practitioners — to resolve remaining unknowns before execution begins.
+
+## The Routing Diamond
+
+```
+[PDE secondary intents + unresolved ambiguities]
+              ↓
+     [Classify each question]
+       /        |        \
+  academic   open-source   conceptual
+  research   discovery     inspiration
+       \        |        /
+     [Parallel deep-search agents]
+       \        |        /
+  [Synthesize → JSONL + recommendations]
+```
+
+## Workflow
+
+### Phase 1: Extract & Classify Questions
+
+1. Receive PDE decomposition (or filtered UNRESOLVED items from local-qmd output)
+2. For each question, classify into one of three categories:
+
+| Classification | Signal | Agent Strategy |
+|---------------|--------|----------------|
+| `academic-research` | Methodology, theory, framework references | Web search for papers, docs, established practices |
+| `open-source-discovery` | Tool names, library references, "is there a..." | GitHub search for repos, implementations, prior art |
+| `conceptual-inspiration` | Novel patterns, "how might we...", cross-domain | Broad web search + GitHub for analogous solutions |
+
+3. A single question may have multiple classifications — spawn one agent per classification
+
+### Phase 2: Spawn Parallel Deep-Search Sub-Agents
+
+For each classified question, spawn a sub-agent with appropriate tools:
+
+**Academic Research Agent:**
+```
+Search for established practices, papers, documentation on: <QUESTION>
+Context: This resolves an ambiguity from PDE decomposition of: <ORIGINAL_PROMPT_SUMMARY>
+Use web_search for academic and practitioner sources.
+Use WebFetch to deep-read promising URLs.
+Prefer: official docs, practitioner blogs, conference talks, academic papers.
+Avoid: SEO farms, aggregators, outdated tutorials.
+Output: findings as structured JSON with source URLs.
+```
+
+**Open-Source Discovery Agent:**
+```
+Search GitHub for existing implementations of: <QUESTION>
+Context: <ORIGINAL_PROMPT_SUMMARY>
+Use github_search_code and github_search_repositories.
+Evaluate: stars, recent activity, license, code quality.
+For each discovery, recommend: fork (adopt directly), clone (study and adapt), or inspire (learn pattern only).
+Output: findings as structured JSON with repo URLs and recommendations.
+```
+
+**Conceptual Inspiration Agent:**
+```
+Search broadly for analogous solutions to: <QUESTION>
+Context: <ORIGINAL_PROMPT_SUMMARY>
+Look across domains — the answer may exist in a different field.
+Use web_search with broad queries first, then narrow.
+Output: findings with cross-domain connections noted.
+```
+
+### Phase 3: Synthesize Results
+
+After ALL sub-agents return (batch — avoid anchoring bias):
+
+1. Merge findings per original question
+2. Score confidence based on source quality and consensus
+3. For open-source discoveries, produce recommendation actions
+
+## Input
+
+Either:
+- Full PDE decomposition JSON with `ambiguities[]` and `secondaryIntents[]`
+- Or filtered `inquiry-resolutions.jsonl` from local-qmd with `status: "unresolved"` items
+
+## Output
+
+**inquiry-resolutions.jsonl** — one JSON object per line:
+
+```jsonl
+{"question": "What is the sacred-container pattern?", "source": "external", "classification": "academic-research", "status": "resolved", "resolution": "Sacred container in ceremony design refers to...", "confidence": 0.75, "sources": ["https://..."], "search_type": "web"}
+{"question": "Is there an existing MCP-to-CLI bridge?", "source": "external", "classification": "open-source-discovery", "status": "resolved", "resolution": "mcp2cli exists at github.com/...", "confidence": 0.9, "sources": ["https://github.com/..."], "search_type": "github"}
+```
+
+**recommendation-actions.jsonl** — for open-source discoveries:
+
+```jsonl
+{"repo": "user/repo-name", "action": "fork", "reason": "Direct match for our MCP bridge need", "stars": 245, "license": "MIT", "last_commit": "2026-03-15", "url": "https://github.com/..."}
+{"repo": "user/other-repo", "action": "inspire", "reason": "Different domain but analogous pattern for ceremony state", "stars": 89, "license": "Apache-2.0", "last_commit": "2025-12-01", "url": "https://github.com/..."}
+```
+
+## Tools
+
+| Tool | Use For |
+|------|---------|
+| `web_search` | Academic papers, practitioner blogs, current documentation |
+| `WebFetch` | Deep-read specific URLs found via search |
+| GitHub search (code + repos) | Open-source discovery, prior art, implementations |
+| Deep-search sub-agents | Parallel investigation per classification |
+
+## Quality Gates
+
+- [ ] Every question has a classification and corresponding agent dispatch
+- [ ] Open-source discoveries include fork/clone/inspire recommendation
+- [ ] Sources include URLs — no unsourced claims
+- [ ] Confidence scores reflect source quality (official docs > blog > forum)
+- [ ] Batch synthesis — all agents complete before merging results
+- [ ] JSONL format matches local-qmd output schema for downstream merging
+
+## Related
+
+- `../deep-search/SKILL.md` — General deep-research pattern this extends
+- `../miaco-pde-inquiry-routing-local-qmd/SKILL.md` — internal routing counterpart
+- `../miaco-pde-inquiry-routing-internal-external-relationship/SKILL.md` — orchestration layer
+- Issue: jgwill/src#425

package/skills/miaco-pde-inquiry-routing-internal-external-relationship/AGENTS.md

@@ -0,0 +1,4 @@
+# AGENTS.md - skills/miaco-pde-inquiry-routing-internal-external-relationship
+
+* I intent to establish here how I conceive the relation of Internal Inquiries resolution with what can happen with external inquiries resolution like into `../deep-search/` (skill name to be defined when forked)
+* We want to achive something.  There will be explicit intention and implicit intent, action-steps, ambiguities and we can draw from that questions that we will resolve with search like using 

package/skills/miaco-pde-inquiry-routing-internal-external-relationship/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: miaco-pde-inquiry-routing-internal-external-relationship
+description: >
+  Orchestrates the relationship between internal (qmd) and external (deep-search) inquiry
+  paths. Classifies each PDE question, routes to the appropriate skill(s), merges and
+  deduplicates results, and produces a unified resolution set with confidence scoring.
+  Triggers: "inquiry routing", "resolve all", "chain inquiry", "route questions".
+version: 0.1.0
+dependencies:
+  - miaco-pde-inquiry-routing-local-qmd
+  - miaco-pde-inquiry-routing-deep-search
+---
+
+# PDE Inquiry Routing — Internal/External Orchestration
+
+The orchestration layer that holds the relationship between internal knowledge (qmd collections) and external knowledge (web, GitHub, academic). Each PDE question gets classified, routed to the right path(s), and results get merged into a single source of truth with confidence scoring and source attribution.
+
+## Who This Is For
+
+The top-level agent coordinating a PDE session. Rather than manually deciding "search locally or externally?", invoke this skill to handle the full inquiry lifecycle. The structural tension: PDE reveals unknowns — this skill transforms the entire set into resolved knowledge, drawing from both internal and external sources as needed.
+
+## Orchestration Flow
+
+```
+[PDE Decomposition]
+        ↓
+[Classify each question: internal-first / external-first / both]
+        ↓
+   ┌────────────────┬─────────────────┐
+   ↓                ↓                 ↓
+[internal-first] [external-first]  [both]
+   ↓                ↓              ↓    ↓
+[local-qmd]    [deep-search]   [local] [deep]
+   ↓                ↓              ↓    ↓
+[if unresolved →    │         [merge results]
+ route external]    │              ↓
+   ↓                ↓              ↓
+   └────────────────┴──────────────┘
+                    ↓
+        [Deduplicate & merge]
+                    ↓
+        [Score confidence per resolution]
+                    ↓
+        [unified inquiry-resolutions.jsonl]
+```
+
+## Workflow
+
+### Phase 1: Receive & Classify
+
+1. Receive full PDE decomposition
+2. For each ambiguity and secondary intent, classify routing:
+
+| Classification | When | Routing |
+|---------------|------|---------|
+| `internal-first` | Question references known entities, project terms, past decisions | Route to local-qmd → if UNRESOLVED, escalate to deep-search |
+| `external-first` | Question references external tools, libraries, academic concepts | Route to deep-search directly |
+| `both` | Question spans internal context + external knowledge | Route to both in parallel |
+
+**Classification heuristics:**
+- References to project names, file paths, GUILLAUME.md → `internal-first`
+- References to npm packages, GitHub repos, methodologies → `external-first`
+- "How does our X compare to..." or "What pattern should we use for..." → `both`
+- When uncertain → `internal-first` (cheaper, faster, may suffice)
+
+### Phase 2: Route to Skills
+
+**Internal-first path:**
+1. Invoke `miaco-pde-inquiry-routing-local-qmd` with classified questions
+2. Collect `inquiry-resolutions.jsonl`
+3. Filter items with `status: "unresolved"` or `status: "partial"`
+4. Escalate those to `miaco-pde-inquiry-routing-deep-search`
+
+**External-first path:**
+1. Invoke `miaco-pde-inquiry-routing-deep-search` directly
+
+**Both path:**
+1. Invoke both skills in parallel with the same questions
+2. Merge results in Phase 3
+
+### Phase 3: Merge & Deduplicate
+
+After all routing completes:
+
+1. Collect all `inquiry-resolutions.jsonl` outputs
+2. Group by original question
+3. For questions answered by both paths:
+   - If answers agree → merge, boost confidence
+   - If answers conflict → flag as `conflicting`, include both with sources
+   - If one is richer → prefer the richer answer, note both sources
+4. Deduplicate — same resolution from different sources becomes one entry with multiple source attributions
+
+### Phase 4: Score & Finalize
+
+For each resolution, compute final confidence:
+
+| Factor | Weight |
+|--------|--------|
+| Source quality (official docs > blog > forum) | 0.3 |
+| Cross-source agreement (internal + external agree) | 0.3 |
+| Specificity (concrete answer vs vague reference) | 0.2 |
+| Recency (recent source vs dated) | 0.1 |
+| Collection match (right collection for question type) | 0.1 |
+
+## Input
+
+Full PDE decomposition JSON — the complete output from `pde_parse_response`.
+
+## Output
+
+**unified inquiry-resolutions.jsonl** — one JSON object per line:
+
+```jsonl
+{"question": "What is the GUILLAUME.md collection structure?", "source_path": "internal", "status": "resolved", "resolution": "GUILLAUME.md files define per-project identity...", "confidence": 0.85, "sources": [{"type": "qmd", "collection": "guillaume", "doc_id": "#abc123"}]}
+{"question": "What is the sacred-container pattern?", "source_path": "internal→external", "status": "resolved", "resolution": "Not found locally. External: sacred container in ceremony design refers to...", "confidence": 0.65, "sources": [{"type": "qmd", "collection": "docs", "result": "no_match"}, {"type": "web", "url": "https://..."}]}
+{"question": "Is there an existing MCP-to-CLI bridge?", "source_path": "external", "status": "resolved", "resolution": "mcp2cli at github.com/...", "confidence": 0.9, "sources": [{"type": "github", "repo": "user/mcp2cli", "url": "https://..."}], "recommendation": {"action": "fork", "reason": "Direct match"}}
+{"question": "How does mia-pi-mono migration affect widgets?", "source_path": "both", "status": "conflicting", "resolutions": [{"source": "internal", "text": "mia-pi-mono is meant to contain all mia-code capabilities"}, {"source": "external", "text": "No external documentation found"}], "confidence": 0.4, "needs_human": true}
+```
+
+## Routing Decision Tree
+
+```
+Is the question about something in our project/repos?
+  ├─ YES → Does it also reference external tools/concepts?
+  │    ├─ YES → route: both
+  │    └─ NO  → route: internal-first
+  └─ NO  → Does it reference academic/methodological concepts?
+       ├─ YES → route: external-first (academic)
+       └─ NO  → Is it about open-source tooling?
+            ├─ YES → route: external-first (open-source)
+            └─ NO  → route: internal-first (default safe)
+```
+
+## Quality Gates
+
+- [ ] Every PDE ambiguity and secondary intent has a routing classification
+- [ ] Internal-first items that remain UNRESOLVED are escalated to external
+- [ ] Conflicting resolutions are flagged, not silently resolved
+- [ ] Final JSONL includes `source_path` showing which route(s) produced the answer
+- [ ] Confidence scores use the weighted formula, not arbitrary values
+- [ ] Items with `confidence < 0.3` are marked `needs_human: true`
+- [ ] Output schema is compatible with both upstream skills' JSONL format
+
+## Dependencies
+
+| Skill | Role |
+|-------|------|
+| `miaco-pde-inquiry-routing-local-qmd` | Internal knowledge search |
+| `miaco-pde-inquiry-routing-deep-search` | External knowledge search |
+
+## Related
+
+- `../qmd/SKILL.md` — QMD query syntax reference
+- `../deep-search/SKILL.md` — General deep-research pattern
+- Issue: jgwill/src#426
+- Issue: jgwill/src#424 (local-qmd)
+- Issue: jgwill/src#425 (deep-search)