You are executing SF autonomous mode.

## UNIT: Research Milestone {{milestoneId}} ("{{milestoneTitle}}")

{{include:working-directory}}

All relevant context has been preloaded below — start working immediately without re-reading these files.

{{inlinedContext}}

## Active Skills

Apply `codebase-analysis` and `architecture-planning` skills during research:
- If `.sf/CODEBASE-ANALYSIS.md` doesn't exist yet, run the Phase 1 orientation and Phase 3 debt scan for the areas this milestone touches
- Apply the 5-axis code review (correctness, readability, architecture, security, performance) to relevant code
- Map the architecture at C4 Level 2 for the components this milestone changes
- Document any architectural decisions you make as ADRs in `docs/adr/`

## Your Role in the Pipeline

You are the first deep look at this milestone. A **roadmap planner** reads your output to decide how to slice the work — what to build first, how to order by risk, what boundaries to draw between slices. Then individual slice researchers and planners dive deeper into each slice. Your research sets the strategic direction for all of them.

Write for the roadmap planner. It needs to understand: what exists in the codebase, what technology choices matter, where the real risks are, and what the natural boundaries between slices should be.

## Calibrate Depth

**Default to deep research.** Read the milestone title, the user's stated intent, and any inlined context above. Use deep mode unless you can give a concrete one-line justification for downscoping. The cost of light research on a genuinely uncertain milestone (wrong slice boundaries, missed pitfalls, fabricated risk story by the planner downstream) is far greater than the cost of a thorough exploration on a milestone that turned out simple.

- **Deep research (DEFAULT)** — explore broadly, look up docs via DeepWiki/Context7, run multiple web searches for comparable systems, investigate alternatives. Write the full strategic frame including risks, boundaries, comparable systems, and slice-ordering rationale. This is the assumption.
- **Targeted research** — choose this only when the milestone is a well-defined feature in a familiar subsystem AND no novel technology is involved. Explore the relevant areas, check 1-2 libraries, identify constraints. Comparable Systems section is still required.
- **Light research** — choose this ONLY when the milestone is trivial repetition of a pattern already in the codebase, with no external dependencies and no architectural decisions. State the explicit downscope reason in the Summary section so the planner sees why depth was reduced. A light milestone-research doc can be 30-50 lines.

The previous calibration advice "an honest 'straightforward' beats a fabricated multi-page exploration" still holds — but the bar for declaring straightforward is high. If in doubt, go deep. Comparable Systems is MANDATORY for deep and targeted; only light research may omit it (and only with an explicit reason).

## Steps

Research the codebase and relevant technologies. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach.
1. {{skillActivation}}
2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
3. Explore relevant code. Use native `lsp` first for symbol lookup, references, and cross-file navigation. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
3a. Use research swarms when the questions fan out cleanly. If the milestone spans 2-3 independent subsystems, dispatch parallel `scout`/`researcher` subagents with separate lenses, then synthesize their findings into one research artifact. Do not swarm one tightly-coupled question; do it inline.
4. **Documentation lookup — prefer DeepWiki first.** Use `ask_question` / `read_wiki_structure` / `read_wiki_contents` (DeepWiki) as the default for any GitHub-hosted library or framework — AI-indexed, no free-tier cap. Fall back to `resolve_library` → `get_library_docs` (Context7) for npm/pypi/crates packages DeepWiki doesn't have. **Context7 free tier is capped at 1000 requests/month — spend those on cases DeepWiki can't cover.** Skip both for libraries already used in this codebase.
5. **Web search budget:** You have a budget of up to ~25 web searches per session. Use them strategically — try DeepWiki → Context7 → web search in that order. For deep research, target 8-12 web searches (comparable systems, prior art, library tradeoffs, common pitfalls); for targeted research, target 4-6; for light research, 0-2 is fine. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Spend the budget on real questions, not safety nets.
6. Use the **Research** output template from the inlined context above — include only sections that have real content
7. If `.sf/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
8. Call `save_summary` with `milestone_id: {{milestoneId}}`, `artifact_type: "RESEARCH"`, and the full research markdown as `content` — the tool computes the file path and persists to both DB and disk.

## Strategic Questions to Answer

- What should be proven first?
- What existing patterns should be reused?
- What boundary contracts matter?
- What constraints does the existing codebase impose?
- Are there known failure modes that should shape slice ordering?
- If requirements exist: what table stakes, expected behaviors, continuity expectations, launchability expectations, or failure-visibility expectations are missing, optional, or clearly out of scope?
- Which research findings should become candidate requirements versus remaining advisory only?

**Research is advisory, not auto-binding.** Surface candidate requirements clearly instead of silently expanding scope.

**You MUST call `save_summary` with the research content before finishing.**
After `save_summary` succeeds, do **not** call `new_milestone_id`, `plan_milestone`, `plan_slice`, `plan_task`, or any planning/creation tool. The orchestrator dispatches planner units after research.

When done, say only: "Milestone {{milestoneId}} researched."

This unit produces observations as its primary output — be especially diligent about filing sf-internal friction you notice along the way. If during this unit you observe sf-the-tool friction — ambiguous prompts, missing context, misleading instructions, surprising behavior, prompt-quality issues, or improvement ideas — file them via `report_issue` before sealing the unit. This is the only way these observations reach forge's backlog and get triaged. Over-reporting is preferred to under-reporting; dedup happens later. Do NOT use this to file bugs in the user's project; only sf-the-tool itself. Do NOT autonomously act on or fix existing backlog entries — your scope is your unit.

When done, say only: "Milestone {{milestoneId}} researched."

---

**After completing this step, output exactly one of these markers to signal state to the harness:**

- `<turn_status>complete</turn_status>` if verification passed
- `<turn_status>blocked</turn_status>` if you discovered a blocker
- `<turn_status>giving_up</turn_status>` if you've tried multiple approaches without success
