Best Practices Researcher

Research industry standards and create project documentation in one workflow.

Purpose & Scope

• Research via MCP Ref + Context7 for standards, patterns, versions
• Create 4 types of documents from research results:
  • Guide: Pattern documentation (Do/Don't/When table)
  • Manual: API reference (methods/params/doc links)
  • ADR: Architecture Decision Record (Q&A dialog)
  • Research: Investigation document answering specific question
• Return document path for linking in Stories/Tasks

Phase 0: Stack Detection

Objective: Identify project stack to filter research queries and adapt output.

Detection:

*.csproj

*.sln

package.json

tsconfig.json

requirements.txt

pyproject.toml

go.mod

Cargo.toml

build.gradle

pom.xml

Usage:

• Add

  query_prefix

  to all MCP search queries
• Link to stack-appropriate official docs

When to Use

• ln-310-story-validator detects missing documentation
• Need to document a pattern, library, or decision
• Replaces: ln-321-guide-creator, ln-322-adr-creator, ln-323-manual-creator

Input Parameters

Research Tools

ref_search_documentation

"[topic] RFC standard best practices 2025"

context7__resolve-library-id

libraryName="[topic]"

context7__query-docs

topic="[stack_prefix] [topic]"

WebSearch

"[topic] latest 2025"

"[topic] vs alternatives"

Time-box: 5-10 minutes for research; skip if topic is trivial

Research Methodology by Type (for doc_type="research")

Workflow by doc_type

ref_search

guides/NN-[slug].md

context7__query-docs

manuals/[pkg]-[ver].md

adrs/adr-NNN-[slug].md

research/rsh-NNN-[slug].md

Common Workflow: Detect number (if needed) → Research → Generate from template → Validate (SCOPE, POSIX) → Save → Return path

Extract & Sections by doc_type:

• guide: Extract principle, 2-3 do/don'ts, sources → Sections: Principle, Our Implementation, Patterns table, Sources, Related
• manual: Extract methods, params (type/required/default), returns → Sections: Package info, Overview, Methods table, Config table, Limitations
• adr: Dialog answers → Sections: Context, Decision, Rationale, Alternatives table, Consequences, Related
• research: Findings by methodology → Sections: Question, Context, Methodology, Findings (tables!), Conclusions, Next Steps, Sources

Validation specifics: guide: patterns table present; manual: version in filename; adr: ISO date, status field; all: sources ≥2025

ADR Dialog (5 questions): Q1: Title? → Q2: Category (Strategic/Technical)? → Q3: Context? → Q4: Decision + Rationale? → Q5: Alternatives (2 with pros/cons)?

Output: File path for linking in Stories/Tasks; for ADR remind to reference in architecture.md; for Research suggest ADR if decision needed

Critical Rules

NO_CODE_EXAMPLES (ALL document types):

Format Priority (STRICT):

┌───────────────────────────────────────────────┐
│ 1. TABLES + ASCII diagrams  ←── PRIORITY      │
│    Params, Config, Alternatives, Flows        │
├───────────────────────────────────────────────┤
│ 2. LISTS (enumerations only)                  │
│    Enumeration items, file lists, tools       │
├───────────────────────────────────────────────┤
│ 3. TEXT (last resort)                         │
│    Only if cannot express as table            │
└───────────────────────────────────────────────┘

A → B → C

Other Rules:

• Research ONCE per invocation; reuse results
• Cite sources with versions/dates (>=2025)
• One pattern per guide; one decision per ADR; one package per manual
• Preserve language (EN/RU) from story_context
• Link to stack-appropriate docs (Microsoft for .NET, MDN for JS, etc.)
• Do not create if target directory missing (warn instead)

Definition of Done

• Research completed (standards/patterns/versions extracted) - for guide/manual
• Dialog completed (5 questions answered) - for ADR
• Document generated with all required sections; no placeholders
• Standards validated (SCOPE, maintenance, POSIX)
• File saved to correct directory with proper naming
• Path returned; README updated if placeholder present

Reference Files

• Guide template:

  shared/templates/guide_template.md

• Manual template:

  shared/templates/manual_template.md

• ADR template:

  shared/templates/adr_template.md

• Research template:

  shared/templates/research_template.md

• Standards:

  docs/DOCUMENTATION_STANDARDS.md

  (if exists)

Version: 3.0.0 Last Updated: 2025-12-23