ln-002-best-practices-researcher

name	ln-002-best-practices-researcher
description	Research best practices via MCP Ref/Context7/WebSearch and create documentation (guide/manual/ADR/research). Single research, multiple output types.

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:

Indicator	Stack	Query Prefix	Official Docs
*.csproj, *.sln	.NET	"C# ASP.NET Core"	Microsoft docs
package.json + tsconfig.json	Node.js	"TypeScript Node.js"	MDN, npm docs
requirements.txt, pyproject.toml	Python	"Python"	Python docs, PyPI
go.mod	Go	"Go Golang"	Go docs
Cargo.toml	Rust	"Rust"	Rust docs
build.gradle, pom.xml	Java	"Java"	Oracle docs, Maven

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

Parameter	Required	Description
doc_type	Yes	"guide" / "manual" / "adr" / "research"
topic	Yes	What to document (pattern name, package name, decision title, research question)
story_context	No	Story/Task context for relevance

Research Tools

Tool	Use Case	Query Pattern
ref_search_documentation	Standards, patterns, RFCs	"[topic] RFC standard best practices 2025"
context7__resolve-library-id	Get library ID for docs	libraryName="[topic]"
context7__query-docs	Library API, methods	topic="[stack_prefix] [topic]"
WebSearch	Market, competitors, versions	"[topic] latest 2025" or "[topic] vs alternatives"

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

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

Type	Focus	Primary Sources	Key Questions
Technical	Solution comparison	Docs, benchmarks, RFCs	"Which solution fits our use-case?"
Market	Industry landscape	Reports, blogs, articles	"What's the market size/trend?"
Competitor	How others solve it	Product pages, reviews, demos	"What features do competitors offer?"
Requirements	User needs	Feedback, support tickets, forums	"What do customers complain about?"
Feasibility	Can we build it?	PoC, prototypes, local tests	"Is it technically possible?"
Feature Demand	Feature viability	Competitor features + blogs/socials + user complaints	"Is this feature worth building?"

Workflow by doc_type

doc_type	Purpose	Research Source	Template	Output Path	Words
guide	Pattern with Do/Don't/When table	ref_search (best practices)	guide_template.md	guides/NN-[slug].md	300-500
manual	API/library reference	context7__query-docs	manual_template.md	manuals/[pkg]-[ver].md	300-500
adr	Architecture decision	Dialog (5 questions)	adr_template.md	adrs/adr-NNN-[slug].md	300-500
research	Investigation answering question	See Methodology table above	research_template.md	research/rsh-NNN-[slug].md	300-700

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):

Forbidden	Allowed
Code snippets	Tables (params, config, alternatives)
Implementation examples	ASCII diagrams, Mermaid diagrams
Code blocks >1 line	Method signatures (1 line inline)
	Links to official docs

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            │
└───────────────────────────────────────────────┘

Content Type	Format
Parameters	Table: Name | Type | Required | Default
Configuration	Table: Option | Type | Default | Description
Alternatives	Table: Alt | Pros | Cons | Why Rejected
Patterns	Table: Do | Don't | When
Workflow	ASCII diagram: 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