deep-research

/deep-research — Multi-Dimensional Deep Research

Checkpointing

This skill uses file-system checkpoints under ${CLAUDE_PLUGIN_DATA}/checkpoints/. The orchestrator creates a JSON checkpoint file at skill start and updates it after each research phase (dimensions confirmed, research complete, synthesis complete). On completion, set status: "completed". On error, set status: "error".

The checkpoint file is ${CLAUDE_PLUGIN_DATA}/checkpoints/deep-researcher-<topic-slug>.json and follows this schema:

{
  "version": 1,
  "topic": "W3C annotation tools",
  "topic_slug": "w3c-annotation-tools",
  "status": "in_progress",
  "phase": 4,
  "phase_name": "Parallel Deep Dive",
  "depth": "standard",
  "format": "md",
  "dimensions": ["dim-01-tools-landscape", "dim-02-technical-architecture", "..."],
  "completed_dimensions": ["dim-01-tools-landscape"],
  "groupings_path": null,
  "synthesis_path": null,
  "created_at": "2026-05-06T16:00:00Z",
  "updated_at": "2026-05-06T16:30:00Z",
  "error": null
}

Status values: in_progress, paused, error, completed

Lifecycle

1. Create -- at skill start (Phase 1), create deep-researcher-<topic-slug>.json with status: in_progress, phase: 1.
2. Update -- after each major phase: dimensions confirmed (phase 3 done), research complete (phase 4 done), synthesis complete (phase 5 done), report pipeline complete (phase 6.5 done), delivery complete (phase 7 done).
3. Pause -- when waiting for user input (e.g., dimension confirmation), update with status: paused, phase: 3.
4. Error -- on handler error, update with status: error and error string.
5. Complete -- after Phase 7, update with status: completed.
6. Resume -- on skill invocation, check for existing checkpoint with matching topic slug. If found and status is in_progress or paused, offer resume.

Subagent Rolling Checkpoints

Researcher subagents write rolling checkpoints when cumulative read volume crosses 2000-line multiples. Path: ${CLAUDE_PLUGIN_DATA}/checkpoints/deep-researcher-<session-id>-checkpoint-<NNN>.md

Where <session-id> is the ISO timestamp from the subagent's scratch filename and <NNN> is zero-padded increment (001, 002, ...).

Trigger

Invoked with /deep-research followed by a topic and optional flags.

/deep-research <topic> [--depth quick|standard|deep] [--visualize]

• <topic> -- The research subject. Can be a technology, market, product category, architectural pattern, or problem space.
• --depth -- Research intensity tier. Default: standard.
  • quick: 3-5 dimensions, ~5 searches each, 1-2 page report
  • standard: 6-10 dimensions, ~10 searches each, 3-5 page report
  • deep: 10-15 dimensions, ~20 searches each, 8-12 page report
• --visualize -- After research completes, generate HTML report and open in browser. Chains to the visualize skill with the research output directory.

Capture ${ARGUMENTS} so the topic and flags are available throughout the workflow.

Purpose

Gather pre-build intelligence across multiple analytical dimensions using parallel subagents. Each dimension is researched independently, then synthesized into a unified report with confidence tiers, conflict zones, and cross-dimensional insights.

Typical use cases:

• Tech stack evaluation ("W3C annotation tools vs alternatives")
• Competitive landscape ("AI chip market 2025")
• Pre-build research ("What's the state of local-first databases?")
• Integration research ("How does OAuth2 integrate with our current auth?")

Output Directory

When output_dir is configured in plugin settings, use <output_dir>/research/<topic-slug>/. Otherwise use ${CLAUDE_PLUGIN_DATA}/research/<topic-slug>/.

All durable artifacts live under the research output directory:

• synthesis.md -- cross-verification and insight extraction
• groupings.json -- page groupings produced by Phase 6.5 Grouping step
• page-N.md -- coherence-written report pages (one per page group)
• report.html / report-offline.html -- HTML output (only if --visualize)
• dim-{NN}-{kebab-title}/ -- per-dimension directory
  • findings.md -- structured findings with citations
  • sources.md -- raw URLs, excerpts, quality tiers
  • side assets -- diagrams, code snippets, tables, images

Workflow

CRITICAL — Pipeline Execution Order. The following flow is the ONLY valid execution sequence. You MUST follow it exactly. Do not skip steps, reorder steps, or proceed to the next step until the current step's checkpoint artifact exists on disk. Each step's procedure doc is the authoritative reference for that step.

flowchart TD
    A["Phase 1-5: Orient → Dimensions → Deep Dive → Synthesis"] --> B["Enrichment"]
    B --> C["Grouping"]
    C --> D["Executive Summary"]
    D --> E["Coherence Writing"]
    E --> F{"Citations exist?"}
    F -- yes --> G["Appendix"]
    F -- no --> J["Phase 7: Delivery"]
    G --> I["Peer Review"]
    I --> J
    J --> K{"--visualize?"}
    K -- yes --> L["HTML Emission"]
    K -- no --> M["Done"]
    L --> M

Each Report Pipeline step has a procedure doc:

• Enrichment → pipeline-steps/enrichment.md
• Grouping → pipeline-steps/grouping.md
• Executive Summary → pipeline-steps/executive-summary.md
• Coherence Writing → pipeline-steps/coherence.md
• Appendix → pipeline-steps/appendix.md
• Peer Review → pipeline-steps/peer-review.md

Read the procedure doc before executing each step. The procedure doc contains the exact prompts, shell commands, validation checks, and retry logic for that step. Do not improvise — follow the procedure.

Resume: if the session was interrupted, follow the checkpoint-resume procedure in ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/resume.md to detect the last completed phase and resume from there.

Subagent output protocol: every subagent spawn follows the protocol defined below. The orchestrator prepends the Spawn Preamble to each spawn prompt.

CRITICAL — subagent_type: The only valid subagent_type for all spawns in this skill is deep-researcher:deep-researcher. Never use the bare name deep-researcher — it will fail with "agent type not found". Never use any other agent type. This applies to every role: researcher, synthesis, enrichment, grouping, executive-summary, coherence, appendix, peer-review.

Scratch file path convention: ${CLAUDE_PLUGIN_DATA}/scratch/deep-researcher-<ISO-timestamp>-<random-12>.md

Where:

• <ISO-timestamp> = output of date -u +%Y-%m-%dT%H-%M-%SZ
• <random-12> = 12 hex chars generated via bash -c 'printf "%08x%04x" $RANDOM $RANDOM'

Spawn Preamble

The orchestrator prepends this block to EVERY subagent spawn:

## Output Protocol
You are a subagent. Write your full output to exactly this path:

  <WRITE-PATH>

Begin the file with this YAML frontmatter:

---
schema_version: 1
verdict: complete | blocked | defer | timeout
summary: "<=140 chars, single line, decision-grade"
agent: deep-researcher:deep-researcher
produced_at: <ISO-8601 UTC>
followups: <integer>
next: orchestrator-decides | none
time_budget_seconds: <integer>
elapsed_seconds: <integer>
---

Then the sentinel line: <!-- end-frontmatter -->

Write the body below. Return ONLY a one-line confirmation with the absolute path -- do not echo the file body in your reply.

Time budget enforcement (CRITICAL): Every spawn prompt includes time_budget_seconds and started_at (Unix epoch, set by orchestrator via date +%s before spawning). The subagent MUST check elapsed time after every round boundary (after completing a search batch, after completing fetches, after each enrichment or synthesis pass). Check with:

elapsed=$(( $(date +%s) - <started_at> ))

If elapsed >= time_budget_seconds, stop immediately — do not start the next round or pass. Write whatever findings exist so far to the output file with verdict: timeout and a summary noting how far you got. The orchestrator handles timeout verdicts as partial results.

Time budgets per depth tier:

• quick: 300 seconds (5 min)
• standard: 600 seconds (10 min)
• deep: 1200 seconds (20 min)

Orchestrator Read Rule

• Read frontmatter only via Read(<path>, limit: 30). Act on verdict, summary, followups, next.
• Body reads only when a branching decision requires body content. Prefer spawning another subagent.
• Never paste a subagent's body into the next subagent's prompt. Pass the path.

Subagent File-Write Verification (CRITICAL)

Background subagents may return content in their task result text but fail to persist the file to disk. After EVERY subagent completes:

1. Check the file exists: test -s <WRITE-PATH> (exists AND non-empty).
2. If file is missing but result contains content: extract the content from the task result/notification and write it to <WRITE-PATH> yourself.
3. If file is missing and result is empty: retry the subagent once. If retry also fails, log a warning and proceed (do not block the pipeline).

This verification applies to ALL subagent spawns: researchers, synthesis, enrichment, coherence, peer-review. Never assume a file was written just because the subagent reported success.

Phase 1: Orient (~30 seconds)

Dialog with the user to establish:

• Scope boundary -- what is in scope, what is explicitly out
• Depth tier -- quick / standard / deep (default: standard)
• Visualize -- whether to generate HTML report (default: no, use --visualize)
• Audience -- technical experts, executives, general audience
• Time constraints -- any date range (e.g., "last 2 years")

Do not proceed to Phase 2 without user confirmation.

Compute a topic slug from the topic string: lowercase, replace non-alphanumeric with hyphens, collapse multiple hyphens.

Store the topic slug as $TOPIC for use in all subsequent phases.

Phase 2: Landscape Scan (~3-5 minutes)

At the start of Phase 2, create the shared failed-domains scratch file:

SESSION_START=$(date -u +%Y-%m-%dT%H-%M-%SZ)
FAILED_DOMAINS_FILE="${CLAUDE_PLUGIN_DATA}/scratch/${TOPIC}-${SESSION_START}-failed-domains.txt"
touch "$FAILED_DOMAINS_FILE"

Store $FAILED_DOMAINS_FILE — it is passed to every researcher subagent in its spawn prompt and used by all parallel researchers to share domain ban state.

The orchestrator performs Phase 2 directly — no subagent is spawned here. Call WebSearch yourself (never Bash curl/wget). Do 3-5 quick orientation searches:

• Macro overview: broad queries, industry reports, high-level statistics
• Structural mapping: key players, market structure, regulatory bodies
• Emerging issues: recent developments, conflicting narratives

After each search, record in the orchestrator's internal state:

• 2-3 key findings with source URLs
• Dominant narratives identified
• Gaps or contradictions detected
• Whether the topic warrants deeper investigation

If the landscape scan reveals the topic is too narrow or already well-understood, surface this to the user and offer to downgrade depth or abort.

Phase 3: Dimension Decomposition (~2 minutes)

Based on landscape findings, define 6-10 research dimensions. Each dimension:

• Approaches the topic from a distinct analytical angle
• Has >=30% conceptual overlap with at least one other dimension (for cross-verification)
• Covers: current state, key evidence, tensions/counter-arguments

Dimension types to consider:

• Technical / engineering / implementation
• Market / commercial / competitive
• Regulatory / policy / legal
• Economic / financial / cost structures
• User / consumer / adoption patterns
• Historical evolution / time horizon
• Geographic / regional variations
• Ethical / social / workforce implications
• Integration / compatibility with existing stack
• Community maturity / maintenance status

For each dimension, produce:

• Dimension name (1-3 words)
• Specific research question
• Expected mode: web or codebase (auto-detected; override with --web or --codebase)
• Expected source types

CHECKPOINT: User Confirm Dimensions

Present the dimension list to the user:

• Dimension names + research questions
• Mode per dimension (web / codebase)
• Expected search count per dimension
• Estimated total time

Wait for user approval, edits, or scope adjustments before spawning researchers.

Phase 4: Parallel Deep Dive (~10-30 minutes)

Spawn researcher subagents in parallel. Cap: 5 concurrent researchers. If dimensions exceed 5, batch in groups of 5.

Agent: deep-researcher:deep-researcher with role: researcher Write path: dimension findings go to scratch file per output protocol; durable artifacts go to the research output directory for that dimension.

Before spawning each researcher, capture the start time:

RESEARCHER_START=$(date +%s)

Per-dimension spawn prompt includes:

• Dimension scope and research question
• Depth-tier search budget (5 / 10 / 20 searches) — this is the Round 1 search count; the agent manages retry rounds internally
• Mode: web or codebase
• Source quality rules (T1/T2/Reject tiers)
• failed_domains_file: <FAILED_DOMAINS_FILE> — absolute path to the shared failed-domains file; append 5XX/down domains, check before every fetch
• time_budget_seconds: <300|600|1200> — 300 for quick, 600 for standard, 1200 for deep
• started_at: <RESEARCHER_START> — Unix epoch captured just before this spawn
• Output format: structured findings in scratch file per output protocol
• Extended frontmatter fields (dimension, mode, searches_conducted, sources_t1, sources_t2, sources_rejected, confidence_high, confidence_medium, confidence_low, time_budget_seconds, elapsed_seconds)

Note: The researcher subagent writes findings to its scratch file only. The orchestrator reads the scratch file and copies/structures the durable artifacts into the research output directory after the subagent returns.

For web mode: researcher uses WebSearch and WebFetch tools. For codebase mode: researcher uses targeted mode against the current project.

Failure handling (per researcher):

1. Internal retry: subagent retries failed searches/reads automatically
2. External retry: if still fails, orchestrator respawns the subagent once
3. User prompt: if fails again, orchestrator pauses and asks user: "Dimension X failed after 2 attempts. Reason: [Y]. Retry, skip, or reduce scope?"

Timeout handling (per researcher):

• verdict: timeout means the subagent hit the time budget mid-work and wrote partial findings. Treat partial findings as usable — do not discard them.
• Present to the user: "Dimension X hit the time limit ({elapsed}s / {budget}s). Partial findings saved. Continue with what was found, give it more time (+5/+10 min), or skip this dimension?"
• If the user grants more time: respawn with a new started_at and the additional seconds added to time_budget_seconds. Pass the existing partial findings path so the subagent can build on them rather than starting over.
• If the user skips: mark the dimension as partial in the delivery summary.

Satisfaction-failure handling (per researcher):

• verdict: defer means the subagent exhausted all 3 rounds (2 retries) and still failed one or more satisfaction conditions. It has partial findings and the summary names the unsatisfied conditions.
• Present to the user: "Dimension X completed all search rounds but satisfaction check did not pass ({unsatisfied conditions from summary}). Partial findings saved. Accept what was found, run one more targeted round, or skip this dimension?"
• If the user accepts: treat findings as partial and continue pipeline — do not re-run.
• If the user grants another round: respawn with time_budget_seconds reset to the depth budget, new started_at, and the path to existing partial findings so the subagent appends rather than restarts.
• If the user skips: mark the dimension as skipped in the delivery summary.

Blocked handling (per researcher):

• verdict: blocked means all fetch attempts across all retry rounds failed (no usable content retrieved at all — domains down, all URLs 4XX/5XX, etc.).
• Present to the user: "Dimension X returned no usable content — all sources were unreachable or blocked. Retry with different search terms, skip this dimension, or replace it with a narrower scope?"
• If the user retries: respawn fresh (no partial findings to pass).
• If the user replaces scope: ask for the narrower question, update the dimension, and respawn.
• If the user skips: mark the dimension as blocked in the delivery summary.

Track completion status per dimension: complete, partial (timeout or accepted defer), skipped (user skipped), or blocked (no content). Do not proceed to Phase 5 until all dimensions have a final status or the user has made a decision on each outstanding one.

Phase 5: Cross-Verification & Synthesis (~5-10 minutes)

Spawn synthesis agent (agent: deep-researcher:deep-researcher, role: synthesis) with:

• Paths to all dimension findings.md files
• Instruction to read frontmatter for metadata, bodies for claims

Synthesis agent tasks:

• Classify every significant claim by confidence:
  • High: >=2 independent T1 sources agree
  • Medium: 1 T1 source OR >=2 T2 sources agree
  • Low: 1 T2 source OR weak evidence
  • Conflict Zone: sources disagree
• Stale Claim Scan (CRITICAL): Scan all findings for claims about future capabilities, browser support, or "not yet supported" status. Flag any claim where:
  • The source is dated >6 months before the research date
  • The claim uses phrases like "not supported", "no support", "not yet", "coming soon", "planned for", "does not support", "rejects"
  • The claim is about a rapidly-changing domain (browsers, APIs, frameworks) For each flagged claim, add a "Re-verify" note with the original source date and a suggestion for a current-source search query.
• Extract cross-dimensional insights (patterns visible only across dimensions)
• Document conflict zones with both sides and sources
• Note any dimensions that were skipped, partial, or blocked, and why

Output: <output-dir>/research/<topic-slug>/synthesis.md

Phase 6.5: Report Pipeline (~10-20 minutes)

This phase always runs. It is the only report generation path.

Enrichment

Spawn parallel enrichment subagents (max 5 concurrent), one per dimension file.

Each subagent:

• Reads its dimension's findings.md
• Appends a <dimension-synthesis> block to that findings.md
• Operation is idempotent -- safe to re-run without producing duplicate blocks

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/enrichment.md

Batch dimensions in groups of 5 if dimension count exceeds 5.

Agent: deep-researcher:deep-researcher with role: enrichment

Grouping

Spawn one grouping subagent that:

• Reads all <dimension-synthesis> blocks from the enriched findings.md files
• Produces <output-dir>/research/<topic-slug>/groupings.json

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/grouping.md

Agent: deep-researcher:deep-researcher with role: grouping

Executive Summary & Conclusion

Spawn one executive-summary subagent that:

• Reads synthesis.md
• Reads <dimension-synthesis> blocks from every dim-NN-*.md file
• Reads groupings.json to determine N (highest page number)
• Writes page-0.md (executive summary, 400-700 words)
• Writes page-{N+1}.md (conclusion, 400-700 words)
• Updates groupings.json with framing entries (page 0 and page N+1)

Both pages are marked with <!-- summary-page: skip-conflict-check --> at the top.

This step runs AFTER Grouping and BEFORE Coherence Writing.

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/executive-summary.md

Agent: deep-researcher:deep-researcher with role: executive-summary

Coherence Writing

Spawn one coherence subagent per page group (parallel, max 5 concurrent). Skip any page entry whose dimensions array is empty -- these are framing pages already written by Executive Summary.

Citations handoff — CRITICAL. Before spawning any coherence agent, the orchestrator MUST pre-compute the global citations table from all <citations> blocks across dimension files. The extraction and deduplication algorithm is defined in coherence.md Section 1. This table (referenced as {CITATIONS_TABLE}) is passed to every coherence subagent so it can emit inline citation markers (e.g. <a href="#appendix:cite-d1-c1" class="citation">[D1C1]</a>) throughout each page. Without this step, report pages will have no inline citation links pointing to the appendix.

Each subagent receives:

• Dimension file contents with synthesis and citations blocks stripped
• Pre-computed citations table ({CITATIONS_TABLE}) for this page group's dimensions
• groupings.json
• Sibling-page list (to avoid duplication across pages)

Each subagent outputs one page-{N}.md file per page group.

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/coherence.md

Agent: deep-researcher:deep-researcher with role: coherence

Appendix (conditional)

Run only if at least one dimension file contains a <citations> block. Detection:

found=0
for f in <output-dir>/research/${TOPIC}/dim-*/findings.md; do
  perl -0777 -ne 'exit 0 if /<citations>.*?<\/citations>/s; exit 1' "$f" 2>/dev/null && found=1 && break
done

When citations exist, spawn one appendix subagent that formats citations into appendix.md.

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/appendix.md

Agent: deep-researcher:deep-researcher with role: appendix

Peer Review -- Citation Audit (conditional, parallel)

Run if Appendix produced any citations. Audits ALL citation types: URL reachability, codebase file:line accuracy, and metric formula validity.

Split all citations into batches of <=50, spawn one peer-review subagent per batch concurrently (max 5 concurrent).

Procedure: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research/pipeline-steps/peer-review.md

Agent: deep-researcher:deep-researcher with role: peer-review

Phase 7: Delivery (~1 minute)

Present to user:

1. Report & Directory Paths Always present full absolute paths:

Report pages:
<ABSOLUTE_PATH>/research/<slug>/page-1.md
<ABSOLUTE_PATH>/research/<slug>/page-2.md
...

Research directory (all dimensions + synthesis):
<ABSOLUTE_PATH>/research/<slug>/

If --visualize was used, the HTML paths are printed in the visualize chaining section below.

2. Dimension Summary -- table of dimensions with status (complete / partial / skipped / blocked) and file sizes.

3. Search Statistics -- total queries, T1/T2/Rejected source counts, subagents spawned.

4. Confidence Summary -- High / Medium / Low / Conflict counts.

5. Key Findings at a Glance -- 3-5 bullet-pointed top-level takeaways.

6. Known Gaps -- unresolved questions, source volatility, pre-GA risks.

7. Artifact Inventory -- tree listing of all files in the research directory.

8. Human Review Invitation -- explicit call for user review on 2-3 high-stakes decisions.

--visualize Chaining

When --visualize was passed, after Phase 7 delivery, proceed to generate HTML output from the research report. Follow the visualize skill workflow:

1. Resolve the topic directory to <output-dir>/research/<topic-slug>/.
2. Verify groupings.json exists (it always will after Phase 6.5).
3. Invoke the emitter:

   npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/scripts/reportPipelineEmitter.ts \
     --groupings <output-dir>/research/<topic-slug>/groupings.json \
     --theme editorial \
     --plugin-dir ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/
   

4. Run visual verification (scan for Mermaid issues, check console for errors if Playwright is available).
5. Print the file:// paths for report.html and report-offline.html.
6. Open report-offline.html in the system browser (open on macOS, xdg-open on Linux).

The default theme is editorial. The user selected --visualize from the research command which does not accept --theme; if they want a different theme they should run /deep-research-visualize separately.

Task Tracking

The orchestrator uses the Task tool to track pipeline progress. Task state is derived from filesystem checkpoints (see pipeline-steps/resume.md), so tasks always reflect reality — they are never the single source of truth.

Task Structure

On pipeline start, create one parent task and child tasks for each phase:

TaskCreate: "Research: {TOPIC}"  → parent_id (root task)
TaskCreate: "Orient & Dimensions"  → child of root
TaskCreate: "Deep Dive (0/{N} dims)"  → child of root
TaskCreate: "Synthesis"  → child of root
TaskCreate: "Report Pipeline"  → child of root
TaskCreate: "Delivery"  → child of root

Report Pipeline gets sub-tasks created just-in-time as each sub-step begins:

TaskCreate: "Enrichment (0/{N})"  → child of Report Pipeline
TaskCreate: "Grouping"  → child of Report Pipeline
TaskCreate: "Executive Summary"  → child of Report Pipeline
TaskCreate: "Coherence (0/{P} pages)"  → child of Report Pipeline
TaskCreate: "Appendix"  → child of Report Pipeline  (only if citations exist)
TaskCreate: "Peer Review"  → child of Report Pipeline  (only if citations exist)

Task Lifecycle Rules

1. Mark in_progress when the phase begins execution.
2. Update description with progress counters as batches complete:
   • "Deep Dive (3/8 dims)" — after each researcher returns
   • "Coherence (2/3 pages)" — after each page is written
   • "Enrichment (5/8)" — after each enrichment agent returns
3. Mark completed when the filesystem checkpoint is confirmed:
   • Deep Dive: all dim-*/findings.md exist and are non-empty
   • Enrichment: all dim-*/findings.md contain <dimension-synthesis>
   • Grouping: groupings.json passes --validate-groupings
   • Coherence: all content pages exist on disk
   • Appendix: appendix.md exists (or marked completed with "skipped: no citations")
4. Skipped sub-steps are marked completed with a note:
   • "Appendix — skipped: no citations" if conditionality check fails
   • "Peer Review — skipped: no citations"

Resume: Re-hydrating Task State

On resume, the orchestrator:

1. Runs the checkpoint detection script from resume.md Section 2.
2. Creates the full task tree (if not already present from a prior session).
3. Walks the checkpoint results and marks completed phases accordingly:

For each phase up to RESUME_FROM:
  TaskUpdate: status = completed

For partial phases (Deep Dive, Enrichment, Coherence):
  TaskUpdate: status = in_progress, description includes progress counter
  (e.g., "Deep Dive (5/8 dims)" based on which findings.md files exist)

4. Reports the task tree state to the user as part of the resume summary.

Filesystem → Task Mapping

Filesystem checkpoint	Task action
dim-*/findings.md exists for all dims	Deep Dive → completed
synthesis.md exists	Synthesis → completed
All findings.md have <dimension-synthesis>	Enrichment → completed
groupings.json passes validation	Grouping → completed
page-0.md exists	Executive Summary → completed
All content page-N.md exist	Coherence → completed
appendix.md exists	Appendix → completed
Peer review entry in groupings.json	Peer Review → completed

The orchestrator never relies solely on task state to determine what to run. It always checks the filesystem. Tasks are a user-facing progress indicator, not a control plane.

Source Quality Tiers

T1 (Highest Credibility)

• .gov, .mil, .eu domains; SEC filings; patent databases
• Peer-reviewed journals (Nature, Science, IEEE, ACM, ACL)
• arXiv preprints (check peer review status)
• Official corporate engineering blogs (with author credentials)
• Open-source project documentation and API docs

T2 (Good Credibility)

• Reuters, Bloomberg, FT, WSJ
• MIT Technology Review, Wired, The Verge
• Gartner, IDC, Forrester, McKinsey, BCG (note paywalls)
• Brookings, RAND, Pew Research, EFF
• Quality Substack / Medium with verified author expertise

Reject (Low or No Credibility)

• Content farms, SEO aggregators, generic listicles
• Anonymous forums (unverified Reddit, 4chan, Quora)
• Wikipedia (orientation only, never primary citation)
• AI-generated content without human editorial oversight
• Vendor whitepapers without methodology disclosure
• Press releases with unverified claims

Constraints

• No ticket tracking. This skill writes to the research output directory and reports paths; it does not create or update ticket files.
• Orchestrator does lightweight planning only. Landscape scan (3-5 searches) and dimension decomposition happen in orchestrator context. All heavy reading and research is delegated to subagents.
• Max 5 parallel subagents. Batch larger dimension sets.
• Human checkpoint is mandatory. Dimensions must be user-confirmed before spawning researchers. Do not auto-proceed.
• Source quality enforcement. Every factual claim must cite a source or be explicitly labeled as speculation. Reject content farms, anonymous forums, and SEO aggregators.
• Never suppress conflicts. Contradictions get their own section.
• Rolling checkpoints. If a single-dimension researcher exceeds 2000 LOC of reading, it writes a checkpoint before continuing.
• SI units primary. All measurements use SI (metric) as the primary unit with US/imperial in parentheses: 24°C (75°F), 5 cm (2 in), 30 km (19 mi), 4 L (1 gal). This applies to all report output — findings, synthesis, coherence pages, and delivery summaries.