Commands
/document Command
Create context files for existing code without running the full spec-driven workflow.
The /document command creates context files for existing code without running the full spec-driven workflow.
Purpose
Document existing functionality, legacy code, or tribal knowledge by creating or updating structured context files in your project's knowledge repository.
Usage
/document <topic-or-module>
Examples
# Document a module
/document authentication module
# Document patterns
/document error handling patterns
# Document infrastructure
/document database connection pooling strategy
# Document legacy code
/document legacy payment processing system
# Document conventions
/document API response formatting conventions
What It Does
When you run /document, Buildforce:
- Analyzes Conversation History
- Reviews recent discussion about the topic
- Extracts key decisions and patterns
- Identifies relevant code examples
- Determines Mode
- CREATE: No context file exists for this topic
- UPDATE: Context file exists, will be merged
- Generates Context File
- Structured YAML in
.buildforce/context/ - Includes decisions, patterns, file paths
- Auto-generates ID and metadata
- Structured YAML in
- Updates Context Index
- Adds entry to
_index.yaml - Creates searchable tags
- Links related contexts
- Adds entry to
- Resolves Conflicts
- Detects duplicate topic names
- Prompts for merge or new name
- Maintains consistency
Typical Workflow
Prepare Context Window
Before /document, gather information:
# Option 1: Run research first
/research authentication patterns in this codebase
/document authentication module
# Option 2: Read and discuss files
# (Read src/auth/*.ts files, discuss patterns)
/document authentication security patterns
# Option 3: Ask questions, explore code
# (Discussion about error handling)
/document error handling conventions
Richer Context → Better DocumentationThe more context in your conversation history (code exploration, pattern discussion, file reading), the better the generated context file will be.
Generated Context Example
Input
# After discussing authentication implementation
/document authentication module
Output
# .buildforce/context/authentication-module.yaml
version: "0.0.29"
id: "authentication-module"
name: "Authentication Module"
type: module
created: "2025-01-05"
last_updated: "2025-01-05"
description: |
JWT-based authentication with argon2 password hashing,
httpOnly cookie storage, and PostgreSQL-backed refresh tokens.
overview: |
The authentication system handles user login, token generation,
and session management. Uses industry-standard JWT with short-lived
access tokens (15min) and long-lived refresh tokens (7 days).
key_decisions:
- decision: "argon2 for password hashing"
rationale: "Superior resistance to GPU brute-force attacks"
- decision: "httpOnly cookies for token storage"
rationale: "XSS protection - tokens not accessible via JavaScript"
file_paths:
primary:
- path: "src/auth/service.ts"
purpose: "Core authentication business logic"
- path: "src/auth/middleware.ts"
purpose: "JWT validation and route protection"
architectural_patterns:
- pattern: "Repository Pattern"
description: "AuthRepository abstracts database operations"
- pattern: "Middleware Chain"
description: "JWT validation → RBAC → route handler"
code_snippets:
- title: "JWT Validation Middleware"
language: "typescript"
code: |
export const validateJWT = async (req, res, next) => {
const token = req.cookies.accessToken;
if (!token) return res.status(401).json({ error: 'Unauthorized' });
try {
const payload = jwt.verify(token, SECRET);
req.user = payload;
next();
} catch (err) {
return res.status(401).json({ error: 'Invalid token' });
}
};
related_context:
- user-management
- api-security
tags:
- authentication
- jwt
- argon2
- security
- middleware
CREATE vs UPDATE Mode
CREATE Mode (New Context)
First time documenting a topic:
/document caching strategy
Result:
- Creates new
caching-strategy.yaml - Adds to
_index.yaml - Generates unique ID
UPDATE Mode (Merge with Existing)
Subsequent documentation of same topic:
/document caching strategy
Buildforce Response:
Context file 'caching-strategy.yaml' already exists.
Options:
A. Update existing context (merge new information)
B. Create new context with different name
C. Cancel
Your choice?
If you choose A (Update):
# Updates section added
updates:
- date: "2025-01-08"
summary: "Added Redis cluster configuration details"
# New information merged into existing sections
Best Practices
Do:
✅ Prepare context window first
/research authentication patterns
# Read relevant files, discuss architecture
/document authentication module
✅ Document meaningful patterns
/document error handling strategy across services
✅ Capture tribal knowledge
/document why we chose PostgreSQL over MongoDB for user data
✅ Document conventions
/document API naming conventions and response formats
Don't:
❌ Document trivial details
/document how to write a for loop # Too basic
❌ Document with no context
# Empty conversation history
/document authentication # Won't have enough information
❌ Document work-in-progress
# Feature not complete
/document half-implemented payment flow # Wait until complete
When to Use /document
Instead of Full Workflow
Use /document when:
- No implementation needed - Just documenting existing code
- Legacy systems - Capturing knowledge about old code
- Tribal knowledge - Writing down unwritten rules
- Team onboarding - Creating knowledge base for new developers
Complement to /complete
/complete auto-generates context from spec+plan+build./document manually creates context when no spec exists.
Use both:
/completefor new features (automatic documentation)/documentfor existing code (manual documentation)
Context File Quality
Generated context quality depends on conversation richness:
Poor Context:
# Minimal conversation
/document auth module
Result: Sparse context file with little detail
Rich Context:
# Extensive discussion
/research authentication in our codebase
# Read 5 auth-related files
# Discuss patterns, decisions, trade-offs
# Review code examples
/document authentication module and security patterns
Result: Comprehensive context with decisions, patterns, examples
Pro TipThink of
/document as crystallizing your conversation into searchable knowledge. The richer your conversation, the better the documentation.Integration with /research
Documents created with /document become searchable via /research:
# Document legacy code
/research payment processing in this codebase
/document legacy payment system architecture
# Later, new developer uses it
/research payment processing
# Finds your documentation: legacy-payment-system.yaml
Conflict Resolution
If context file already exists:
## Context Conflict Detected
A context file named 'authentication.yaml' already exists.
**Existing context:**
- ID: authentication-module
- Created: 2025-01-05
- Description: JWT-based authentication
**New documentation:**
- Would create: authentication-module-2.yaml
- Topic: OAuth2 authentication integration
**Options:**
A. Merge into existing 'authentication.yaml'
B. Create 'oauth2-authentication.yaml' (new file)
C. Create 'authentication-oauth2-integration.yaml' (descriptive name)
X. Cancel
Choose A-C or X:
Next Steps
- Context Repository - Understand how context is stored
- /research Command - Search documented context
- /complete Command - Auto-generate context from features