forge-research

Phase 1 of 4 in the Forge pipeline (research → plan → implement → ship). The goal is a plans/research/<slug>.md document grounded in real code, with every open question that the codebase cannot answer resolved by the user.

Hard rule: never ask the user something the code, knowledge files, or git history can answer. Explore first, ask last. See [[grill-me]] for the interview discipline this phase reuses.

When to Use

• The user runs /forge-research <feature> or /forgemaster enters its research phase.
• A feature is described but the implementation surface, constraints, or decisions are unclear.
• The next useful step is reducing ambiguity, not coding or planning yet.

Inputs

• Free-text feature description, a bd show <id> task, or a spec file path.
• Optional <slug> (kebab-case). If absent, derive one from the feature title and reuse it for every downstream phase artifact.
• Optional --smith <name>: the configured smith the run is recorded as built by. Add it to the forge:phase-gate call in step 6; the phase gate refuses a name that is not configured. It does not change the model of the session doing the work (.claude/workflows/forge.md, --smith).

Process

1. Establish the target

State the feature in one or two sentences. If it is already clear from context, do not ask the user to restate it. Pick the <slug> now and announce it — all later phases key off it.

2. Explore what code can answer (mandatory, before any question)

Load knowledge first, then read real code. Be exhaustive enough to write accurate file paths.

cat knowledge/_shared.yaml
cat knowledge/repos/<repo>.yaml 2>/dev/null || echo "no knowledge file for <repo>"   # for each affected repo
bd show <id> 2>/dev/null               # if a task id was given

A repo has a knowledge/repos/<repo>.yaml only after /add-repo or /sync-knowledge has been run for it; the directory is empty in a fresh checkout, and the harness itself has none. When there is no file, do not generate one here: read the repo's README, its manifest (package.json or the like) and its AGENTS.md/CLAUDE.md if it has them, say in the research document that no knowledge file existed, and carry on with the code read below.

Then use Glob/Grep/Read (read-only) to map:

• Entry points and the data flow into the affected area.
• Existing code to reuse (hooks, types, components, utilities) — search before assuming new.
• Integration points: what this feature depends on, and what depends on it.
• Existing tests and how this area is currently verified.

Record each discovered fact. If exploration answers a question you were about to ask, write the answer down instead of asking it.

3. Separate the unknowns

Sort every open item into two buckets:

• Answerable by code/docs → resolve it yourself now; cite the file/line.
• Not answerable by code → product intent, scope boundaries, UX choices, external systems, priorities, acceptance thresholds. These become user questions.

4. Grill the user — one question at a time

For each unanswerable item, ask exactly one question per turn, hardest-blocking branch first. Every question carries a recommended answer and a one-line reason (the [[grill-me]] format):

Shared understanding so far:
- Confirmed (from code): <fact + file:line>
- Open: <the gap this question closes>

Question:
<one question>

Recommended answer:
<your recommendation>

Why:
<brief rationale + consequence>

Explain before you ask. If the decision rests on a mechanism the user may not have in their head — a tradeoff, how a tool behaves, or why the code forces the choice — open with one or two plain-language sentences that explain what's going on and why it matters, then give the options. A question the user can't parse wastes the turn (and the tokens). Lead with the "why", not the menu. If the user says they don't understand, stop and explain the mechanism in plain terms before re-asking.

Prefer AskUserQuestion when the choice is a small closed set. Stop asking when the remaining uncertainty is explicitly accepted or the user says to proceed.

5. Write the research document

Write to plans/research/<slug>.md (create the folder if needed):

# Research: <slug> — <feature title>
Generated: <date>
Repo: <repo>
Phase: research (1/4)

## Goal
<what the user wants and why, 2–3 sentences>

## What the Code Says (answered by exploration)
- <fact> — `path/to/file.ts:NN`
- Existing code to reuse: `...` — <how it helps>
- Integration points: <upstream / downstream>
- Current test coverage of this area: <summary>

## Decisions Resolved with the User
| Question | Decision | Rationale |
|----------|----------|-----------|
| <q> | <answer> | <why> |

## Constraints & Non-Goals
- Constraint: <...>
- Non-goal: <explicitly out of scope>

## Open Risks / Assumptions Carried Forward
- <risk or accepted assumption>

## Recommended Scope for Planning
<one paragraph: the shape of the feature the plan phase should design>

6. Hand off

Update the forge state and report:

bun run forge:phase-gate research --slug <slug> --write --bead <task-id>

<task-id> is the issue this run was started from, when that is a task, a bug or a chore: it ties the run's ledger events, and later its quality gate, to that issue. Omit --bead when the run was started from free text, a feature or an epic: no task exists until the plan phase creates one, and a feature or an epic is named only by the ship write (pass it as --epic <id> here: that groups the run and is never used for its correlation). See .claude/workflows/forge.md, Which bead a phase names.

Then tell the user: research is complete at plans/research/<slug>.md, and the next phase is /forge-plan <slug> (or /forgemaster will offer to continue). Do not start planning in this phase — planning is [[forge-plan]].

Exit Criteria

• plans/research/<slug>.md exists with all sections filled.
• Every "Decisions Resolved" row came from the user, not guessed.
• No question was asked that the code already answered.
• Forge state advanced to research complete.