Initial commit

skills/documentation/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: documentation
+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:**
+
+```bash
+# 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:
+
+1. **Title and Purpose** - What this documents
+2. **Context** - When/why this applies
+3. **Details** - The actual content (patterns, rules, contracts)
+4. **Examples** - Code snippets or scenarios
+5. **References** - Related docs or external links
+
+## Deduplication Protocol
+
+Before creating any documentation:
+
+1. **Search by topic**: `grep -ri "topic" docs/`
+2. **Check category**: List files in target category
+3. **Read related files**: Verify no overlap
+4. **Decide**: Create new vs enhance existing
+5. **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:
+
+```markdown
+## 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]
+```
+
+## 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