gh-henkisdabro-wookstar-claude-code-plugins-productivity-toolkit/skills/prp-generator/references/research_methodology.md

Research Methodology for PRP Generation

This document provides detailed guidance on conducting thorough research for creating comprehensive Product Requirement Plans.

Research Philosophy

The AI agent implementing the PRP only receives:

1. The context you include in the PRP
2. Their training data knowledge
3. Access to the codebase
4. WebSearch capabilities

Therefore, your research findings MUST be:

• Comprehensive: Cover all aspects of implementation
• Specific: Include exact URLs, file paths, line numbers
• Actionable: Provide concrete examples and patterns
• Complete: Assume the implementer won't have your conversation context

Codebase Analysis Process

1. Find Similar Features

Goal: Identify existing implementations that solve similar problems

Approach:

# Search for similar feature keywords
# Use Grep tool with relevant patterns

# Look for:
- Similar UI components
- Similar API endpoints
- Similar data models
- Similar business logic

What to Document:

• Exact file paths with line numbers (e.g., src/components/UserProfile.tsx:45-67)
• Code snippets showing the pattern
• Why this pattern is relevant
• Any modifications needed

Example:

Found: User authentication flow in `src/auth/AuthProvider.tsx:23-89`
Pattern: Context provider with useAuth hook
Relevance: Similar state management approach needed for feature X
Adaptation: Will need to add Y and Z properties

2. Identify Architectural Patterns

Goal: Understand how the codebase is structured

Look for:

• Directory structure conventions
• File naming patterns
• Component organization
• State management approach (Redux, Context, Zustand, etc.)
• API structure patterns
• Database access patterns
• Error handling patterns

What to Document:

Pattern: Feature-based directory structure
Example: src/features/authentication/
Application: Create src/features/[new-feature]/ with:
  - components/
  - hooks/
  - types/
  - api/
  - tests/

3. Analyze Coding Conventions

Goal: Ensure consistency with existing codebase

Check:

• TypeScript usage (strict mode? interfaces vs types?)
• Component patterns (FC vs function? default vs named exports?)
• Styling approach (CSS modules, styled-components, Tailwind?)
• Import ordering
• Comment style
• Function naming (camelCase, descriptive names)

What to Document:

Convention: Named exports for all components
Example: export function UserProfile() { ... }
Reasoning: Easier refactoring and better IDE support

4. Study Test Patterns

Goal: Write tests that match existing patterns

Investigate:

• Test framework (Jest, Vitest, etc.)
• Testing library usage (@testing-library/react?)
• Test file naming (*.test.ts or *.spec.ts?)
• Test organization (co-located or separate test directory?)
• Mock patterns
• Test coverage expectations

What to Document:

Pattern: Co-located tests with *.test.tsx suffix
Framework: Vitest + @testing-library/react
Example: src/components/Button.test.tsx
Approach: Test user interactions, not implementation details
Mock Strategy: Use vi.fn() for callbacks, MSW for API calls

5. Check Configuration Files

Goal: Understand build, lint, and tooling setup

Review:

• package.json - scripts and dependencies
• tsconfig.json - TypeScript configuration
• vite.config.ts or webpack.config.js - build setup
• .eslintrc - linting rules
• .prettierrc - formatting rules

What to Document:

TypeScript: Strict mode enabled
Build: Vite with React plugin
Path Aliases: '@/' maps to 'src/'
Must use: Import type syntax for type-only imports

External Research Process

1. Library Documentation

When to Search:

• Using a new library or framework feature
• Integrating third-party services
• Implementing complex functionality

How to Search:

1. Go directly to official documentation
2. Search for the specific version being used
3. Look for:
   • Getting started guides
   • API references
   • Examples
   • Migration guides
   • Known issues

What to Document:

Library: @tanstack/react-query v5
URL: https://tanstack.com/query/latest/docs/react/guides/queries
Key Sections:
  - Queries: https://tanstack.com/query/latest/docs/react/guides/queries
  - Mutations: https://tanstack.com/query/latest/docs/react/guides/mutations
Version: 5.28.0 (check package.json)
Gotchas:
  - Query keys must be arrays
  - Automatic refetching on window focus (may want to disable)
  - Stale time defaults to 0

2. Implementation Examples

Where to Search:

• GitHub repositories (search: "language:typescript [feature]")
• StackOverflow (recent answers)
• Official example repositories
• Blog posts from reputable sources

What to Look For:

• Production-grade code (not quick hacks)
• Recent examples (check dates)
• Well-explained implementations
• Edge case handling

What to Document:

Example: Form validation with Zod and React Hook Form
Source: https://github.com/react-hook-form/react-hook-form/tree/master/examples/V7/zodResolver
Relevance: Shows integration pattern we need
Key Takeaway: Use zodResolver for seamless integration
Caution: Needs @hookform/resolvers package

3. Best Practices Research

Search Queries:

• "[Technology] best practices 2024"
• "[Feature] common pitfalls"
• "[Library] performance optimization"
• "[Pattern] security considerations"

What to Document:

Practice: Input sanitization for user-generated content
Why: Prevent XSS attacks
How: Use DOMPurify library before rendering HTML
Reference: https://owasp.org/www-community/attacks/xss/
Warning: Never use dangerouslySetInnerHTML without sanitization

4. Performance Considerations

Research:

• Bundle size implications
• Runtime performance patterns
• Common optimization techniques
• Lazy loading opportunities

What to Document:

Performance: Large data table rendering
Solution: Use virtualization (@tanstack/react-virtual)
Reference: https://tanstack.com/virtual/latest
Benefit: Render only visible rows (handles 100k+ items)
Tradeoff: Adds 15KB to bundle

5. Security Research

Check:

• Common vulnerabilities (OWASP Top 10)
• Authentication/authorization patterns
• Data validation requirements
• Secure defaults

What to Document:

Security: API authentication
Pattern: Use HTTP-only cookies for tokens
Reference: https://owasp.org/www-community/HttpOnly
Implementation: Configure in Cloudflare Workers
Warning: Don't store tokens in localStorage

Combining Research Findings

Integration Analysis

After completing both codebase and external research:

1. Match external patterns to codebase conventions

   • "Library X recommends pattern Y, but codebase uses pattern Z"
   • Document adaptations needed

2. Identify conflicts or gaps

   • "Existing auth pattern doesn't support OAuth"
   • Document how to extend existing patterns

3. Plan integration points

   • "New feature will integrate with existing [Component] at [Location]"
   • Document all touch points

Context Completeness Check

Before finalizing research, verify:

• Can implementer understand the codebase structure from your findings?
• Are all external dependencies documented with versions and URLs?
• Are code examples specific enough to follow?
• Are gotchas and warnings clearly stated?
• Are all integration points identified?
• Can implementer validate their work with the gates you've defined?

Research Output Format

Organize findings into these categories for the PRP:

1. Codebase Analysis

   • Similar patterns (with file:line references)
   • Existing conventions (with examples)
   • Test patterns (with framework details)

2. External Research

   • Documentation references (with specific URLs and sections)
   • Implementation examples (with source links and relevance)
   • Best practices (with rationale and warnings)

3. Integration Points

   • Where new code connects to existing code
   • What patterns to follow
   • What conventions to maintain

Common Research Pitfalls to Avoid

1. Vague references: "There's a similar component somewhere" ❌

   • Should be: "See UserProfile component at src/components/UserProfile.tsx:45" ✅

2. Outdated examples: Linking to old blog posts or deprecated APIs ❌

   • Should be: Check dates, verify current best practices ✅

3. Missing version info: "Use React Query" ❌

   • Should be: "Use @tanstack/react-query v5.28.0" ✅

4. No gotchas: Assuming smooth implementation ❌

   • Should be: Document known issues, common mistakes, edge cases ✅

5. Too generic: "Follow React best practices" ❌

   • Should be: Specific patterns with code examples ✅

Research Time Allocation

Codebase Analysis: 40% of research time

• Critical for maintaining consistency
• Most valuable for implementation

External Research: 35% of research time

• Essential for new technologies
• Validation of approaches

Integration Planning: 15% of research time

• Connecting the dots
• Identifying conflicts

Documentation: 10% of research time

• Organizing findings
• Creating clear references

Quality Indicators

Your research is complete when:

• ✅ An implementer could start coding immediately
• ✅ All necessary context is documented
• ✅ Integration points are clear
• ✅ Validation approach is defined
• ✅ Edge cases are identified
• ✅ Error handling strategy is outlined
• ✅ No assumptions are left undocumented