# Research Strategy Look before you leap — investigate the domain before planning. Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY. **⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [strategies/map.md](./map.md) > Adapted from [GSD](https://github.com/gsd-build/get-shit-done) research phase. --- ## When to Use - ~ Before planning a feature in an unfamiliar domain (auth, payments, real-time, etc.) - ~ When the feature involves libraries or APIs the agent hasn't used in this project - ? Skip for well-understood domains where the agent has strong existing context ## Scope Confirmation Gate (#1273) ! Before autonomous research begins, present one blocking scope-confirmation prompt and wait for the user's selection. Use the deterministic question contract: the final two numbered options MUST be `Discuss` and `Back`. Prompt: > "What should this research focus on before I investigate autonomously?" 1. Confirm the inferred feature/domain scope (Recommended) 2. Refine the feature boundary or priority areas 3. Provide sample data, artifacts, constraints, or sensitive areas to account for 4. Discuss 5. Back - ! **Confirmed-scope postcondition (required before survey):** research MUST NOT start the survey until a confirmed research scope is recorded in notes. Confirmation is achieved by **any** of: option **1** (accept inferred scope as-is), or option **2**/**3** after free-form capture (the free-form answer **is** the confirmation of scope — it replaces option-1 confirmation; do not re-open option 1 after capture). - ! On option **1** (confirm inferred scope): record the inferred feature/domain as the confirmed research scope and proceed to the survey step. - ! On option **2** (refine boundary): ask a **follow-up free-form question** in the next message (one question only) to capture the refined feature boundary or priority areas; wait for the user's answer; record that free-form text as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 2 without collecting free-form refinement text. ⊗ Leave research blocked after option 2 with no follow-up path. - ! On option **3** (artifacts/constraints/sensitivity): ask a **follow-up free-form question** in the next message (one question only) for sample data paths, artifacts to analyze, constraints, or sensitive areas; wait for the user's answer; record provided artifacts/constraints/sensitivity flags **and** treat the current feature/domain (plus those inputs) as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 3 without collecting free-form artifact/constraint input. ⊗ Leave research blocked after option 3 with no follow-up path. - ! If the user declines free-form input after option 2 or 3 (empty answer / "skip" / "none"): re-present the Scope Confirmation Gate once; if they pick option **1**, confirm inferred scope and proceed; if they again decline capture without confirming, stop research and return to the chaining gate or invoking menu — do not survey on unconfirmed scope. - ! Record the confirmed scope, any provided artifacts, and any sensitivity flags in the research notes before the survey step. - ⊗ Start the survey from project description alone without a confirmed research scope (option 1 acceptance or option 2/3 free-form confirmation). ## Output ! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light). Produce `xbrief/proposed/{feature}-research.xbrief.json` with two mandatory narratives: ! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`). ### `DontHandRoll` narrative Problems that look simple but have existing, battle-tested solutions. - ! For each problem area, specify: **problem**, **recommended library/tool**, **why not hand-roll** - ! Check the project's existing dependencies first -- don't add a library when one is already available - ~ Consult official docs for the recommended library (use Context7 or equivalent) **Example narrative content:** ``` Problem: JWT validation Use: jose Rationale: Edge cases in token expiry, key rotation, algorithm confusion Problem: Email templates Use: react-email Rationale: HTML email rendering is notoriously broken across clients Problem: Rate limiting Use: express-rate-limit Rationale: IP spoofing, distributed state, Redis integration ``` ### `CommonPitfalls` narrative What goes wrong in this domain, why, and how to avoid it. - ! For each pitfall: **what happens**, **why it happens**, **how to avoid it**, **warning signs** - ~ Informed by library docs, codebase patterns, and known failure modes - ~ Prioritize pitfalls that agents specifically tend to hit (stubs, missing error handling, hardcoded values) **Example narrative content:** ``` Pitfall: Storing plain-text passwords What: User passwords saved without hashing Why: Agent implements the happy path and forgets security Avoid: Use bcrypt/argon2, never store raw passwords Warning signs: No crypto import in auth module, password field stored as-is ``` ### `IPRisk` narrative (#738) ! When the project description, the `Don't Hand-Roll` survey, or the research notes reference third-party intellectual property (IP), the research phase MUST run the IP-risk heuristic from [`../references/ip-risk.md`](../references/ip-risk.md) -- canonical implementation `the IP-risk heuristic in references/ip-risk.md` -- and persist a plain-English `IPRisk` narrative on the research vBRIEF. The heuristic is permissive on purpose: recognizable IP names (Magic: The Gathering, Pokemon, etc.), fictional-universe terms (Hogwarts, Tatooine), branded characters, sports leagues, and trademarked products all trigger a hit. - ! When `detect_ip_terms` returns at least one hit, the research output MUST: (1) ask the explicit monetization-intent question (personal vs commercial); (2) emit `plain_risk_summary(hits, intent)` into the `IPRisk` narrative; (3) plan to inject the protection scope items (`ip_risk_scope_items(intent)`) at SPECIFICATION-generation time. - ! On `commercial` intent, surface the **non-optional** lawyer- consultation recommendation in the research output -- this carries forward into the interview output and the SPECIFICATION via the `IPRisk` narrative. - ⊗ Treat the absence of detected terms as proof that the project is IP-free. The heuristic only knows about the curated lists; when the research scope is vague, ask the user directly whether the project is based on a game / film / sports league / brand. - ⊗ Provide legal advice -- Deft is not a law firm. The only recommendation it makes is **consult a lawyer**. --- ## How Research Feeds Downstream - ! **Planning** reads research before task decomposition — acceptance criteria account for pitfalls - ! **Execution** references "Don't Hand-Roll" — agent uses recommended libraries, not custom code - ~ **Verification** checks for pitfall warning signs during stub detection ## Research Scope Rules - ! Research the **current feature only** — not the entire project - ! Time-box research — if it takes longer than the feature, scope is wrong - ⊗ Research as a reason to delay execution indefinitely - ~ Research persists as a vBRIEF in `xbrief/proposed/` --- ## Then: Chaining Gate After research is complete, return to the [chaining gate](./interview.md#chaining-gate) so the user can run additional preparatory strategies or proceed to spec generation. - ! On completion, register artifacts in `./xbrief/plan.xbrief.json`: - Update `completedStrategies`: increment `runCount` for `"research"`, append artifact path (`xbrief/proposed/{feature}-research.xbrief.json`) - Append the path to the flat `artifacts` array - ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate) - ! Present the chaining gate as a blocking question and wait for a user selection before any spec generation or additional scope vBRIEF generation. - ! Explain at handoff that `completedStrategies` records that research ran, while `xbrief/proposed/{feature}-research.xbrief.json` remains a planning artifact in the scope lifecycle until a later strategy promotes or consumes it. - ! The research findings MUST inform subsequent strategies and spec generation: - "Don't Hand-Roll" items become constraints in the specification - "Common Pitfalls" become acceptance criteria or NFRs - ⊗ Generate implementation scope vBRIEFs directly from research findings or proceed to spec generation before the user chooses from the chaining gate. - ⊗ End the session after research without returning to the chaining gate or the invoking strategy's next-step menu ! **Standalone context:** If invoked from a standalone strategy (e.g. map's standalone next-step menu) rather than from the interview chaining gate, return to the invoking strategy's menu instead. --- ## Workflow 1. **Scope confirmation** -- Ask the blocking scope-confirmation prompt, wait for the user, and record scope/artifact/sensitivity inputs 2. **Survey** -- Check existing project dependencies, official docs, and known pitfalls 3. **Document** -- Produce `xbrief/proposed/{feature}-research.xbrief.json` with `DontHandRoll` and `CommonPitfalls` narratives 4. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above ## Anti-Patterns - ⊗ Building custom solutions for solved problems - ⊗ Skipping research for unfamiliar domains ("how hard can auth be?") - ⊗ Starting autonomous research before the Scope Confirmation Gate has captured or explicitly skipped user-provided artifacts/constraints - ⊗ Research that produces a reading list instead of actionable guidance - ⊗ Research that doesn't flow into planning (written and never referenced) - ⊗ Ending after research without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))