| name | oh-my-research |
| description | Intelligent orchestrator for high-quality deep research reports from collected materials and evidence. Auto-detects intent and workspace state, then routes to init, collect, deep analyze (with THINK paradigms such as first principles), optional decide/idea, synthesize survey/report, reconcile, or version. Single entry point for the report-first research lifecycle. |
| license | Apache-2.0 |
| metadata | {"version":"1.4.7","author":"Xiaming Chen","category":"workflow"} |
Oh-My-Research
Intelligent orchestrator for report-first deep research. Auto-detects user intent and workspace state, then executes the right mode — initialize, collect materials, deep-analyze with evidence boundaries and thinking paradigms, synthesize a survey/report, or maintain state.
North star: high-quality deep research reports from collected materials and evidence — not prototypes, not coding validation.
When to Use This Skill
- Start a research workspace on a topic
- Collect papers, URLs, repos, datasets
- Analyze materials into evidence maps and judgments
- Deepen analysis with first principles, Socratic, triangulation, etc. (THINK)
- Write a survey, report, manuscript, or brief
- Reconcile when new evidence contradicts prior claims
- Run the full Evidence-Deep workflow
Keywords: research, survey, literature review, evidence, collect papers, analyze, first principles, synthesize report, deep research, oh-my-research, omr
Core Pipeline (Evidence-Deep)
COLLECT materials → [Gate M] → ANALYZE (deep evidence + THINK) → [Gate A] → [Gate P] → SYNTH (survey / report)
Optional: IDEA, DECIDE (stance), RECONCILE. Default pattern: Evidence-Deep. See references/GRAPH.md and patterns/.
Auto-Detection Decision Tree
The agent runs intention detection first, then falls back to workspace-state detection. Canonical op names (init, collect, analyze, think, synth, decide, idea, reconcile, workflow, qa) always win over keyword routing.
flowchart TD
START([User request]) --> OP{Canonical op<br/>in request?}
OP -- Yes --> RUNOP[Run named op — wins]
OP -- No --> INT{Intent keywords?}
INT -- THINK keywords<br/>first principles, socratic,<br/>pre-mortem, red team, steelman,<br/>deepen, rethink, elicit, think --> THINK[THINK on latest artifact]
INT -- IDEA keywords<br/>idea, brainstorm, speculate,<br/>what if, hypothesis --> IDEA[IDEA mode]
INT -- COLLECT signals<br/>URL, DOI, arxiv, github,<br/>huggingface, search, collect --> COLLECT[COLLECT — init-on-demand<br/>if no workspace]
INT -- SYNTH keywords<br/>report, survey, write up,<br/>synthesize, manuscript, brief --> SYNTHGUARD{Phase-Guard:<br/>judgment + gate-a present?}
INT -- none --> STATE[Inspect workspace state]
COLLECT --> GATEM[Run Gate M:<br/>source diversity + sufficiency]
GATEM --> ANALYZE
SYNTHGUARD -- Yes --> SYNTH[SYNTH mode]
SYNTHGUARD -- No, missing --> BLOCKSYNTH[Show PHASE-GUARD<br/>offer ANALYZE first]
STATE --> S1{No AGENTS.md<br/>and no .omr/?}
S1 -- Yes --> INIT[INIT]
S1 -- No --> S2{Materials present,<br/>no judgment?}
S2 -- Yes --> GATEM
S2 -- No --> S3{Judgment present,<br/>no synth content?}
S3 -- Yes --> SYNTHGUARD
S3 -- No --> S4{loop-state active?}
S4 -- Yes --> GATEL[Gate L:<br/>iterate vs advance]
S4 -- No --> S5{Contradiction vs<br/>published claims?}
S5 -- Yes --> RECONCILE[Propose RECONCILE]
S5 -- No --> AMBIG[Ambiguous → ask user<br/>or show graph-recommended next]
GATEL --> AMBIG
THINK --> GATEA[Gate A / QA1]
GATEA --> SYNTHGUARD
BLOCKSYNTH --> ANALYZE
ANALYZE --> GATEA
Always show a phase label at the start of each action: [INIT], [COLLECT], [ANALYZE], [THINK], [SYNTH], [RECONCILE], [FINISHED] (plus [DECIDE] / [IDEA] when used).
Phase-Guard: Cross-Stage Jump Protection
Before routing to a stage, read .omr/tree-state.json and check whether the target stage is unlocked, ready, or completed. If locked, verify the required prerequisite artifacts exist on disk before proceeding. This prevents silent stage-skipping (e.g. user says "write report" → SYNTH keyword detected → but no judgment-*.md exists).
| Target stage | Required prerequisite artifacts | Required gate JSON | If missing |
|---|
| ANALYZE | materials/ with ≥1 source + docs/index/ entry | gate-m.json (source diversity + sufficiency, run during ANALYZE) | Route to COLLECT first |
| THINK | docs/plans/judgment-*.md or docs/plans/evidence-*.md | (none) | Route to ANALYZE first |
| SYNTH | docs/plans/judgment-*.md | gate-a.json (pass) + gate-p.json | Route to ANALYZE → THINK → Gate A → Gate P first |
| DECIDE | docs/plans/judgment-*.md | (none) | Route to ANALYZE first |
Blocking by default. The agent must not proceed past a missing prerequisite without either (a) satisfying the prerequisites or (b) receiving an explicit user override (e.g. "I know, just write the report" or "skip guard"). A general instruction like "write the report" does not count as an override. When overridden, record scenario_note: "prerequisite skipped by user override" in the next gate JSON for auditability.
Tree-state staleness: after every op, update .omr/tree-state.json — move completed stages to completed, unlock dependents, write a brief notes summary. A stale tree-state signals an interrupted workflow; check and refresh it at the start of any new op.
Operation Modes
| Mode | Op | One-line | Detail |
|---|
| INIT | init "<topic>" | Bootstrap workspace (only AGENTS.md + .omr/*.json; no empty folders) | references/INIT/init.md |
| COLLECT | collect <url|query|…> | Default papers+web+github+search (parallel bucket agents) → materials + indexes + full-text Markdown | references/COLLECT/collect.md |
| ANALYZE | analyze | Brief, evidence-map, judgment; reads full-text Markdown; Gate M before, Gate A / QA1 after, Gate T after THINK | references/ANALYZE/analyze.md |
| THINK | think [method] | Methodology-driven elicitation on research artifacts (never code); stamps hardened/refined/unchanged/killed | references/THINK/think.md, references/THINK/methods/ |
| SYNTH | synth [--mode] [--format docx|pdf|md] [--language] [--resume] [--chapter] [--no-wiki] | Incremental long reports in preferred language; Gate P confirms prefs; never one-shot a deep report | references/SYNTH/synth.md, references/SYNTH/long-report.md, references/LANGUAGE.md |
| IDEA | idea "…" | Capture speculative notes (optional) | references/IDEA/idea.md |
| DECIDE | decide | Stance / claim framing with ≥3 alternatives; Gate B (optional) | references/DECIDE/decide.md |
| RECONCILE | reconcile | Contradiction blast-radius, archive, rollback | references/RECONCILE/reconcile.md |
| VERSION | — | Workspace artifact versioning: tag, history, diff, backup, list | references/VERSION/version.md |
| WORKFLOW | workflow [--pattern P] |
Confirmation Gates
Default semi-automated (pause for confirm). Support "no confirmations" / quick-pass. Rapid pattern skips all gates (fully-automated).
| Gate | When |
|---|
| M | After COLLECT: source diversity & enough materials? Shows diversity report, asks user: collect more types or proceed? |
| L | Loop pattern: iterate vs advance |
| A / QA1 | After ANALYZE judgment, before unlock SYNTH |
| T | After THINK: collect more from surfaced gaps? |
| B | Only if DECIDE runs |
| P | Before SYNTH: language / format / mode / audience |
| Lenses | Structure → Prose → Adversarial before Gate D |
| D / QA2 | Before publishing SYNTH |
Post-Step Routing Menu (after Gate M / IDEA / Gate A / THINK proceed / Gate T / Gate B): (1) Pause at each gate (default) · (2) Quick pass · (3) Continue recommended (next graph edge) · (4) Run THINK · (5) Switch pattern · (6) Stop.
Default Paths
Paths below are logical destinations. Create a folder only when writing the first file into it (see references/INIT/init.md).
| Artifact | Path (when content exists) |
|---|
| State | .omr/ (tree-state, pattern, locale; other JSON as needed) |
| Materials | materials/{papers-raw,papers,web,github,datasets,search,failed}/ — papers: raw binaries in papers-raw/, Markdown in papers/ (same stem); other buckets only when they receive files |
| Indexes | docs/index/ (papers-index.json; workers use docs/index/inbox/ then merge) |
| Plans | docs/plans/ |
| Ideas | docs/ideas/ |
| Reports | docs/{survey,report,manuscript,brief}/ |
| Wiki | wiki/ |
| Archive | docs/archive/ |
Templates: assets/. Patterns: patterns/. Full operation reference: references/REFERENCE.md.
Best Practices
- Trust auto-detection; override with canonical ops when needed
- Phase-Guard before every stage (blocking by default) — read
.omr/tree-state.json, check prerequisites, show [PHASE-GUARD] if missing; never silently skip a stage
- Never create empty directories — mkdir only as the parent of a real file write
- Never upgrade
suggests → proven without stronger source language
- Use THINK (first principles / triangulation) before Gate A when confidence is low — in Evidence-Deep, THINK is offered by default after judgment, not only when confidence is low
- Run Gate M after every collect batch — default collect fills papers, web, github, and search (parallel bucket agents). Show the diversity report; warn if a default bucket is empty without an explicit opt-out. Prevents premature analysis on narrow or single-type corpora
- Write long reports chapter-by-chapter to disk; keep a pruned continuity brief; author
.omr/report-state.json to match the topic outline; resume if interrupted
- Prefer a professionally formatted DOCX, PDF, or Markdown deliverable in the preferred language (timezone/locale auto-detect via
LANGUAGE.md / .omr/locale.json, or explicit --language); drive its presentation via an LLM-authored _document.json (title, fonts, cover, TOC, header/footer, chapter order) rather than script defaults
- Keep internal traceability private; translate it into standard citations and natural prose
- Make the final report self-contained, professional, and accessible to its intended reader
- Run LLM QA checklists (adapt thresholds to the scenario); write results under
.omr/quality-gates/
- Write full reports to disk; reply in chat with summary only
- Run document lenses and visually inspect the rendered file before Gate D
- Update
.omr/tree-state.json after every op — move completed stages to completed, unlock next stages; never leave tree-state stale
Dependencies
- Read/write project workspace
- Agent-authored state under
.omr/ (tree, loop, report-state, quality-gates) — see references/LLM-STATE.md
- Mechanical scripts only:
export_report.py (thin, spec-driven DOCX/PDF/Markdown renderer applying LLM-authored _document.json; the Markdown deliverable passes Mermaid figures and GFM tables through verbatim), prefer_language.py (timezone/locale → BCP-47 language tag), version_control.py (workspace tags/backups), collect_cli.py (records source + invokes material_to_markdown.py; --id/--bucket/--inbox for parallel workers, --merge-inbox for the coordinator), material_to_markdown.py (downloads source via arxiv/DOI/URL; papers persist materials/papers-raw/<ID>.<ext> and convert to materials/papers/<ID>.md; other buckets write materials/<bucket>/<ID>.md; anydoc with pymupdf/pdfplumber/markdownify fallbacks; --convert-dir batch-converts pre-downloaded files), report_lint.py (publication-safety linter: scans report chapters for leaked internal IDs, evidence-grade labels, workflow jargon, gate names, and private paths)
python-docx / reportlab via scripts/requirements.txt for export; anydoc (npx -y @firecrawl/anydoc, Node 20+) for material → Markdown conversion; optional pymupdf / pdfplumber / markdownify / beautifulsoup4 as fallbacks if anydoc is unavailable
Deep Dive
references/REFERENCE.md — complete operation guide, artifact naming, evidence boundaries, tree state, troubleshootingreferences/GRAPH.md — pattern graphs, node ↔ artifact contracts, unlock rules, cyclesreferences/GATES.md — gate definitions and QA checklistsreferences/LLM-STATE.md — agent-owned state JSON schemasreferences/LANGUAGE.md — timezone/locale → preferred BCP-47 language tagreferences/COLLECT/collect.md — default four-bucket mix + parallel workersreferences/COLLECT/agents/bucket-worker.md — per-bucket collect agent
