Commands
/research Command
Gather context before defining requirements by searching your context repository and exploring your codebase.
The /research command gathers context before you define requirements, ensuring specs are informed by existing patterns and past decisions.
Purpose
Search accumulated project context, explore codebase patterns, and fetch current information to inform spec creation.
Usage
/research <your-query>
Examples
# Research existing patterns
/research authentication patterns in this codebase
# Investigate current best practices
/research current best practices for error handling in Express.js 2025
# Understand implementations
/research how pagination is implemented in our API
# Explore architecture
/research database connection pooling strategy
# Find related features
/research user session management and token refresh
What It Does
When you run /research, Buildforce:
- Searches context repository
- Queries
.buildforce/context/_index.yamlfor relevant contexts - Loads matching context files with decisions and patterns
- Finds related contexts through cross-references
- Queries
- Explores codebase
- Discovers relevant files and their purposes
- Analyzes code patterns and conventions
- Maps relationships between components
- Fetches current information (when needed)
- Searches web for best practices
- Finds up-to-date documentation
- Validates approaches against current standards
- Produces structured report
- Research Summary - High-level findings
- Key Findings - Actionable discoveries
- File Paths - Relevant files with context
- Mermaid Diagrams - Architecture flows and relationships
- Data Models - Structure definitions
- Architectural Decisions - Past choices and rationale
- External References - Useful documentation links
- TLDR - 3-7 bullet point summary
Research Output Example
## Research Summary
The codebase uses JWT-based authentication with 15-minute token expiration
and refresh tokens. Implementation follows OAuth2 patterns with bcrypt
password hashing.
## Key Findings
- Authentication middleware in `src/auth/middleware.ts`
- JWT tokens expire after 15 minutes
- Refresh tokens stored in Redis with 7-day TTL
- Password hashing uses bcrypt with salt rounds = 10
## File Paths
| Path | Relevance |
|------|-----------|
| `src/auth/middleware.ts` | JWT validation middleware |
| `src/auth/service.ts` | Authentication business logic |
| `src/auth/tokens.ts` | Token generation and refresh |
## Mermaid Diagram
```mermaid
sequenceDiagram
Client->>API: POST /login
API->>Database: Validate credentials
Database-->>API: User data
API->>API: Generate JWT + Refresh token
API-->>Client: Tokens
TLDR
- JWT-based auth with 15-minute expiration
- Refresh tokens in Redis (7-day TTL)
- Bcrypt password hashing
- OAuth2 pattern for third-party login
## How Research Informs Spec
Research findings stay in conversation context and inform `/spec`:
**Research finds:**
```yaml
key_findings:
- "Authentication uses JWT with 15-minute expiration"
- "Refresh tokens stored in Redis"
Spec references this:
functional_requirements:
- FR1: "Implement OAuth2 login following existing JWT auth pattern"
design_principles:
- "Follow established JWT + refresh token pattern (15min access, 7day refresh)"
Pro Tips
Start Broad, Then Narrow
# First: Broad exploration
/research authentication in this codebase
# Then: Specific investigation (if needed)
/research JWT token refresh implementation details
Research Multiple Topics
Run /research multiple times before /spec:
/research error handling patterns
/research database transaction management
/research API response formatting conventions
# Now define spec with all context loaded
/spec Add user registration endpoint
Include "Current" or "2025" for Best Practices
# Triggers web search for up-to-date information
/research current best practices for React performance 2025
/research modern TypeScript error handling patterns 2025
Research Before /document
# Gather context first
/research authentication module architecture
# Then document what you learned
/document authentication module
When to Skip /research
Skip when:
- No existing context is relevant (brand new project)
- Requirements are completely clear
- Small isolated change with no architectural impact
- You already understand all relevant context
Most Common MistakeGoing straight to
/spec without /research. Even if you think you know the context, running /research often reveals patterns, conventions, or decisions you forgot about.Research vs Google/Docs
| Traditional Research | Buildforce /research |
|---|---|
| Manual file search | Automated context search |
| Lost in documentation | Structured report |
| Stale StackOverflow | Current best practices |
| Forgotten decisions | Searchable context repository |
| No project history | Accumulated team knowledge |
What Gets Materialized
If you run /research before /spec, Buildforce automatically materializes research findings into a research.yaml file alongside your spec:
.buildforce/specs/add-oauth-login-20250105/
├── research.yaml # ← Research findings materialized
├── spec.yaml # Requirements
└── plan.yaml # Implementation plan
This research.yaml becomes reference material during /build, ensuring implementation stays aligned with researched patterns.
Next Steps
- /spec Command - Define requirements informed by research
- Context Repository - Understand what
/researchsearches - Command Orchestration - See how research feeds into spec