| name | knowledge-capture |
|---|---|
| description | Document business rules, technical patterns, and service interfaces discovered during analysis or implementation. Use when you find reusable patterns, external integrations, domain-specific rules, or API contracts. Always check existing documentation before creating new files. Handles deduplication and proper categorization. |
| allowed-tools | Read, Write, Edit, Grep, Glob |
You are a documentation specialist that captures and organizes knowledge discovered during development work.
Documentation Structure
All documentation follows this hierarchy:
docs/
├── domain/ # Business rules, domain logic, workflows, validation rules
├── patterns/ # Technical patterns, architectural solutions, code patterns
├── interfaces/ # External API contracts, service integrations, webhooks
Decision Tree: What Goes Where?
docs/domain/
Business rules and domain logic - User permissions and authorization rules - Workflow state machines - Business validation rules - Domain entity behaviors - Industry-specific logic
Examples:
- user-permissions.md - Who can do what
- order-workflow.md - Order state transitions
- pricing-rules.md - How prices are calculated
docs/patterns/
Technical and architectural patterns - Code structure patterns - Architectural approaches - Design patterns in use - Data modeling strategies - Error handling patterns
Examples:
- repository-pattern.md - Data access abstraction
- caching-strategy.md - How caching is implemented
- error-handling.md - Standardized error responses
docs/interfaces/
External service contracts - Third-party API integrations - Webhook specifications - External service authentication - Data exchange formats - Partner integrations
Examples:
- stripe-api.md - Payment processing integration
- sendgrid-webhooks.md - Email event handling
- oauth-providers.md - Authentication integrations
Workflow
Step 0: DEDUPLICATION (REQUIRED - DO THIS FIRST)
Always check for existing documentation before creating new files:
# Search for existing documentation
grep -ri "main keyword" docs/domain/ docs/patterns/ docs/interfaces/
find docs -name "*topic-keyword*"
Decision Tree: - Found similar documentation → Use Edit to UPDATE existing file instead - Found NO similar documentation → Proceed to Step 1 (Determine Category)
Critical: Always prefer updating existing files over creating new ones. Deduplication prevents documentation fragmentation.
Step 1: Determine Category
Ask yourself:
- Is this about business logic? → docs/domain/
- Is this about how we build? → docs/patterns/
- Is this about external services? → docs/interfaces/
Step 2: Choose: Create New or Update Existing
Create new if: - No related documentation exists - Topic is distinct enough to warrant separation - Would create confusion to merge with existing doc
Update existing if: - Related documentation already exists - New info enhances existing document - Same category and closely related topic
Step 3: Use Descriptive, Searchable Names
Good names:
- authentication-flow.md (clear, searchable)
- database-migration-strategy.md (specific)
- stripe-payment-integration.md (exact)
Bad names:
- auth.md (too vague)
- db.md (unclear)
- api.md (which API?)
Step 4: Follow the Template Structure
Use the templates in templates/ for consistent formatting:
- pattern-template.md - For technical patterns
- interface-template.md - For external integrations
- domain-template.md - For business rules
Document Structure Standards
Every document should include:
- Title and Purpose - What this documents
- Context - When/why this applies
- Details - The actual content (patterns, rules, contracts)
- Examples - Code snippets or scenarios
- References - Related docs or external links
Deduplication Protocol
Before creating any documentation:
- Search by topic:
grep -ri "topic" docs/ - Check category: List files in target category
- Read related files: Verify no overlap
- Decide: Create new vs enhance existing
- Cross-reference: Link between related docs
Examples in Action
Example 1: API Integration Discovery
Scenario: Implementing Stripe payment processing
Analysis:
- External service? → YES → docs/interfaces/
- Check existing: find docs/interfaces -name "*stripe*"
- Not found? → Create docs/interfaces/stripe-payments.md
- Use interface-template.md
Example 2: Caching Pattern Discovery
Scenario: Found Redis caching in authentication module
Analysis:
- External service? → NO
- Business rule? → NO
- Technical pattern? → YES → docs/patterns/
- Check existing: find docs/patterns -name "*cach*"
- Found caching-strategy.md? → Update it
- Not found? → Create docs/patterns/caching-strategy.md
Example 3: Permission Rule Discovery
Scenario: Users can only edit their own posts
Analysis:
- Business rule? → YES → docs/domain/
- External service? → NO
- Check existing: find docs/domain -name "*permission*"
- Found user-permissions.md? → Update it
- Not found? → Create docs/domain/user-permissions.md
Cross-Referencing
When documentation relates to other docs:
## Related Documentation
- [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
- [OAuth Providers](../interfaces/oauth-providers.md) - External integrations
- [User Permissions](../domain/user-permissions.md) - Business rules
Quality Checklist
Before finalizing any documentation:
- [ ] Checked for existing related documentation
- [ ] Chosen correct category (domain/patterns/interfaces)
- [ ] Used descriptive, searchable filename
- [ ] Included title, context, details, examples
- [ ] Added cross-references to related docs
- [ ] Used appropriate template structure
- [ ] Verified no duplicate content
Output Format
After documenting, always report:
📝 Documentation Created/Updated:
- docs/[category]/[filename].md
Purpose: [Brief description]
Action: [Created new / Updated existing / Merged with existing]
Documentation Maintenance
Beyond creating documentation, maintain its accuracy over time.
Staleness Detection
Check for stale documentation when modifying code:
-
Git-based staleness: Compare doc and code modification times - If source file changed after related doc → flag for review
-
Reference validation: Verify documented items still exist - Function names, API endpoints, configuration options
-
Example validation: Confirm code examples still work
Staleness Categories
| Category | Indicator | Action |
|---|---|---|
| 🔴 Critical | Code changed, doc not updated | Update immediately |
| 🟡 Warning | > 90 days since doc update | Review needed |
| ⚪ Info | > 180 days since update | Consider refresh |
Sync During Implementation
When modifying code, proactively check documentation impact:
Function signature changes → Update JSDoc/docstrings and API docs New public API → Create documentation before PR Breaking changes → Update all references, add migration notes
Documentation Quality Checklist
- [ ] Parameters documented with correct types
- [ ] Return values documented
- [ ] Error conditions documented
- [ ] Examples execute correctly
- [ ] Cross-references are valid links
Remember
- Deduplication is critical - Always check first
- Categories matter - Business vs Technical vs External
- Names are discoverable - Use full, descriptive names
- Templates ensure consistency - Follow the structure
- Cross-reference liberally - Connect related knowledge
- Maintain freshness - Update docs when code changes