Research
Systematic research documentation that gathers context, evaluates options, and ages gracefully with built-in freshness tracking.
Definition
Research in Farmwork is a formal process of gathering context before making decisions. Research documents live in _RESEARCH/ and are persistent (unlike plans), providing long-term reference material for your project.
Research captures what you learn about technologies, patterns, APIs, and approaches. It includes not just findings but also gotchas, security considerations, and alternative approaches considered and rejected.
Philosophy
Core Principle
Research before planning, plan before implementing. The cascade of research → plan → implement ensures each phase builds on solid foundations rather than assumptions.
In farming terms, research is soil testing before planting. You need to understand what you're working with - the composition, pH, drainage - before you can plan what to grow and how to grow it.
What Research Captures
- Official documentation summaries and links
- API capabilities and limitations
- Security implications and best practices
- Common pitfalls and gotchas
- Alternative approaches with trade-offs
- Compatibility considerations
Freshness System
Research documents track their own freshness. This is critical because technical information ages - APIs change, best practices evolve, security vulnerabilities are discovered.
| Age | Status | Indicator |
|---|---|---|
| 0-14 days | Fresh | No indicator needed |
| 15-30 days | Aging | Shown during "open the farm" |
| 30+ days | Stale | Update recommended |
Automatic Staleness Tracking
When you "open the farm", stale research documents are flagged. Say "update research on X" to refresh the document with current information while preserving historical context.
Document Structure
Research documents follow a consistent structure that makes them useful for future reference:
# Stripe Payments Research
**Last Updated:** 2024-01-15
**Status:** Fresh
## Summary
Stripe provides a complete payments platform with
excellent developer experience and comprehensive
documentation.
## Key Findings
- Payment Intents API is the recommended approach
- Webhooks required for reliable payment confirmation
- PCI compliance handled by Stripe.js and Elements
## Security Considerations
- Never log full card numbers or CVVs
- Use Stripe.js to ensure card data never touches server
- Verify webhook signatures to prevent spoofing
## Gotchas
- Idempotency keys required for retry safety
- Test mode vs live mode use different API keys
- Some features require account activation
## Alternatives Considered
- **PayPal:** Higher fees, more friction
- **Square:** Better for in-person, weaker online
- **Braintree:** Owned by PayPal, similar trade-offs
## References
- https://stripe.com/docs/payments/payment-intents
- https://stripe.com/docs/webhooks
- https://stripe.com/docs/security/guideWorkflow
Trigger Phrases
| Phrase | Action |
|---|---|
"let's research X" |
Create comprehensive research document |
"update research on X" |
Refresh existing research with new findings |
"show research on X" |
Display research summary and freshness |
Integration with Planning
Research and planning work together. A typical flow for implementing something new:
- Say "let's research authentication patterns"
- Review the research document
- Say "make a plan for user authentication"
- Plan references research: "See _RESEARCH/AUTH_PATTERNS.md"
- Implement with confidence in your decisions
Research vs Planning
Research is about understanding options and trade-offs. Planning is about deciding what to build. Keep them separate - research documents are reference material; plans are action items.