irahardianto/agy-perf-optimization-demo/research-methodology

Research Methodology Skill

Ensure code is informed by accurate, up-to-date knowledge — not stale training data.

When to Invoke

• Before implementing with unfamiliar tech
• Evaluating library/framework options
• Architect informing design decisions
• Builder encountering unknown API/pattern

Process

1. Topic Decomposition

Break into 2-5 keyword searchable topics:

"Task CRUD API with Supabase":
  1. Supabase client library JS/TS
  2. Supabase RLS policies
  3. Supabase real-time subscriptions
  4. PostgreSQL UUID PK patterns
  5. TS type generation from Supabase

2. Multi-Tool Search

Strategy: broad search → find doc page → deep read → search gotchas + edge cases.

3. Document Findings

Path: docs/research_logs/{feature_name}.md

# Research: {Topic}
Date: {date}
Researcher: {agent}
 
## Topics Investigated
1.{topic} — {tool} — {finding}
 
## Key Patterns
-{Pattern}: {description + code}
 
## API Signatures

// Exact API from docs

 
## Gotchas
- {Gotcha}: {avoidance}
 
## Code Examples

// Working examples from docs

 
## Sources
- [{title}]({url}) — {learned}
 
## Training Data Reliance
- {topic}: Relying on training data. No external verification.

4. Training Data Fallback

If no search yields results:

1. Document queries attempted + tools used
2. Explicitly state: "Relying on training data for {topic}. External verification unavailable."
3. Flag for human review
4. If critical, ask user for docs

Never silently use training data when verification is available.

5. ADRs

If research reveals choice between 2+ approaches, new dependency, or arch change → create ADR via adr skill at docs/decisions/NNNN-short-title.md. The adr skill template produces structured-spec-compatible ADRs with YAML frontmatter and <!-- decision --> annotations.

Agent Integration

Research logs persist in docs/research_logs/ for cross-session knowledge. ADRs follow adr skill format.