Research

flow:research — Pre-plan investigation

Research exists to make the plan better. The output is not for shipping; it is a working document that the plan skill consumes. Optimize for useful pointers, decision-relevant facts, and explicit options, not for thoroughness.

When to run

• Task size is L (always)
• Task size is M and any of:
  • The user is unsure how the existing code is structured
  • The change depends on a library/API behavior the user has not verified
  • There is an existing similar pattern elsewhere in the repo or org that should be matched
• Task size is S — usually skip. The plan can be drafted directly from the file under change.

If you are not sure whether to research: time-box it. Spend 5–10 minutes scanning the most-likely-relevant files, then write a short research.md and move on. Fast iteration means gaps surface during implementation and result review — don't over-research up front.

What to produce

<worktree>/.flow/tasks/<date>-<task>/research.md, with the standard frontmatter (full schema in ../../references/frontmatter.md):

---
title: "Research — <task>"
type: research
task: <kebab task name>
task_date: <YYYY-MM-DD>
created: <today>
last_updated: <today>
status: active           # this doc rarely changes status
size: <S|M|L>
parent: ./prepare.md
related:
  - ./plan.md (will consume these findings)
time_box: 10m            # 5m | 10m | 20m | 60m
used_external_llm: false # set true if an external agent produced raw output under artifacts/
---

# Research — <task>

## Problem framing
- User goal in one sentence, in the user's words when possible.
- Who is affected by this change (end user, operator, maintainer, downstream agent).
- Success criteria: what must be true for the task to be done — measurable, not "works better".
- Constraints and non-goals already known.
- **Goal-lock flags:** call out any part of the goal that is still ambiguous, and any
  schema/contract/interface decision the task hinges on. These are what `flow:plan` must
  resolve with the user (AskUser) before drafting — surface them here so they aren't missed.

## Premises to validate
- List the assumptions the plan would rely on. Each line should say whether it is
  verified, likely, or still unknown.
- Challenge vague framing: if the task says "make it better", "simplify",
  "support X", or "improve UX", define the measurable version.

## Decision-relevant findings
- Crisp bullets. Each line should change at least one decision the planner will make.

## Existing code
- file:line references to where related logic lives
- Existing code, flows, docs, or past PRs that partially solve the problem
- Patterns to follow / patterns to avoid (call out anti-patterns explicitly)
- Anything the plan must reuse rather than rebuild, or a concrete reason not to
- Test coverage gaps in the area being touched

## External references
- Library API documentation (link + relevant version)
- Internal docs / past PRs / past issues
- Output from other-LLM research if used (saved separately, summarized here)

## Candidate approaches
- 2-3 viable shapes when the task is non-trivial. For each: summary, effort,
  risk, reversibility, blast radius, and existing code reused.
- Include a minimal viable approach and an ideal/local-architecture approach when
  they differ. Add a creative/lateral approach only when it is meaningfully
  different, not just bigger.
- Do not pick the final answer here unless the evidence clearly eliminates every
  alternative. The plan makes the decision.

## Open questions
- Things that need user input before planning can proceed.

Keep this document under ~300 lines. If you find yourself writing more, you are probably over-researching — surface the key facts and let the plan or actual implementation pull in the rest.

How to research

Delegate to cost-efficient subagents, fanned out in parallel — not the frontier orchestrator model. Spawn one subagent per relevant area (codebase, GitHub Issues/PRs, commit history, web) and have each return a tight digest; the orchestrator reads digests and decides. Pick the cheap model tier by harness (Claude Code → Sonnet, Antigravity → Gemini Flash, Codex → Codex 5.6 Terra) per ../../references/models.md. In Claude Code, delegate to the bundled flow:researcher agent (Sonnet) — fan out one per area. Skip any area that is obviously irrelevant — research serves the plan, it is not a checklist to complete.

Codebase exploration

Use grep / find / Glob to locate related code. For broader exploration where you do not know the right keyword, spawn an Explore subagent — it scans without filling the orchestrator's context with raw file contents.

When exploring, explicitly look for leverage before inventing structure:

• Existing flows that already produce the desired data or behavior.
• Shared helpers, adapters, tests, or docs that should be extended.
• Nearby anti-patterns the plan should avoid copying.
• Deferred TODOs or prior plans that overlap with the task.

Web research (optional, fast path)

When the task involves a less-familiar library or API, do web research in-harness via the flow:researcher subagent (WebFetch / WebSearch) — do not shell out to an external CLI.

If the task is about a library, framework, SDK, API, CLI tool, or cloud service, follow the current project's documented source-of-truth lookup first (for example, ctx7 where configured) before relying on general web search or model memory.

Point the subagent at a specific question — e.g. the current shape of the <topic> API in <library@version>: auth flow, required scopes, callback behavior, error responses, and breaking changes in the last 12 months, with source URLs cited. It returns a tight digest; distill the load-bearing facts into research.md under External references and keep the rest out of your active context.

Past project memory

If the user mentions "we did this before" or similar, check claude-mem search for prior sessions before retracing the same path.

Approach framing

Before finishing research.md, write candidate approaches when the choice is not obvious. Use this shape:

## Candidate approaches
- **Minimal viable** — smallest change that satisfies the success criteria.
  Effort: S/M/L. Risk: low/medium/high. Reuses: <existing code/docs>.
- **Local architecture fit** — approach that best matches current project
  structure, even if it touches a little more code.
  Effort: S/M/L. Risk: low/medium/high. Reuses: <existing code/docs>.
- **Ideal / lateral** — include only when it changes the framing or long-term
  trajectory in a meaningful way.
  Effort: S/M/L. Risk: low/medium/high. Reuses: <existing code/docs>.

What NOT to do

• Don't research the obvious. Linking to the React docs for useState is noise.
• Don't paste long code blocks. Use file:line references instead — they stay current as the code evolves.
• Don't decide the implementation here. Research surfaces options and constraints. The plan picks among them. Mixing the two means the plan has nowhere to add value.
• Don't research what the user has already told you. If they said "we use Firebase Auth", don't go verify that.
• Don't skip problem framing. If the problem statement is fuzzy, the plan will encode fuzzy assumptions. Tighten the framing before drafting options.

Reference

• Directory layout: ../../references/directory-structure.md
• Frontmatter schema: ../../references/frontmatter.md
• Calling other LLMs: ../../references/multi-llm.md
• Doc style (prefer lists over tables): ../../references/doc-style.md