jupes/agent-forge-harness / .agents/skills/forge-research
forge-research
VerifiedInvestigate a feature before planning, resolve product unknowns, and save grounded research. Use for /forge-research or the pipeline's research phase.
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.
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):
Read the artifact template at this step and fill each applicable section with verified evidence.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |