Initial commit

2025-11-29 18:32:48 +08:00
commit 9997176040
24 changed files with 2371 additions and 0 deletions
--- a/skills/prp-generator/references/research_methodology.md
+++ b/skills/prp-generator/references/research_methodology.md
@@ -0,0 +1,334 @@
+# 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**:
+```bash
+# 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