---
title: "Create Research"
description: "Documents how the codebase works today for a task's research questions and saves it as a research file (.ork/tasks/TASK/NN-research-SLUG.md) with file:line citations, so the plan builds on a reviewable record. Use before planning a change in unfamiliar code; describes, never proposes."
canonical: "https://orchestkit.dev/docs/reference/skills/create-research"
---

# Create Research

Documents how the codebase works today for a task's research questions and saves it as a research file (.ork/tasks/TASK/NN-research-SLUG.md) with file:line citations, so the plan builds on a reviewable record. Use before planning a change in unfamiliar code; describes, never proposes.

<span className="badge badge-blue">Command</span> <span className="badge badge-yellow">medium</span>

```bash title="Invoke"
/ork:create-research
```

<ContextualSkillSidebar slug="create-research" />

> **Create Research** Documents how the codebase works today for a task's research questions and saves it as a research file (.ork/tasks/TASK/NN-research-SLUG.md) with file:line citations, so the plan builds on a reviewable record. Use before planning a change in unfamiliar code; describes, never proposes.


# create-research

Answer the task's questions about the code as it is, and save the answer as one research file. It is
a map, not a proposal: no recommendations, no fixes, no critique. Layout: the create-plan skill's
`references/artifact-layout.md`.

## Steps

1. **Get the questions.** From the user, or from a questions file they name. Read any file they
   mention in full before anything else.
2. **Do not read the task's ticket or plans.** Research describes the code; a ticket that wants a
   change biases it. Earlier research artifacts in the task directory may be read.
3. **Split the questions into areas** and research them in parallel with `Explore` agents (two to
   six, grouped by area, not one per question). Ask each for `file:line` evidence.
4. **Check the agents' claims** that the document will rest on: open the cited lines yourself. An
   agent's summary is a claim, not evidence.
5. **Write the body** to a scratch file using
   [references/research-template.md](references/research-template.md), then create the artifact:

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" create \
     --task <task> --kind research --slug <slug> --title "<question>" --author <your seat> --body /tmp/research-body.md
   # prints .ork/tasks/<task>/NN-research-<slug>.md
   ```

6. **Reply with the path and the open questions**, and stop.

## Rules

- Describe, never prescribe: no "should", no "we could", no diff blocks.
- Every finding cites `path:line` or a line range.
- Say when a list is complete and when it is a sample.
- Open questions are about what was not traced ("how does X reach Y?"), not about what to build.

## Related

- `/ork:iterate-research` revises it from comments. `/ork:create-plan` reads it next.


---

## References (1)

### Research Template

# Research body template

Adapted from humanlayer's riptide `research_template.md` (Apache-2.0). This is the BODY only: the
front matter and comment block are written by `scripts/artifact.mjs`.

````markdown
# Research: <question or topic>

## Questions
1. <question as asked>

## Method
This document describes the code as it exists at the commit in the front matter. It makes no
recommendations.

## Summary
Two to four paragraphs: the main structures, how data moves, how the parts relate.

## Findings

### 1. <a claim about the code, stated as a fact>
What it is and how it works, with citations inline (`src/app.ts:57-80`). Use a table, a call tree or
a short type signature where it is faster than prose.

#### Tests
Where the tests for this are and how they work. Say so if there are none.

### 2. <next claim>
...

## Code references
### <area>
- `path/to/file.ts:28-36`: what is there
- `path/to/dir/`: what the directory holds (complete list, or key files only)

## Open questions
Things not fully traced. "None" if none.
````