research

name	research
description	Explore, investigate, or reason through something you do not know the answer to yet — open-ended investigation where the destination is not clear. Unlike /autonomous (known goal, TDD), this is for unknowns. Use when the user says 'explore X', 'what do I need to know about Y', 'investigate why Z', 'research the best approach to W'. Runs Ouros REPL sessions for token-efficient exploration. NOT for iterative hypothesis loops (use /autonomous-research) or people/company lookups (use /people-research or /company-research).
user-invocable	true

Step 0 — Resolve storage roots

Two roots, both walked-up from CWD:

state_root (for continuum/autonomous/, continuum/research/, thoughts/shared/plans/, thoughts/shared/research/ — project work artifacts):

1. If CWD is inside <workspace.root>/<workspace.projects>/<slug>/ → state_root = <workspace.root>/<workspace.projects>/<slug>/
2. If CWD is inside <workspace.root>/<workspace.coding>/<name>/ → state_root = <workspace.root>/<workspace.coding>/<name>/
3. If CWD has a CLAUDE.md or .git/ but no parent workspace match → state_root = <repo_root> (standalone repo / original CCv4 mode)
4. None of the above → AskUserQuestion: "No project context detected. Which project should this run in?" Never silently fall back.

handoff_root (for handoffs/, library/ — session metadata):

• If <workspace.resources> is defined in CLAUDE.md Configuration AND <workspace.root>/ exists as a directory on disk → handoff_root = <workspace.root>/<workspace.resources>/ (multi-project / workspace mode — handoffs pool workspace-wide)
• Else → handoff_root = <state_root>/thoughts/shared/ (single-project mode — original CCv4 behavior, no workspace)
• If <handoff_root>/ subfolder doesn't exist yet → create on first write (mkdir -p semantic).

Use <state_root>/continuum/... and <handoff_root>/handoffs/{session-name}/... in place of any relative paths in the rest of this skill.

---

Use when you need to explore, reason through an idea, or research something you don't already know the answer to. Unlike /autonomous (which drives toward known goals), /research is for open-ended investigation where the destination isn't clear yet.

Ouros is a sandboxed Python REPL that persists variables across executions, supports fork/save/resume, and bridges to external functions (exa search, nia docs, llm_call, agent_call). Context lives in the REPL heap — not in your conversation window — so you can reason over large amounts of data without burning tokens.

Harness location: .claude/tools/ouros_harness.py

Core commands:

# Execute research code in a named session
python .claude/tools/ouros_harness.py --file /tmp/research.py \
  --session {topic} --storage <state_root>/continuum/research

# Resume a previous session (loads saved state, then runs new code)
python .claude/tools/ouros_harness.py --file /tmp/next-step.py \
  --session {topic} --storage <state_root>/continuum/research --load

# Fork a session for parallel exploration
python .claude/tools/ouros_harness.py --session {topic} \
  --storage <state_root>/continuum/research --fork {topic}-branch-a

# Inspect session state
python .claude/tools/ouros_harness.py --session {topic} \
  --storage <state_root>/continuum/research --list-vars

# Extract a variable as JSON
python .claude/tools/ouros_harness.py --session {topic} \
  --storage <state_root>/continuum/research --get-var findings

Available functions inside the REPL:

Research: exa_search(query, num_results, with_text, domains, start_date), nia_search(query, repositories, data_sources), nia_universal(query, limit), nia_web(query), nia_package(package, query, registry), nia_package_grep(package, pattern, registry), research_package(package, version, registry), nia_help().

RLM recursive calls: llm_call(prompt, model, backend, max_tokens, system, temperature) — stateless LM sub-query. agent_call(prompt, agent, model, max_turns, timeout, cwd, isolated) — headless agent with full tool access.

Filesystem: read_file(path), write_file(path, content), glob_files(pattern, path), run_command(cmd, timeout).

How to use this skill:

Write a Python program that decomposes the research question, calls external functions, stores intermediate results as variables, and produces a telegraphic artifact as final output. The program runs inside Ouros — all variables persist in the session and can be inspected, forked, or resumed later.

The key RLM property: sub-agents (via agent_call) and LM queries (via llm_call) are functions called from within the REPL. Results flow back into the program as return values, not as context injected into your conversation. This means you can orchestrate multiple agents, aggregate their outputs, reason over the combined data — all without any of it touching your token budget.

Example research program:

# Research: What auth patterns does this codebase use?

# 1. Gather data from multiple sources
codebase_auth = agent_call(
    "Search this codebase for authentication patterns. "
    "List every auth-related file with a one-line summary. "
    "Include: middleware, token validation, session handling, OAuth.",
    agent="claude-code", model="sonnet", max_turns=5
)

best_practices = exa_search(
    "modern authentication patterns 2026 JWT OAuth session",
    num_results=5, with_text=True
)

docs = nia_search("authentication middleware best practices")

# 2. All results are now REPL variables — no tokens spent in conversation

# 3. Synthesize via LLM sub-call (only sees relevant slices)
synthesis = llm_call(
    f"Given these codebase auth patterns:\n{codebase_auth}\n\n"
    f"And these best practices:\n{docs.get('answer', '')}\n\n"
    "Write a telegraphic assessment: what's good, what's missing, "
    "what should change. Be specific with file:line references.",
    model="claude-sonnet-4-6", backend="anthropic", max_tokens=2000
)

# 4. Store as artifact
findings = {
    "question": "What auth patterns does this codebase use?",
    "synthesis": synthesis,
    "sources": {
        "codebase": codebase_auth[:500],
        "exa_results": len(best_practices.get("results", [])),
        "nia_answer": docs.get("answer", "")[:300],
    },
}

# 5. Write telegraphic artifact for /autonomous or handoff consumption
write_file("<state_root>/continuum/research/auth-patterns/findings.md", f"""# Auth Patterns Research

{synthesis}

## Sources
- Codebase scan: {len(codebase_auth)} chars of analysis
- Exa: {len(best_practices.get('results', []))} results
- Nia docs: indexed answer available
""")

print(synthesis)

Output convention: Every research session should produce a telegraphic artifact at <state_root>/continuum/research/{topic}/findings.md. This is what /autonomous reads as input context, what handoffs reference, and what the user sees. The full REPL state (all variables, raw API responses, intermediate reasoning) persists in the session and can be resumed or forked — but only the artifact crosses back into the conversation.

Storage layout:

<state_root>/continuum/research/
  {topic}/
    findings.md          ← telegraphic artifact (what others consume)
    session state         ← serialized REPL (auto-saved by ouros)

When to fork: Fork when you want to explore two hypotheses in parallel without them contaminating each other's variable space. Each fork gets an independent copy of all accumulated state.

When to resume: Resume when you got initial results and want to go deeper on one thread, or when a previous research session produced partial findings you want to extend.

Relationship to other skills: /research explores and produces artifacts. /autonomous consumes those artifacts as milestone inputs. /create-handoff references them for context transfer. They compose but don't overlap — research finds the path, autonomous walks it.