6.8 KiB
6.8 KiB
Research Guidelines
Quality guidelines for library and standards research to ensure accurate, up-to-date, and actionable information.
Source Credibility Hierarchy
Use this priority order when selecting sources:
| Priority | Source Type | Example | When to Use |
|---|---|---|---|
| 1 | Official documentation | Python.org, FastAPI docs, RFC specifications | ALWAYS prefer official docs |
| 2 | Industry standards | RFC 6749 (OAuth), OpenAPI 3.0 spec, OWASP guidelines | For protocol/standard compliance |
| 3 | Vendor documentation | AWS docs, Redis docs, PostgreSQL docs | For specific vendor implementations |
| 4 | Community standards | PEP (Python), JSR (Java), WCAG (accessibility) | For language/platform best practices |
| 5 | Authoritative blogs | Real Python, DigitalOcean tutorials, vendor blogs | For complex integration examples |
| 6 | Stack Overflow | Accepted answers with high votes (500+) | LAST RESORT - verify info elsewhere |
RED FLAGS (avoid):
- Blog posts > 2 years old (outdated patterns)
- Personal blogs without credentials
- Medium posts without verification
- Reddit/forum posts (use for direction only)
Version Selection Guidelines
| Scenario | Preferred Version | Rationale |
|---|---|---|
| Production projects | Latest LTS (Long Term Support) | Stability + security updates |
| New features | Latest stable release | Modern APIs, avoid beta/RC |
| Legacy projects | Match existing version (upgrade path in separate Story) | Avoid breaking changes |
| Experimental | Latest (including RC) | ONLY if Epic explicitly requests bleeding edge |
Version notation:
- ✅ GOOD: "v3.12.1 (LTS)" or "v2.5.0 (stable)"
- ❌ BAD: "latest" or "v3.x" (not specific)
Deprecation check:
- If library has deprecated methods → List in "Key constraints"
- If library is end-of-life → Suggest alternatives
Key APIs Extraction
Focus on 2-5 MOST RELEVANT methods for Story domain:
Good Example (rate limiting Story):
**Key APIs:**
- `Limiter(key_func=get_remote_address, default_limits=["200/day"])` - Initialize rate limiter with default limits
- `@limiter.limit("5/minute")` - Decorator for route-specific limits
- `limiter.reset()` - Reset limits programmatically (testing, admin operations)
Bad Example (too generic):
**Key APIs:**
- Constructor
- Methods
- Properties
Extraction rules:
- Include method signature (parameters, return type if critical)
- Explain WHEN to use (not just WHAT it does)
- Prioritize methods for Story domain (not all library methods)
- If >5 methods → group by category (CRUD, validation, utilities)
Constraints and Limitations
MUST document:
- Async/sync support (e.g., "slowapi v0.1.9 has NO async support")
- Storage backends (e.g., "in-memory storage doesn't persist across restarts")
- Multi-process caveats (e.g., "Limiter doesn't share state across workers without Redis")
- Platform limitations (e.g., "Windows async I/O has known issues")
- Performance limitations (e.g., "max 10K requests/sec without Redis backend")
Format:
**Key constraints:**
- [Limitation]: [Brief explanation] - [Workaround or solution]
Example:
**Key constraints:**
- No async support in v0.1.9 - Use slowapi v0.2.0+ OR sync endpoints only
- In-memory storage loses data on restart - Use Redis backend for production
- Rate limiting doesn't work across multiple workers - Configure Redis shared storage
Standards Compliance
Industry standards to check (by domain):
| Domain | Relevant Standards |
|---|---|
| Authentication | OAuth 2.0 (RFC 6749), OpenID Connect, JWT (RFC 7519) |
| REST API | OpenAPI 3.0, REST principles (RFC 7231), HATEOAS |
| Security | OWASP Top 10, NIST guidelines, CSP (Content Security Policy) |
| Data formats | JSON Schema, Protocol Buffers, Avro |
| Protocols | HTTP/2 (RFC 7540), WebSocket (RFC 6455), gRPC |
| Accessibility | WCAG 2.1, ARIA, Section 508 |
Format:
**Standards compliance:**
- [Standard/RFC name]: [How Story should comply - brief description]
Example:
**Standards compliance:**
- RFC 6749 (OAuth 2.0): Use authorization code flow with PKCE for web apps
- OWASP Top 10 (2021): Implement rate limiting to prevent brute-force attacks (A07:2021)
- OpenAPI 3.0: Document rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
Research Summary Template
## Library Research
**Primary libraries:**
| Library | Version | Purpose | Docs |
|---------|---------|---------|------|
| slowapi | v0.2.1 (stable) | Rate limiting for FastAPI endpoints | [GitHub](https://github.com/laurentS/slowapi) |
| redis-py | v5.0.0 (stable) | Redis backend for distributed rate limiting | [Redis docs](https://redis.io/docs/clients/python/) |
**Key APIs:**
- `Limiter(key_func=get_remote_address, storage_uri="redis://localhost:6379")` - Initialize with Redis backend for multi-worker support
- `@limiter.limit("5/minute")` - Apply per-route rate limits (returns 429 on exceed)
- `@limiter.exempt` - Exempt specific routes (admin endpoints, health checks)
**Key constraints:**
- slowapi v0.1.9 has NO async support - Upgrade to v0.2.0+ for FastAPI async routes
- In-memory storage loses data on restart - Use Redis backend for production environments
- Rate limiting doesn't work across multiple workers without shared storage - Configure Redis URI
**Standards compliance:**
- RFC 6585 (HTTP 429): Return 429 Too Many Requests with Retry-After header
- OWASP A07:2021 (Identification/Auth Failures): Implement rate limiting on login endpoints (5 attempts/15 min)
- OpenAPI 3.0: Document rate limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
**Existing guides:**
- [docs/guides/rate_limiting_pattern.md](docs/guides/rate_limiting_pattern.md) - Rate limiting best practices for FastAPI
Time Management
Time-box: 15-20 minutes maximum per Epic
Time allocation:
- Phase 1 (Identify): 2-3 minutes
- Phase 2 (Context7): 5-7 minutes (parallel calls)
- Phase 3 (Ref): 5-7 minutes (parallel calls)
- Phase 4 (Guides): 1-2 minutes
- Phase 5 (Summary): 2-3 minutes
If time exceeds:
- Reduce library count (focus on 2-3 primary libraries)
- Skip fallback WebSearch
- Use cached Ref results from previous Epics
Quality Checklist
Before returning Research Summary, verify:
- All libraries have specific versions (not "latest")
- Key APIs (2-5 methods) include when to use (not just what)
- Constraints list workarounds or solutions
- Standards compliance includes HOW to comply (not just standard name)
- Official docs URLs are valid (not broken links)
- Research Summary is ≤ 500 words (concise, actionable)
Version: 1.0.0 Last Updated: 2025-11-17