Research Patterns Enforcement Skill

Ensures every research task follows a consistent, evidence-based methodology. Used by the researcher and researcher-local agents.

4-Phase Research Methodology

Every research task MUST follow these phases in order.

Phase 1: Codebase Recon

Grep/Glob for existing patterns that relate to the task
Identify what the codebase already does (avoid reinventing)
Note file locations, naming conventions, architectural patterns
Document existing test patterns for the area

Phase 2: Targeted Web Search

Formulate 2-3 specific search queries
Include the current year in queries for freshness (e.g., "JWT best practices 2026")
Search for official documentation first
Search for known issues or CVEs if security-related

Phase 3: Deep Fetch Top Sources

Fetch the top 2-3 most relevant results
Extract specific code examples, configuration snippets, or API references
Note version numbers and compatibility requirements
Record URLs for citation

Phase 4: Synthesis with Gap Analysis

Compare findings against existing codebase patterns
Identify gaps between current implementation and best practices
Produce structured recommendations with tradeoffs
Flag risks and unknowns explicitly

Source Hierarchy

When sources conflict, prefer in this order:

Official documentation — language docs, framework docs, RFCs
Authoritative GitHub repos — reference implementations, official examples
Stack Overflow — accepted answers with high votes, verify currency
Blog posts / tutorials — cross-reference with official docs

Every recommendation MUST include at least one URL source.

HARD GATE: Research Output

FORBIDDEN:

Recommending an approach without citing sources
Using "I think" or "I believe" without supporting evidence
Skipping codebase search (Phase 1) and jumping straight to web
Single-source recommendations — minimum 2 sources for any recommendation
Presenting opinions as facts
Ignoring existing codebase patterns in favor of greenfield approaches

REQUIRED:

Minimum 3 sources cited across the research output
Existing codebase patterns identified first (Phase 1 before Phase 2)
Tradeoffs stated for every recommendation (pros AND cons)
Structured output in the format below
Version/date noted for all external sources
Risks section with at least one identified risk

Required Output Format

{
  "findings": "Summary of what was discovered",
  "sources": [
    {"url": "https://...", "title": "...", "relevance": "..."},
    {"url": "https://...", "title": "...", "relevance": "..."},
    {"url": "https://...", "title": "...", "relevance": "..."}
  ],
  "existing_patterns": [
    {"file": "path/to/file.py", "pattern": "description", "reusable": true}
  ],
  "recommendations": [
    {
      "approach": "description",
      "pros": ["..."],
      "cons": ["..."],
      "effort": "low/medium/high"
    }
  ],
  "risks": [
    {"risk": "description", "mitigation": "how to handle", "severity": "low/medium/high"}
  ]
}

Anti-Patterns

BAD: Vague "best practice" without citation

"The best practice is to use dependency injection."

No source, no context, no tradeoffs. Useless as research output.

GOOD: Cited recommendation with tradeoffs

"Dependency injection is recommended by the Python Packaging Guide
(https://packaging.python.org/...) for testability. Tradeoff: adds
indirection that can make debugging harder for small projects."

BAD: Ignoring existing codebase patterns

Recommending a completely new auth library when the codebase already uses a working pattern. Always check what exists first.

BAD: Single-source echo chamber

Reading one blog post and presenting its opinion as the definitive answer. Cross-reference with at least one other source.

GOOD: Multiple sources with synthesis

"Three sources agree on token rotation (RFC 6749 Section 10.4,
OWASP Cheat Sheet, and the existing auth.py pattern at line 42).
The codebase already implements refresh tokens; recommend extending
rather than replacing."

Cross-References

security-patterns: Security-specific research requirements
architecture-patterns: How research feeds into architecture planning
project-alignment: Ensuring research aligns with PROJECT.md scope

research-patterns