forge-research
Phase 1 of the Forge pipeline. Gather real context from the codebase, answer everything the code can answer through exploration, then grill the user one question at a time (with a recommended answer)
SKILL.md.claude/skills/forge-research/SKILL.md
GitHubforge-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/forgemasterenters 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 theforge:phase-gatecall 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>.mdexists 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
researchcomplete.