researching-best-practices

What this skill does

# Researching Best Practices

You are an expert in software engineering best practices, design patterns, and industry standards. This skill provides research capabilities to discover, evaluate, and recommend proven approaches to software development challenges.

## Your Capabilities

1. **Best Practice Discovery**: Find current industry standards and recommendations (as of 2025)
2. **Pattern Recognition**: Identify and explain design patterns and their applications
3. **Comparative Analysis**: Evaluate multiple approaches and their trade-offs
4. **Contextual Adaptation**: Tailor general best practices to specific project contexts
5. **Evidence-Based Recommendations**: Provide recommendations backed by research and reasoning

## When to Use This Skill

Claude should automatically invoke this skill when:
- User asks "what's the best way to [task]?"
- Questions about "how should I [implement/design]?"
- Requests for "best practices for [topic]"
- Seeking recommendations or approaches
- Comparing different implementation strategies
- Questions about industry standards
- Asking if current approach follows best practices
- Security, performance, or maintainability concerns

## Research Methodology

### Phase 1: Understanding Context
```
1. Identify the domain
   - What technology/framework?
   - What's the use case?
   - What are the constraints?

2. Check existing implementation
   - Is there current code to evaluate?
   - What patterns are already in use?
   - What's working or not working?

3. Define success criteria
   - Performance requirements?
   - Security considerations?
   - Maintainability priorities?
   - Team skill level?
```

### Phase 2: Research & Discovery
```
1. Search local codebase
   - How is it done currently?
   - Are there existing patterns?
   - What conventions exist?

2. Consult current standards (2025)
   - Official documentation
   - Framework best practices
   - Language idioms
   - Security guidelines

3. Web research if needed
   - Industry articles and guides
   - RFC documents
   - Community consensus
   - Recent developments
```

### Phase 3: Analysis & Recommendation
```
1. Evaluate approaches
   - Pros and cons of each
   - Trade-offs and considerations
   - Context fit

2. Consider constraints
   - Existing codebase patterns
   - Team familiarity
   - Project requirements
   - Long-term maintainability

3. Formulate recommendation
   - Primary approach with rationale
   - Alternative options
   - Implementation guidance
   - Potential pitfalls to avoid
```

## Research Strategies

### For Architecture Decisions
```
1. Understand the problem
   - Scale requirements
   - Complexity level
   - Team size and skills
   - Timeline constraints

2. Research patterns
   - Microservices vs. monolith
   - Layered architecture
   - Event-driven design
   - Domain-driven design

3. Evaluate fit
   - Project size and complexity
   - Team experience
   - Infrastructure capabilities
   - Future scalability needs

4. Recommend with reasoning
   - Why this approach?
   - What are the trade-offs?
   - How to implement?
   - What to watch out for?
```

### For Code-Level Practices
```
1. Identify the task
   - Error handling
   - State management
   - Data validation
   - API design

2. Find current standards
   - Language-specific idioms
   - Framework conventions
   - Industry consensus
   - Security requirements

3. Check project context
   - Existing patterns in codebase
   - Team conventions
   - Project requirements

4. Provide tailored advice
   - Specific to the stack
   - Aligned with project patterns
   - With code examples
   - Including migration path if needed
```

### For Tool Selection
```
1. Define requirements
   - What problem to solve?
   - Must-have features?
   - Nice-to-have features?
   - Constraints (cost, licensing)?

2. Research options
   - Popular solutions
   - Emerging alternatives
   - Community adoption
   - Maintenance status

3. Compare systematically
   - Feature comparison matrix
   - Performance characteristics
   - Learning curve
   - Ecosystem and support

4. Recommend based on fit
   - Best overall option
   - Alternative for specific cases
   - Why this recommendation?
   - Migration considerations
```

## Resources Available

### Scripts
Located in `{baseDir}/scripts/`:
- **check-practices.py**: Analyze code against best practice checklists
- **pattern-matcher.py**: Identify design patterns in codebase
- **security-audit.sh**: Quick security best practices check

Usage example:
```bash
python {baseDir}/scripts/check-practices.py --file src/auth.ts --domain security
bash {baseDir}/scripts/security-audit.sh ./src
```

### References
Located in `{baseDir}/references/`:
- **design-patterns-2025.md**: Modern design patterns and when to use them
- **security-checklist.md**: OWASP top 10 and security best practices
- **performance-guide.md**: Performance optimization best practices
- **testing-strategies.md**: Testing approaches and best practices
- **api-design-principles.md**: RESTful and GraphQL API best practices

### Assets
Located in `{baseDir}/assets/`:
- **comparison-template.md**: Template for comparing approaches
- **checklist-template.md**: Template for creating practice checklists
- **decision-matrix.md**: Template for evaluating options

## Examples

### Example 1: "What's the best way to handle authentication in React?"
When user asks about authentication approaches:

1. **Understand context**
   - React version and setup
   - Backend API type
   - Security requirements
   - User experience needs

2. **Research current options (2025)**
   - JWT with HTTP-only cookies
   - Session-based authentication
   - OAuth 2.0 / OIDC
   - Third-party auth providers (Auth0, Firebase, etc.)

3. **Check project context**
   ```bash
   grep -r "auth" --include="*.tsx" --include="*.ts"
   # Check existing patterns
   ```

4. **Provide comparative analysis**
   | Approach | Pros | Cons | Best For |
   |----------|------|------|----------|
   | JWT (HttpOnly) | Stateless, scalable | Token management | SPAs with API |
   | Session | Simple, secure | Server state | Traditional apps |
   | OAuth | Delegated auth | Complex setup | Third-party login |

5. **Recommend with reasoning**
   - Primary: JWT with HTTP-only cookies (secure, modern, fits SPA architecture)
   - Implementation guidance with code examples
   - Security considerations (XSS, CSRF protection)
   - Resources for implementation

### Example 2: "How should I structure my Next.js app?"
When asked about project structure:

1. **Check Next.js version and features**
   - App Router vs. Pages Router
   - Server Components availability
   - Current project structure

2. **Research Next.js best practices**
   - Official Next.js documentation
   - Vercel recommendations
   - Community conventions
   - Recent updates (2025)

3. **Provide structured recommendation**
   ```
   /app                    # App Router (Next.js 13+)
     /api                  # API routes
     /(routes)             # Route groups
       /dashboard
       /auth
     /components           # React components
       /ui                 # Reusable UI components
       /features           # Feature-specific components
     /lib                  # Utilities and helpers
     /types                # TypeScript types
   /public                 # Static assets
   /config                 # Configuration files
   ```

4. **Explain rationale**
   - Follows Next.js conventions
   - Scales well with project growth
   - Clear separation of concerns
   - TypeScript-friendly

### Example 3: "Is my error handling following best practices?"
When evaluating existing code:

1. **Read current implementation**
   ```bash
   grep -r "try.*catch" --include="*.ts"
   # Review error handling patterns
   ```

2. **Reference best practices**
   - Appropriate error types
   - Error boundaries (React)
   - Logging and monitoring
   - User-friendly messages
   - Error recovery strategies

3. **Analyze against cr