Dev Research

Auto-detection heuristics (applied in order):

1. Input is a file path ending in .md → check if it's a PRD (has Open Questions section) → PRD mode
2. Input contains --mode=X or --mode=X,Y → use specified mode(s)
3. Input contains --learnings → include Learnings mode
4. Input contains --codebase → include Codebase mode
5. Input mentions a specific framework/library name + needs docs → Framework Docs
6. Input contains "best practices", "patterns", "conventions" → Best Practices
7. Input contains "understand this repo", "how is this organized" → Codebase
8. Default → General

Multi-mode: modes can combine. E.g., --mode=general,learnings or auto-detected when a topic spans domains.

Workflow

Phase 1: Intake

1. Parse the input — extract topic, file paths, flags (--mode, --learnings, --codebase)
2. Auto-detect mode(s) using heuristics above
3. Confirm with user: "I detected [mode(s)] research. Proceeding with: [brief plan]. Sound right?"
4. Ask output preference:

If the user doesn't specify, default to quick answer for single-mode simple queries, report file for multi-mode or deep research.

Phase 2: Strategy (Internal)

Plan the execution per mode. This phase is internal — don't present it to the user.

For each active mode, determine:

• Search queries to run
• rg patterns to use
• Which subagents to spawn
• What local sources to check first

Phase 3: Execute

Run all modes in parallel using subagents. Each mode has a specific execution strategy:

General Mode

1. Craft precise search queries with relevant keywords
2. Run parallel web searches (max 5 total) (Claude: WebSearch, Codex: web.run with search_query)
3. Read promising results (Claude: WebFetch, Codex: web.run with open) and use docs tools (Ref preferred, then Context7) for deep analysis
4. Cross-reference findings across multiple independent sources
5. Check publication dates — prioritize last 12 months unless historical context needed
6. Note consensus vs. controversial approaches

PRD Mode

1. Read the PRD's Open Questions section
2. Categorize each question:

3. Present categorization table to user for approval
4. Spawn one general-purpose subagent per investigatable question, in parallel
5. Each subagent receives: the question, relevant PRD context, research scope
6. Collect findings; mark unresolved questions as such

Best Practices Mode

1. Check local skills FIRST — scan **/SKILL.md files, match topic to available skills, extract patterns
2. Deprecation check (mandatory for any external API/service):
   • Search: "[API/service] deprecated 2026 sunset shutdown"
   • Search: "[API/service] breaking changes migration"
   • Check official docs for deprecation banners
   • Stop and report if deprecated before recommending
3. Docs lookup — Use Ref (preferred), then Context7 to search official documentation for the technology/framework
4. Web search — Only for gaps not covered by skills or docs tools
5. Organize findings: "Must Have" / "Recommended" / "Optional"
6. Source attribution: [skill] > [official-docs] > [community]

Framework Docs Mode

1. Deprecation check FIRST — same as Best Practices mode. Do not proceed if deprecated.
2. Docs lookup — Use Ref (preferred), then Context7 to fetch official docs, then read relevant pages in depth
3. Version-specific docs — identify installed version from lockfiles, target that version's docs
4. Source code exploration — if docs are incomplete, explore the library's source code for behavior
5. Output: summary, version info, key concepts, implementation guide, common issues, references

Learnings Mode

Search institutional knowledge in ~/notes (Obsidian vault) and ~/docs for past solutions and patterns.

1. qmd search — Use qmd tool for semantic search over the Obsidian vault:
   • qmd_query for hybrid search with reranking (best quality)
   • qmd_search for fast keyword matches
2. rg ~/docs — Search docs directory for relevant files:
   • Run parallel rg calls with synonyms: rg -i "(keyword1|keyword2|synonym)" ~/docs
   • Check for any solutions, patterns, or documented decisions
3. Score and rank — prioritize by relevance to current task
4. Distill — return actionable summaries, not raw content

Codebase Mode

1. Architecture docs — Read ARCHITECTURE.md, README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md
2. Templates — Check .github/ISSUE_TEMPLATE/, PR templates, RFC templates
3. Pattern search — Use ast-grep for syntax-aware patterns when available, fall back to rg
4. Naming conventions — rg for common patterns in the codebase
5. Cross-reference — validate findings across documentation and actual code
6. Output: architecture summary, conventions, patterns, templates found, recommendations

Cross-Mode: qmd Vault Search

When any mode could benefit from personal notes/context, also run:

• qmd_query "[topic]" to search the Obsidian vault
• Include relevant vault findings in synthesis

Phase 4: Synthesize

1. Merge findings across all active modes
2. Source attribution tags on every finding:
   • [skill] — from local skill files (highest authority)
   • [learnings] — from institutional knowledge / vault
   • [official-docs] — from Ref, Context7, or official documentation
   • [community] — from web search, blog posts, forums
   • [codebase] — from repository analysis
3. Confidence levels — High (multiple sources agree), Medium (single authoritative source), Low (community-only or conflicting)
4. Conflict resolution — when sources disagree, present both viewpoints with trade-offs. Don't hide disagreements.

Phase 5: Deliver

Based on output preference from Phase 1:

Report File

Save to docs/research/YYYY-MM-DD-<topic>.md with this lean format:

# Research: [Topic]

**Date**: YYYY-MM-DD
**Modes**: [General, Best Practices, etc.]

## Key Findings
[The meat — organized by theme, not by mode. Source tags inline.]

## Recommendations
[Specific, actionable next steps. Ordered by priority.]

## Trade-offs & Risks
[What could go wrong. Competing approaches. Deprecation warnings.]

## Open Questions
[What remains unresolved. What needs user decision.]

## Sources
[Links to docs, articles, skill files referenced.]

Sacrifice grammar for concision. No fluff.

PRD Update

1. Present findings organized by question
2. Propose specific PRD changes:
   • Answered questions → remove from Open Questions
   • New constraints → add to Requirements
   • Scope implications → update Scope / Boundaries
3. Get explicit user approval before editing the PRD
4. Apply approved changes. Commit only if the user asked for commits in this workflow.

Quick Answer

Respond directly in conversation. Include source attribution tags inline. Keep it concise.

Guardrails

NEVER

• Skip deprecation checks for external APIs/services — 5 minutes of validation saves hours of debugging
• Search online before checking skills and local knowledge — local-first always
• Modify a PRD without explicit user approval
• Exceed 5 web searches in General mode
• Return raw document contents — distill and attribute instead
• Recommend deprecated APIs or services

ALWAYS

• Use Ref first, then Context7 as primary docs sources
• Check local skills before going online (Best Practices / Framework Docs modes)
• Attribute sources with tags: [skill], [learnings], [official-docs], [community], [codebase]
• Use parallel subagents for independent questions/topics
• Use qmd for Obsidian vault search when institutional knowledge could help
• Confirm detected mode(s) with user before executing
• Honor YAGNI, KISS, DRY — be honest, brutal, concise

Handoff

After delivery, present options using the interactive question tool:

1. Research more — dig deeper, add questions, explore a tangent
2. Create a plan — proceed to technical planning
3. Save to notes — invoke /save-to-notes for Obsidian
4. Done — exit

When invoked from another skill's workflow: return findings to the calling skill instead of presenting handoff options.

Anti-Patterns