research

Forge: Research

Overview

Gather external context to inform brainstorming and planning decisions. This skill uses web search, documentation fetchers, and GitHub repo search to find relevant information about libraries, patterns, APIs, and best practices.

This skill is always optional. It's offered as a choice during brainstorming and planning, or invoked standalone via forge research.

Session

Session Resolution

1. From $ARGUMENTS: If the first token is a number or short identifier, use it as the session ID.
2. Auto-detect existing sessions:

   ls .forge/sessions/ 2>/dev/null | sort
   

   • 0 sessions → create a new session (ID: 1), then mkdir -p .forge/sessions/1/
   • 1 session → use it automatically; print "Using session <id>"
   • 2+ sessions → list them, AskQuestion "Which session?"
3. When called from brainstorming/planning: the calling skill passes the session ID — use it directly without re-resolving.

SESSION_DIR = .forge/sessions/<id>/ — all file paths in this skill are relative to this directory.

Tools Available

Tool	Use Case
WebSearch	General queries — best practices, comparisons, "how to X in Y"
WebFetch	Read specific pages — docs, blog posts, GitHub issues, Stack Overflow
mcp__plugin_context7_context7__resolve-library-id → query-docs	Library documentation — API reference, usage examples, configuration
mcp__zread__search_doc	GitHub repo docs, issues, and commits

Process

1. Identify Research Questions

From the user's input (or from brainstorm/plan context), extract specific questions:

• What library/API are we working with? → Context7
• Are there established patterns for this? → WebSearch
• How does a specific API work? → WebFetch on docs
• What are common pitfalls? → WebSearch + GitHub issues
• How have others solved this? → WebSearch + GitHub repos

If the user's request is vague, ask using AskQuestion:

• "Was genau soll ich recherchieren?" with options like:
  • Library docs (API, config, examples)
  • Best practices / patterns
  • Alternatives / comparisons
  • Known issues / pitfalls

2. Execute Research

Run research queries in parallel where possible (multiple WebSearch calls, Context7 + WebSearch simultaneously).

Library docs flow:

1. resolve-library-id with the library name
2. query-docs with the specific topic/question
3. Extract relevant code examples and API details

General research flow:

1. WebSearch with targeted query
2. Pick 2-3 most relevant results
3. WebFetch on the best results for deeper content
4. Extract key takeaways (don't copy content verbatim)

GitHub repo flow:

1. search_doc on the relevant repo with the question
2. Check issues for known problems
3. Check docs for official guidance

3. Synthesize Findings

Combine results into a structured summary. Focus on:

• Actionable insights — not just facts, but what they mean for our approach
• Code patterns — relevant examples that inform implementation
• Gotchas — things that commonly go wrong
• Version-specific info — note which version docs apply to

4. Write Research Document

Save to $SESSION_DIR/research.md:

# Research: <topic>

## Questions Investigated
- <question 1>
- <question 2>

## Findings

### <Finding title>
- **Source**: <url or "Context7: library-name">
- **Relevance**: <why this matters for our task>
- **Key takeaway**: <1-3 sentences>
- **Code example** (if applicable):
  ```typescript
  // relevant snippet

• Source:
• Relevance:
• Key takeaway: <1-3 sentences>

Gotchas / Pitfalls

Recommendations

Create `$SESSION_DIR` if it doesn't exist. If `$SESSION_DIR/research.md` already exists, ask whether to overwrite or append.

### 5. Report Back

Summarize findings concisely to the user. If called inline from brainstorming/planning, return focus to that skill's flow.

## Rules

- **Max 5 WebSearch queries** per research session — be targeted, not exhaustive
- **Max 3 WebFetch calls** — pick the most relevant sources
- **Don't copy content verbatim** — summarize in your own words, reference sources
- **Prefer official docs** over blog posts over Stack Overflow
- **Note freshness** — flag if docs might be outdated (check dates)
- **Stay focused** — research the specific questions, don't go down rabbit holes