---
name: docxology/research-workflow
source: https://app.decimal.ai/s/docxology-research-workflow@1/SKILL.md
source_sha256: 6dc7e5fd8434
---

# Research Workflow

Seven-stage research workflow scaffolding for AI-assisted research processes.
Each stage produces structured prompts and acceptance criteria for agent loops.

## Stages

| # | Stage | Purpose |
| --- | --- | --- |
| 1 | **SCOPE** | Define research question, scope, and success criteria |
| 2 | **LITERATURE** | Survey prior work; produce annotated bibliography |
| 3 | **REASON** | Identify gaps, contradictions, and open questions |
| 4 | **DESIGN** | Formulate methodology and experimental plan |
| 5 | **COMPUTE** | Execute analysis; collect and validate results |
| 6 | **SYNTHESIZE** | Interpret results relative to prior work |
| 7 | **WRITE** | Draft manuscript sections and iterative revision |

## Quick Start

```python
from infrastructure.research import ResearchWorkflow

# Print all stage descriptions
ResearchWorkflow.describe()

# Get a structured prompt for a specific stage
prompt = ResearchWorkflow.prompt("SCOPE", question="What drives protein misfolding?")
print(prompt)

# Iterate stages in order
for stage in ResearchWorkflow.stages():
    print(f"{stage.index}. {stage.name}: {stage.description}")
```

## Pipeline Orchestrator

```bash
# Run research workflow scaffolding for a named project
uv run python scripts/pipeline/stage_10_research_workflow.py --project my_project

# Run only specific stages
uv run python scripts/pipeline/stage_10_research_workflow.py --project my_project --stages SCOPE,LITERATURE

# Generate stage prompts without executing
uv run python scripts/pipeline/stage_10_research_workflow.py --project my_project --dry-run
```

## Config Integration

Set stage overrides in `projects/{name}/manuscript/config.yaml`:

```yaml
research_workflow:
  question: "How do transformer attention patterns relate to syntactic structure?"
  stages:
    SCOPE:
      depth: detailed
    LITERATURE:
      max_papers: 50
      sources:
        - arxiv
        - semantic_scholar
    WRITE:
      target_venue: NeurIPS
```

## Key Types

```python
from infrastructure.research import (
    ResearchWorkflow,        # instance API — workflow.stage(name) / all_stages() / describe()
    ResearchStage,           # Stage descriptor: name, label, description, inputs, outputs, gate, status, order
    ResearchWorkflowConfig,  # Parsed config.yaml `research_workflow:` block
)
```

> **Doc/code drift (tracked for follow-up):** the "Stages" table, `.prompt()`,
> `.stages()`, `.render()`, and `.record_output()` calls elsewhere in this
> file describe an OpenScience-ported design (uppercase SCOPE/LITERATURE/...
> stage names, per-stage sub-agent fan-out and prompt templates) that
> `ResearchWorkflow`/`ResearchStage` do not implement — the real stage names
> are lowercase (`scope, survey, hypothesise, experiment, validate, review,
> write`) and there is no `.prompt()`/`.stages()`/`.render()` API. Treat
> those sections as design intent, not a verified API surface.

## Stage Prompt Generation

```python
from infrastructure.research import ResearchWorkflow

# Generate LITERATURE stage prompt for a specific project
prompt = ResearchWorkflow.prompt(
    "LITERATURE",
    question="Neural scaling laws",
    context={"prior_papers": 12, "target_venue": "ICML"},
)
```

## Agent Loop Integration

```python
from infrastructure.research import ResearchWorkflow

# Use in an agent loop
for stage in ResearchWorkflow.stages():
    prompt = stage.render(project_context)
    response = llm_call(prompt)
    stage.record_output(response, output_dir="output/research/")
```

## Testing

```bash
uv run pytest tests/infra_tests/research/ -v
```

## See Also

- [`AGENTS.md`](AGENTS.md) — operating contract and architecture
- [`../search/SKILL.md`](../search/SKILL.md) — literature search integration
- [`../llm/SKILL.md`](../llm/SKILL.md) — LLM review integration