@duckmind/deepquark-darwin-arm64 0.9.78 → 0.9.81

package/.deepquark/skills/bundled/duckmind-deep-research/SKILL.md

@@ -0,0 +1,754 @@
+---
+name: deep-research
+description: Conduct enterprise-grade research with multi-source synthesis, citation tracking, and verification. Use when user needs comprehensive analysis requiring 10+ sources, verified claims, or comparison of approaches. Triggers include "deep research", "comprehensive analysis", "research report", "compare X vs Y", or "analyze trends". Do NOT use for simple lookups, debugging, or questions answerable with 1-2 searches.
+---
+
+# Deep Research
+
+<!-- STATIC CONTEXT BLOCK START - Optimized for prompt caching -->
+<!-- All static instructions, methodology, and templates below this line -->
+<!-- Dynamic content (user queries, results) added after this block -->
+
+## Core System Instructions
+
+**Purpose:** Deliver citation-backed, verified research reports through 8-phase pipeline (Scope → Plan → Retrieve → Triangulate → Synthesize → Critique → Refine → Package) with source credibility scoring and progressive context management.
+
+**Primary Research Engine:** This skill uses **Perplexity Sonar Deep Research** (via OpenRouter) as its primary retrieval engine. Sonar Deep Research is a multi-step research model that autonomously searches, reads, and evaluates sources — performing deep synthesis across complex topics including finance, technology, health, and current events. It is invoked at the start of Phase 3 before any other searches, and its output forms the backbone of the final report.
+
+**Context Strategy:** This skill uses 2025 context engineering best practices:
+- Static instructions cached (this section)
+- Progressive disclosure (load references only when needed)
+- Avoid "loss in the middle" (critical info at start/end, not buried)
+- Explicit section markers for context navigation
+
+---
+
+## OpenRouter / Sonar Deep Research Integration
+
+### API Key Resolution
+
+**Priority order for resolving the OpenRouter API key:**
+
+1. **DeepQuark local auth store** (preferred):
+   ```bash
+   cat ~/.local/share/deepquark/auth.json | python3 -c "
+   import json, sys
+   data = json.load(sys.stdin)
+   key = data.get('duckmind').get('key')
+   print(key or '')
+   "
+   ```
+
+2. **Environment variable** (fallback):
+   ```bash
+   echo $DUCKMIND_API_KEY
+   ```
+
+3. **If neither found:** Abort Sonar phase → fall back to parallel WebSearch only. Log warning:
+   ```
+   ⚠️ DUCKMIND API key not found. Falling back to WebSearch-only mode.
+   ```
+
+### Calling Sonar Deep Research
+
+**Endpoint:** `https://openrouter.ai/api/v1/chat/completions`  
+**Model:** `perplexity/sonar-deep-research`
+
+**Python invocation (run via bash_tool):**
+
+```python
+#!/usr/bin/env python3
+"""sonar_research.py — Call Perplexity Sonar Deep Research via OpenRouter"""
+
+import json, sys, os, urllib.request, urllib.error
+
+def get_api_key():
+    # 1. Try DeepQuark auth store
+    auth_path = os.path.expanduser("~/.local/share/deepquark/auth.json")
+    if os.path.exists(auth_path):
+        try:
+            with open(auth_path) as f:
+                data = json.load(f)
+            key = data.get("duckmind").get("key")
+            if key:
+                return key
+        except Exception:
+            pass
+    # 2. Try env var
+    return os.environ.get("duckmind", "")
+
+def sonar_research(query: str, mode: str = "standard") -> dict:
+    api_key = get_api_key()
+    if not api_key:
+        return {"error": "no_api_key", "content": None}
+
+    # Adjust system prompt by mode
+    depth_instruction = {
+        "quick":     "Provide a concise but comprehensive overview with key findings and citations.",
+        "standard":  "Provide a thorough multi-section research report with detailed findings, evidence, and citations.",
+        "deep":      "Provide an exhaustive analysis. Investigate all angles, counterarguments, and nuances. Prioritize source diversity and verification.",
+        "ultradeep": "Conduct maximum-depth investigation. Synthesize across all available sources. Include contradictory findings, limitations, and gaps in current knowledge.",
+    }.get(mode, "Provide a thorough research report with detailed findings and citations.")
+
+    payload = {
+        "model": "perplexity/sonar-deep-research",
+        "messages": [
+            {
+                "role": "system",
+                "content": (
+                    "You are an expert research analyst. "
+                    + depth_instruction
+                    + " Always cite your sources inline using numbered references [1], [2], etc. "
+                    "Include a full bibliography at the end. "
+                    "Distinguish clearly between verified facts and analytical synthesis. "
+                    "Do not fabricate sources or citations."
+                )
+            },
+            {
+                "role": "user",
+                "content": query
+            }
+        ],
+        "max_tokens": 8000,
+        "temperature": 0.2
+    }
+
+    req = urllib.request.Request(
+        "https://openrouter.ai/api/v1/chat/completions",
+        data=json.dumps(payload).encode(),
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://deepquark.ai",
+            "X-Title": "DeepQuark Deep Research Skill"
+        },
+        method="POST"
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = json.loads(resp.read().decode())
+            content = result["choices"][0]["message"]["content"]
+            usage = result.get("usage", {})
+            return {"error": None, "content": content, "usage": usage}
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        return {"error": f"http_{e.code}", "content": None, "detail": body}
+    except Exception as e:
+        return {"error": str(e), "content": None}
+
+if __name__ == "__main__":
+    query = sys.argv[1] if len(sys.argv) > 1 else ""
+    mode  = sys.argv[2] if len(sys.argv) > 2 else "standard"
+    if not query:
+        print(json.dumps({"error": "no_query"}))
+        sys.exit(1)
+    result = sonar_research(query, mode)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+```
+
+**Usage in Phase 3:**
+```bash
+python3 /tmp/sonar_research.py "Your research question here" "standard"
+```
+
+### Sonar Output Processing
+
+After receiving Sonar's response:
+
+1. **Extract citations:** Parse inline `[N]` references and the bibliography block.
+2. **Renumber citations:** Sonar uses its own numbering; renumber sequentially starting from `[1]` in the master report's citation tracker.
+3. **Tag Sonar findings:** Prefix each Sonar-sourced finding with `[Sonar]` in internal working notes (stripped before final report).
+4. **Credibility floor:** Sonar sources inherit a baseline credibility score of **70/100** (verified multi-source synthesis). Downgrade individual sources only if they are clearly low-quality (blog, anonymous, undated).
+5. **Gap detection:** Identify topics Sonar did NOT cover → route these to supplementary WebSearch in Phase 3.
+
+### Fallback Behavior
+
+If Sonar call fails for any reason:
+
+```
+⚠️ Sonar Deep Research unavailable: [error reason]
+   Falling back to parallel WebSearch mode (Phase 3 standard).
+   Research will proceed — expect slightly reduced source depth for [topic area].
+```
+
+Continue with 5–10 parallel WebSearch calls as documented in standard Phase 3.
+
+---
+
+## Decision Tree (Execute First)
+
+```
+Request Analysis
+├─ Simple lookup? → STOP: Use WebSearch, not this skill
+├─ Debugging? → STOP: Use standard tools, not this skill
+└─ Complex analysis needed? → CONTINUE
+
+Mode Selection
+├─ Initial exploration? → quick (3 phases, 2-5 min)
+├─ Standard research? → standard (6 phases, 5-10 min) [DEFAULT]
+├─ Critical decision? → deep (8 phases, 10-20 min)
+└─ Comprehensive review? → ultradeep (8+ phases, 20-45 min)
+
+Execution Loop (per phase)
+├─ Load phase instructions from [methodology](./reference/methodology.md#phase-N)
+├─ Execute phase tasks
+├─ Spawn parallel agents if applicable
+└─ Update progress
+
+Validation Gate
+├─ Run `python scripts/validate_report.py --report [path]`
+├─ Pass? → Deliver
+└─ Fail? → Fix (max 2 attempts) → Still fails? → Escalate
+```
+
+---
+
+## Workflow (Clarify → Plan → Act → Verify → Report)
+
+**AUTONOMY PRINCIPLE:** This skill operates independently. Infer assumptions from query context. Only stop for critical errors or incomprehensible queries.
+
+### 1. Clarify (Rarely Needed - Prefer Autonomy)
+
+**DEFAULT: Proceed autonomously. Derive assumptions from query signals.**
+
+**ONLY ask if CRITICALLY ambiguous:**
+- Query is incomprehensible (e.g., "research the thing")
+- Contradictory requirements (e.g., "quick 50-source ultradeep analysis")
+
+**When in doubt: PROCEED with standard mode. User will redirect if incorrect.**
+
+**Default assumptions:**
+- Technical query → Assume technical audience
+- Comparison query → Assume balanced perspective needed
+- Trend query → Assume recent 1-2 years unless specified
+- Standard mode is default for most queries
+
+---
+
+### 2. Plan
+
+**Mode selection criteria:**
+- **Quick** (2-5 min): Exploration, broad overview, time-sensitive
+- **Standard** (5-10 min): Most use cases, balanced depth/speed [DEFAULT]
+- **Deep** (10-20 min): Important decisions, need thorough verification
+- **UltraDeep** (20-45 min): Critical analysis, maximum rigor
+
+**Announce plan and execute:**
+- Briefly state: selected mode, estimated time, Sonar status, number of sources
+- Example: "Starting standard mode research (5-10 min, Sonar + 15-30 supplementary sources)"
+- Proceed without waiting for approval
+
+---
+
+### 3. Act (Phase Execution)
+
+**All modes execute:**
+- Phase 1: SCOPE - Define boundaries ([method](./reference/methodology.md#phase-1-scope))
+- **Phase 3: RETRIEVE - Sonar-first parallel information gathering** (see below)
+- Phase 8: PACKAGE - Generate report using [template](./templates/report_template.md)
+
+**Standard/Deep/UltraDeep execute:**
+- Phase 2: PLAN - Strategy formulation
+- Phase 4: TRIANGULATE - Verify 3+ sources per claim
+- Phase 4.5: OUTLINE REFINEMENT - Adapt structure based on evidence (WebWeaver 2025)
+- Phase 5: SYNTHESIZE - Generate novel insights
+
+**Deep/UltraDeep execute:**
+- Phase 6: CRITIQUE - Red-team analysis
+- Phase 7: REFINE - Address gaps
+
+---
+
+### Phase 3: RETRIEVE — Sonar-First Parallel Gathering
+
+**Step 3.0: Resolve API Key**
+```bash
+# Attempt to read from DeepQuark auth store
+python3 -c "
+import json, os
+p = os.path.expanduser('~/.local/share/deepquark/auth.json')
+if os.path.exists(p):
+    d = json.load(open(p))
+    k = d.get('duckmind').get('key')
+    print(k or '')
+"
+```
+
+**Step 3.1: Sonar Deep Research Call (Primary)**
+
+Write `sonar_research.py` to `/tmp/` and execute:
+```bash
+python3 /tmp/sonar_research.py "[full research question]" "[mode]"
+```
+
+- Timeout: 120 seconds
+- On success: Parse output → extract findings + citations → add to report backbone
+- On failure: Log fallback warning → proceed to Step 3.2
+
+**Step 3.2: Gap Analysis**
+
+After reviewing Sonar output, identify topics not covered or needing verification. These gaps drive supplementary WebSearch queries.
+
+**Step 3.3: Parallel Supplementary Searches**
+
+Launch ALL remaining searches in a **single message** (multiple tool calls simultaneously):
+
+```
+[Single message — ALL tool calls launched at once]
+WebSearch #1: [gap topic 1]
+WebSearch #2: [gap topic 2]
+WebSearch #3: Recent 2024-2025 developments
+WebSearch #4: Academic / primary source verification
+WebSearch #5: Critical perspectives / counterarguments
+WebSearch #6: Industry / market data
+Task agent #1: Deep-dive on [specific sub-topic]
+Task agent #2: Primary source document review
+```
+
+**❌ WRONG — sequential:**
+```
+Sonar → wait → WebSearch #1 → wait → WebSearch #2 → wait...
+```
+
+**✅ CORRECT — parallel after Sonar:**
+```
+Sonar call (Step 3.1) → Parse gaps → Launch ALL supplementary searches simultaneously (Step 3.3)
+```
+
+**Quality threshold monitoring (FFS pattern):**
+- Track source count and average credibility score
+- Sonar contributes a baseline of ~10-20 sources at 70+ credibility
+- Supplementary searches bring total to mode-specific threshold
+- Proceed to Phase 4 when threshold reached
+
+---
+
+**Critical: Avoid "Loss in the Middle"**
+- Place key findings at START and END of sections, not buried
+- Use explicit headers and markers
+- Structure: Summary → Details → Conclusion (not Details sandwiched)
+
+**Progressive Context Loading:**
+- Load [methodology](./reference/methodology.md) sections on-demand
+- Load [template](./templates/report_template.md) only for Phase 8
+- Do not inline everything - reference external files
+
+**Anti-Hallucination Protocol (CRITICAL):**
+- **Source grounding**: Every factual claim MUST cite a specific source immediately [N]
+- **Clear boundaries**: Distinguish between FACTS (from sources) and SYNTHESIS (your analysis)
+- **Explicit markers**: Use "According to [1]..." or "[1] reports..." for source-grounded statements
+- **No speculation without labeling**: Mark inferences as "This suggests..." not "Research shows..."
+- **Verify before citing**: If unsure whether source actually says X, do NOT fabricate citation
+- **When uncertain**: Say "No sources found for X" rather than inventing references
+- **Sonar-specific**: Sonar citations are pre-verified by Sonar's own retrieval. Still include in bibliography with URL if available.
+
+---
+
+### 4. Verify (Always Execute)
+
+**Step 1: Citation Verification (Catches Fabricated Sources)**
+
+```bash
+python scripts/verify_citations.py --report [path]
+```
+
+**Checks:**
+- DOI resolution (verifies citation actually exists)
+- Title/year matching (detects mismatched metadata)
+- Flags suspicious entries (2024+ without DOI, no URL, failed verification)
+
+**If suspicious citations found:**
+- Review flagged entries manually
+- Remove or replace fabricated sources
+- Re-run until clean
+
+**Step 2: Structure & Quality Validation**
+
+```bash
+python scripts/validate_report.py --report [path]
+```
+
+**8 automated checks:**
+1. Executive summary length (50-250 words)
+2. Required sections present (+ recommended: Claims table, Counterevidence)
+3. Citations formatted [1], [2], [3]
+4. Bibliography matches citations
+5. No placeholder text (TBD, TODO)
+6. Word count reasonable (500-10000)
+7. Minimum 10 sources
+8. No broken internal links
+
+**If fails:**
+- Attempt 1: Auto-fix formatting/links
+- Attempt 2: Manual review + correction
+- After 2 failures: **STOP** → Report issues → Ask user
+
+---
+
+### 5. Report
+
+**CRITICAL: Generate COMPREHENSIVE, DETAILED markdown reports**
+
+**File Organization (CRITICAL - Clean Accessibility):**
+
+**1. Create Organized Folder in Documents:**
+- ALWAYS create dedicated folder: `~/Documents/[TopicName]_Research_[YYYYMMDD]/`
+- Extract clean topic name from research question (remove special chars, use underscores/CamelCase)
+- Examples:
+  - "psilocybin research 2025" → `~/Documents/Psilocybin_Research_20251104/`
+  - "compare React vs Vue" → `~/Documents/React_vs_Vue_Research_20251104/`
+  - "AI safety trends" → `~/Documents/AI_Safety_Trends_Research_20251104/`
+- If folder exists, use it; if not, create it
+- This ensures clean organization and easy accessibility
+
+**2. Save All Formats to Same Folder:**
+
+**Markdown (Primary Source):**
+- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].md`
+- Also save copy to: `~/.claude/research_output/` (internal tracking)
+- Full detailed report with all findings
+
+**HTML (McKinsey Style - ALWAYS GENERATE):**
+- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].html`
+- Use McKinsey template: [mckinsey_template](./templates/mckinsey_report_template.html)
+- Design principles: Sharp corners (NO border-radius), muted corporate colors (navy #003d5c, gray #f8f9fa), ultra-compact layout, info-first structure
+- Place critical metrics dashboard at top (extract 3-4 key quantitative findings)
+- Use data tables for dense information presentation
+- 14px base font, compact spacing, no decorative gradients or colors
+- **Attribution Gradients (2025):** Wrap each citation [N] in `<span class="citation">` with nested tooltip div showing source details
+- OPEN in browser automatically after generation
+
+**PDF (Professional Print - ALWAYS GENERATE):**
+- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].pdf`
+- Use generating-pdf skill (via Task tool with general-purpose agent)
+- Professional formatting with headers, page numbers
+- OPEN in default PDF viewer after generation
+
+**3. File Naming Convention:**
+All files use same base name for easy matching:
+- `research_report_20251104_psilocybin_2025.md`
+- `research_report_20251104_psilocybin_2025.html`
+- `research_report_20251104_psilocybin_2025.pdf`
+
+**Length Requirements (UNLIMITED with Progressive Assembly):**
+- Quick mode: 2,000+ words (baseline quality threshold)
+- Standard mode: 4,000+ words (comprehensive analysis)
+- Deep mode: 6,000+ words (thorough investigation)
+- UltraDeep mode: 10,000-50,000+ words (NO UPPER LIMIT - as comprehensive as evidence warrants)
+
+**How Unlimited Length Works:**
+Progressive file assembly allows ANY report length by generating section-by-section.
+Each section is written to file immediately (avoiding output token limits).
+Complex topics with many findings? Generate 20, 30, 50+ findings - no constraint!
+
+**Content Requirements:**
+- Use [template](./templates/report_template.md) as exact structure
+- Generate each section to APPROPRIATE depth (determined by evidence, not word targets)
+- Include specific data, statistics, dates, numbers (not vague statements)
+- Multiple paragraphs per finding with evidence (as many as needed)
+- Each section gets focused generation attention
+- DO NOT write summaries - write FULL analysis
+
+**Writing Standards:**
+- **Narrative-driven**: Write in flowing prose. Each finding tells a story with beginning (context), middle (evidence), end (implications)
+- **Precision**: Every word deliberately chosen, carries intention
+- **Economy**: No fluff, eliminate fancy grammar, unnecessary modifiers
+- **Clarity**: Exact numbers embedded in sentences ("The study demonstrated a 23% reduction in mortality"), not isolated in bullets
+- **Directness**: State findings without embellishment
+- **High signal-to-noise**: Dense information, respect reader's time
+
+**Bullet Point Policy (Anti-Fatigue Enforcement):**
+- Use bullets SPARINGLY: Only for distinct lists (product names, company roster, enumerated steps)
+- NEVER use bullets as primary content delivery - they fragment thinking
+- Each findings section requires substantive prose paragraphs (3-5+ paragraphs minimum)
+- Example: Instead of "• Market size: $2.4B" write "The global market reached $2.4 billion in 2023, driven by increasing consumer demand and regulatory tailwinds [1]."
+
+**Anti-Fatigue Quality Check (Apply to EVERY Section):**
+Before considering a section complete, verify:
+- [ ] **Paragraph count**: ≥3 paragraphs for major sections (## headings)
+- [ ] **Prose-first**: <20% of content is bullet points (≥80% must be flowing prose)
+- [ ] **No placeholders**: Zero instances of "Content continues", "Due to length", "[Sections X-Y]"
+- [ ] **Evidence-rich**: Specific data points, statistics, quotes (not vague statements)
+- [ ] **Citation density**: Major claims cited within same sentence
+
+**If ANY check fails:** Regenerate the section before moving to next.
+
+**Source Attribution Standards (Critical for Preventing Fabrication):**
+- **Immediate citation**: Every factual claim followed by [N] citation in same sentence
+- **Quote sources directly**: Use "According to [1]..." or "[1] reports..." for factual statements
+- **Distinguish fact from synthesis**:
+  - ✅ GOOD: "Mortality decreased 23% (p<0.01) in the treatment group [1]."
+  - ❌ BAD: "Studies show mortality improved significantly."
+- **No vague attributions**:
+  - ❌ NEVER: "Research suggests...", "Studies show...", "Experts believe..."
+  - ✅ ALWAYS: "Smith et al. (2024) found..." [1], "According to FDA data..." [2]
+- **Label speculation explicitly**:
+  - ✅ GOOD: "This suggests a potential mechanism..." (analysis, not fact)
+  - ❌ BAD: "The mechanism is..." (presented as fact without citation)
+- **Admit uncertainty**:
+  - ✅ GOOD: "No sources found addressing X directly."
+  - ❌ BAD: Fabricating a citation to fill the gap
+- **Template pattern**: "[Specific claim with numbers/data] [Citation]. [Analysis/implication]."
+
+**Deliver to user:**
+1. Executive summary (inline in chat)
+2. Organized folder path (e.g., "All files saved to: ~/Documents/Psilocybin_Research_20251104/")
+3. Confirmation of all three formats generated:
+   - Markdown (source)
+   - HTML (McKinsey-style, opened in browser)
+   - PDF (professional print, opened in viewer)
+4. Source quality assessment summary: total source count, Sonar contribution, WebSearch contribution
+5. Next steps (if relevant)
+
+**Generation Workflow: Progressive File Assembly (Unlimited Length)**
+
+**Phase 8.1: Setup**
+```bash
+mkdir -p ~/Documents/[folder_name]
+# Create initial markdown file with frontmatter
+```
+
+**Phase 8.2: Progressive Section Generation**
+
+**CRITICAL STRATEGY:** Generate and write each section individually to file using Write/Edit tools.
+This allows unlimited report length while keeping each generation manageable.
+
+**OUTPUT TOKEN LIMIT SAFEGUARD (CRITICAL - Claude Code Default: 32K):**
+
+Claude Code default limit: 32,000 output tokens (≈24,000 words total per skill execution)
+This is a HARD LIMIT and cannot be changed within the skill.
+
+**What this means:**
+- Total output (your text + all tool call content) must be <32,000 tokens
+- 32,000 tokens ≈ 24,000 words max
+- Leave safety margin: Target ≤20,000 words total output
+
+**Realistic report sizes per mode:**
+- Quick mode: 2,000-4,000 words ✅ (well under limit)
+- Standard mode: 4,000-8,000 words ✅ (comfortably under limit)
+- Deep mode: 8,000-15,000 words ✅ (achievable with care)
+- UltraDeep mode: 15,000-20,000 words ⚠️ (at limit, monitor closely)
+
+**For reports >20,000 words:**
+User must run skill multiple times:
+- Run 1: "Generate Part 1 (sections 1-6)" → saves to part1.md
+- Run 2: "Generate Part 2 (sections 7-12)" → saves to part2.md
+- User manually combines or asks Claude to merge files
+
+**Auto-Continuation Strategy (TRUE Unlimited Length):**
+
+When report exceeds 18,000 words in single run:
+1. Generate sections 1-10 (stay under 18K words)
+2. Save continuation state file with context preservation
+3. Spawn continuation agent via Task tool
+4. Continuation agent: Reads state → Generates next batch → Spawns next agent if needed
+5. Chain continues recursively until complete
+
+**Initialize Citation Tracking:**
+```
+citations_used = []  # Maintain throughout — includes both Sonar and WebSearch citations
+sonar_citation_map = {}  # Maps Sonar's internal [N] → master report [N]
+```
+
+**Section Generation Loop:**
+
+Generate section content → Write/Edit tool → Move to next section
+Each Write/Edit call contains ONE section (≤2,000 words per call)
+
+1. **Executive Summary** (200-400 words) → Write
+2. **Introduction** (400-800 words) → Edit/append
+3. **Findings** — one Edit per finding (600-2,000 words each)
+4. **Synthesis & Insights** → Edit/append
+5. **Limitations & Caveats** → Edit/append
+6. **Recommendations** → Edit/append
+7. **Bibliography (CRITICAL)** — COMPLETE, all citations, no ranges, no placeholders → Edit/append
+8. **Methodology Appendix** — include note on Sonar Deep Research usage → Edit/append
+
+**Phase 8.3: Auto-Continuation Decision Point**
+
+After generating sections, check word count. If ≤18,000 words: complete normally. If will exceed: invoke Auto-Continuation Protocol (save state JSON, spawn continuation agent via Task tool — same as original skill).
+
+**Generate HTML (McKinsey Style)**
+1. Read McKinsey template from `./templates/mckinsey_report_template.html`
+2. Extract 3-4 key quantitative metrics for dashboard
+3. Use `python scripts/md_to_html.py [markdown_path]` for conversion
+4. Add citation tooltips (optional, for speed)
+5. Replace all `{{PLACEHOLDERS}}` in template
+6. **NO EMOJIS** in final HTML
+7. Save and verify: `python scripts/verify_html.py --html [html] --md [md]`
+8. Open in browser: `open [html_path]`
+
+**Generate PDF**
+1. Use Task tool with general-purpose agent
+2. Invoke generating-pdf skill with markdown as input
+3. Save and open
+
+---
+
+## Output Contract
+
+**Format:** Comprehensive markdown report following [template](./templates/report_template.md) EXACTLY
+
+**Required sections (all must be detailed):**
+- Executive Summary (2-3 concise paragraphs, 50-250 words)
+- Introduction (2-3 paragraphs: question, scope, methodology, assumptions)
+- Main Analysis (4-8 findings, each 300-500 words with citations)
+- Synthesis & Insights (500-1000 words)
+- Limitations & Caveats (2-3 paragraphs)
+- Recommendations (3-5 immediate actions, 3-5 next steps, 3-5 further research)
+- **Bibliography (COMPLETE — every citation, no truncation)**
+- Methodology Appendix (must note use of Sonar Deep Research via OpenRouter, model `perplexity/sonar-deep-research`, and any fallback to WebSearch-only mode)
+
+**Bibliography Requirements (ZERO TOLERANCE):**
+- ✅ MUST include EVERY citation [N] used in report body
+- ✅ Format: [N] Author/Org (Year). "Title". Publication. URL (Retrieved: Date)
+- ✅ For Sonar-sourced citations: note "(via Sonar Deep Research)" if URL not directly verifiable
+- ❌ NO placeholders, ranges, or truncation
+- ⚠️ Report is unusable without complete bibliography
+
+**Strictly Prohibited:**
+- Placeholder text (TBD, TODO, [citation needed])
+- Uncited major claims
+- Broken links
+- Missing required sections
+- Short summaries instead of detailed analysis
+- Vague statements without specific evidence
+
+**Writing Standards (Critical):**
+- Narrative-driven, precision, economy, clarity, directness, high signal-to-noise
+- Bullet discipline: prose paragraphs by default, bullets only for distinct lists
+- Precision examples:
+  - Bad: "significantly improved outcomes" → Good: "reduced mortality 23% (p<0.01)"
+  - Bad: "several studies suggest" → Good: "5 RCTs (n=1,847) show"
+
+**Quality gates (enforced by validator):**
+- Minimum 2,000 words (standard mode)
+- Average credibility score >60/100
+- 3+ sources per major claim
+- Clear facts vs. analysis distinction
+- All sections present and detailed
+
+---
+
+## Error Handling & Stop Rules
+
+**Stop immediately if:**
+- 2 validation failures on same error → Pause, report, ask user
+- <5 sources after exhaustive search (Sonar + WebSearch) → Report limitation, request direction
+- User interrupts/changes scope → Confirm new direction
+
+**Graceful degradation:**
+- Sonar unavailable → Fall back to WebSearch-only, note in methodology
+- 5-10 sources → Note in limitations, proceed with extra verification
+- Time constraint reached → Package partial results, document gaps
+- High-priority critique issue → Address immediately
+
+**Error format:**
+```
+⚠️ Issue: [Description]
+📊 Context: [What was attempted]
+🔍 Tried: [Resolution attempts]
+💡 Options:
+   1. [Option 1]
+   2. [Option 2]
+   3. [Option 3]
+```
+
+---
+
+## Quality Standards (Always Enforce)
+
+Every report must:
+- 10+ sources (document if fewer; Sonar typically contributes 10-20 by itself)
+- 3+ sources per major claim
+- Executive summary <250 words
+- Full citations with URLs
+- Credibility assessment
+- Limitations section
+- Methodology documented (including Sonar usage / fallback status)
+- No placeholders
+
+**Priority:** Thoroughness over speed. Quality > speed.
+
+---
+
+## Inputs & Assumptions
+
+**Required:**
+- Research question (string)
+
+**Optional:**
+- Mode (quick/standard/deep/ultradeep)
+- Time constraints
+- Required perspectives/sources
+- Output format
+- `DUCKMIND_API_KEY` or DeepQuark auth store configured (enables Sonar; falls back gracefully if absent)
+
+**Assumptions:**
+- User requires verified, citation-backed information
+- 10-50 sources available on topic
+- Time investment: 5-45 minutes
+
+---
+
+## When to Use / NOT Use
+
+**Use when:**
+- Comprehensive analysis (10+ sources needed)
+- Comparing technologies/approaches/strategies
+- State-of-the-art reviews
+- Multi-perspective investigation
+- Technical decisions
+- Market/trend analysis
+
+**Do NOT use:**
+- Simple lookups (use WebSearch)
+- Debugging (use standard tools)
+- 1-2 search answers
+- Time-sensitive quick answers
+
+---
+
+## Scripts (Offline, Python stdlib only)
+
+**Location:** `./scripts/`
+
+- **sonar_research.py** — OpenRouter / Sonar Deep Research invocation (inline in Phase 3)
+- **research_engine.py** - Orchestration engine
+- **validate_report.py** - Quality validation (8 checks)
+- **citation_manager.py** - Citation tracking
+- **source_evaluator.py** - Credibility scoring (0-100)
+
+**No external dependencies required.**
+
+---
+
+## Progressive References (Load On-Demand)
+
+- [Complete Methodology](./reference/methodology.md) - 8-phase details
+- [Report Template](./templates/report_template.md) - Output structure
+- [README](./README.md) - Usage docs
+- [Quick Start](./QUICK_START.md) - Fast reference
+- [Competitive Analysis](./COMPETITIVE_ANALYSIS.md) - vs OpenAI/Gemini
+
+---
+
+<!-- STATIC CONTEXT BLOCK END -->
+<!-- ⚡ Above content is cacheable (>1024 tokens, static) -->
+<!-- 📝 Below: Dynamic content (user queries, retrieved data, generated reports) -->
+
+---
+
+## Dynamic Execution Zone
+
+**User Query Processing:**
+[User research question will be inserted here during execution]
+
+**Retrieved Information:**
+[Sonar Deep Research output + supplementary WebSearch results accumulated here]
+
+**Generated Analysis:**
+[Findings, synthesis, and report content generated here]
+
+**Note:** This section remains empty in the skill definition. Content populated during runtime only.