Initial commit

2025-11-30 08:53:07 +08:00
commit b5ab310674
19 changed files with 5687 additions and 0 deletions
--- a/skills/documentation/SKILL.md
+++ b/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
--- a/skills/documentation/reference.md
+++ b/skills/documentation/reference.md
@@ -0,0 +1,388 @@
+# Documentation Skill Reference
+
+Complete reference for the documentation skill including advanced patterns, edge cases, and detailed protocols.
+
+## Advanced Categorization Rules
+
+### Gray Areas and Edge Cases
+
+#### When Business and Technical Overlap
+
+**Authentication Example:**
+- `docs/domain/user-roles.md` - WHO can access WHAT (business rule)
+- `docs/patterns/authentication-flow.md` - HOW authentication works (technical)
+- `docs/interfaces/oauth-providers.md` - EXTERNAL services used (integration)
+
+**Guideline:** If it affects WHAT users can do → domain. If it affects HOW we build it → patterns.
+
+#### When Pattern Becomes Interface
+
+**Caching Example:**
+- Local in-memory caching → `docs/patterns/caching-strategy.md`
+- Redis/Memcached integration → `docs/interfaces/redis-cache.md`
+
+**Guideline:** Self-contained code patterns → patterns. External service dependencies → interfaces.
+
+#### When Multiple Categories Apply
+
+**Payment Processing Example:**
+Could span all three:
+- `docs/domain/payment-rules.md` - Refund policies, pricing rules
+- `docs/patterns/payment-processing.md` - Internal payment handling
+- `docs/interfaces/stripe-api.md` - Stripe integration specifics
+
+**Guideline:** Create separate documents for each perspective. Cross-reference heavily.
+
+## Naming Conventions
+
+### Pattern: `[noun]-[noun/verb].md`
+
+**Good Examples:**
+- `error-handling.md`
+- `database-migrations.md`
+- `api-versioning.md`
+- `event-sourcing.md`
+
+**Avoid:**
+- Single words: `cache.md`, `auth.md`
+- Abbreviations: `db-mig.md`, `err-hdl.md`
+- Generic terms: `utilities.md`, `helpers.md`
+
+### Interface: `[service-name]-[integration-type].md`
+
+**Good Examples:**
+- `stripe-payments.md`
+- `sendgrid-webhooks.md`
+- `github-api.md`
+- `aws-s3-storage.md`
+
+**Avoid:**
+- Generic: `payment-gateway.md` (which one?)
+- Vague: `email.md` (what about email?)
+- Tech-only: `rest-api.md` (which service?)
+
+### Domain: `[entity/concept]-[aspect].md`
+
+**Good Examples:**
+- `user-permissions.md`
+- `order-workflow.md`
+- `inventory-tracking.md`
+- `pricing-rules.md`
+
+**Avoid:**
+- Implementation details: `user-table.md` (that's technical)
+- Generic: `rules.md` (which rules?)
+- Too broad: `business-logic.md` (everything?)
+
+## Update vs Create Decision Matrix
+
+| Scenario | Existing Doc | Action |
+|----------|--------------|--------|
+| New payment provider | `stripe-payments.md` exists | **Create** `paypal-payments.md` (different service) |
+| Additional caching layer | `caching-strategy.md` exists | **Update** existing (same pattern, new details) |
+| New user role type | `user-permissions.md` exists | **Update** existing (extends same rule set) |
+| Different auth method | `jwt-authentication.md` exists | **Create** `oauth-authentication.md` (different approach) |
+| API version change | `github-api.md` exists | **Update** existing (same service, evolved) |
+| New business constraint | `order-workflow.md` exists | **Update** if related, **Create** if distinct |
+
+**Guiding Principle:** Same topic/service = update. Different topic/service = create new.
+
+## Template Usage Guidelines
+
+### Pattern Template
+Use for:
+- Architectural decisions (MVC, microservices, event-driven)
+- Code organization patterns (repository, factory, singleton)
+- Data handling approaches (caching, validation, serialization)
+- Testing strategies (unit, integration, e2e)
+
+### Interface Template
+Use for:
+- Third-party API integrations
+- Webhook implementations
+- External service authentication
+- Data exchange protocols
+- Partner system integrations
+
+### Domain Template
+Use for:
+- Business rules and constraints
+- User permission systems
+- Workflow state machines
+- Validation requirements
+- Domain entity behaviors
+
+## Deduplication Techniques
+
+### Technique 1: Keyword Search
+```bash
+# Search filenames
+find docs -type f -name "*.md" | grep -i keyword
+
+# Search content
+grep -ri "search term" docs/
+```
+
+### Technique 2: Category Listing
+```bash
+# List all patterns
+ls docs/patterns/
+
+# List all interfaces
+ls docs/interfaces/
+
+# List all domain docs
+ls docs/domain/
+```
+
+### Technique 3: Content Scanning
+```bash
+# Show first 5 lines of each file
+find docs/patterns -name "*.md" -exec head -5 {} \; -print
+
+# Search for specific concept
+grep -l "authentication" docs/**/*.md
+```
+
+### Technique 4: Related Term Mapping
+
+For a new document about "caching":
+- Check for: cache, caching, cached, memoization, storage
+- Check categories: patterns (implementation), interfaces (Redis/Memcached)
+- Read related files before deciding
+
+## Merge vs Separate Guidelines
+
+### Merge When:
+- Same category and closely related topic
+- Information enhances without confusing
+- Single cohesive narrative possible
+- Total length stays under 500 lines
+
+**Example:** Merging "JWT tokens" into existing `authentication-flow.md`
+
+### Keep Separate When:
+- Different approaches to same problem
+- Distinct services/technologies
+- Would make document unfocused
+- Exceeds reasonable length
+
+**Example:** `jwt-authentication.md` and `oauth-authentication.md` as separate files
+
+## Cross-Reference Patterns
+
+### Within Same Category
+```markdown
+## Related Patterns
+- [Repository Pattern](./repository-pattern.md) - Data access layer
+- [Service Layer](./service-layer.md) - Business logic organization
+```
+
+### Across Categories
+```markdown
+## Related Documentation
+- **Domain:** [User Permissions](../domain/user-permissions.md) - Authorization rules
+- **Patterns:** [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
+- **Interfaces:** [OAuth Providers](../interfaces/oauth-providers.md) - External auth services
+```
+
+### To Specifications
+```markdown
+## Implementations
+- [User Authentication](../specs/001-user-auth/SDD.md) - Technical specification
+- [OAuth Integration](../specs/015-oauth/PRD.md) - Product requirements
+```
+
+## Version Management
+
+### When Patterns Evolve
+
+**Approach 1: Update in Place**
+- Add "Version History" section
+- Document what changed and when
+- Keep current approach primary
+
+**Approach 2: Separate Documents**
+- `authentication-v1.md` (legacy)
+- `authentication-v2.md` (current)
+- Clear migration path documented
+
+**Guideline:** Update in place unless breaking change makes old version still relevant for existing code.
+
+### Deprecation
+
+When a pattern/interface is superseded:
+
+```markdown
+# Old Authentication Pattern
+
+> **⚠️ DEPRECATED:** This pattern is no longer recommended.
+> See [New Authentication Flow](./authentication-flow.md) for current approach.
+>
+> This document is maintained for reference by legacy code in modules X, Y, Z.
+
+[Original content preserved...]
+```
+
+## Quality Standards
+
+### Completeness Checklist
+- [ ] Title clearly states what is documented
+- [ ] Context explains when/why this applies
+- [ ] Examples show real usage
+- [ ] Edge cases are covered
+- [ ] Related docs are linked
+- [ ] Code snippets use real project conventions
+
+### Clarity Checklist
+- [ ] New team member could understand it
+- [ ] Technical terms are explained
+- [ ] Assumptions are stated explicitly
+- [ ] Steps are in logical order
+- [ ] Diagrams included for complex flows (if applicable)
+
+### Maintainability Checklist
+- [ ] Searchable filename
+- [ ] Correct category
+- [ ] No duplicate content
+- [ ] Cross-references are bidirectional
+- [ ] Version history if evolved
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Creating Without Checking
+**Problem:** Duplicate documentation proliferates
+**Solution:** Always search first - multiple ways (grep, find, ls)
+
+### ❌ Mistake 2: Wrong Category
+**Problem:** Business rules in patterns/, technical details in domain/
+**Solution:** Ask "Is this about WHAT (domain) or HOW (patterns)?"
+
+### ❌ Mistake 3: Too Generic Names
+**Problem:** Can't find documentation later
+**Solution:** Full descriptive names, not abbreviations
+
+### ❌ Mistake 4: No Cross-References
+**Problem:** Related knowledge stays siloed
+**Solution:** Link liberally between related docs
+
+### ❌ Mistake 5: Template Ignored
+**Problem:** Inconsistent structure makes scanning hard
+**Solution:** Follow templates for consistency
+
+### ❌ Mistake 6: No Examples
+**Problem:** Abstract descriptions don't help
+**Solution:** Include real code snippets and scenarios
+
+## Edge Case Handling
+
+### What if Nothing Fits the Categories?
+
+**Option 1:** Expand categories (rare, think hard first)
+**Option 2:** Create `docs/architecture/` for cross-cutting concerns
+**Option 3:** Add to specification docs if feature-specific
+
+**Example:** ADRs (Architecture Decision Records) might warrant `docs/decisions/`
+
+### What if It's Too Small to Document?
+
+**Guideline:** If it's reusable or non-obvious, document it.
+
+**Too small:**
+- "We use camelCase" (coding standard, not pattern)
+- "API returns JSON" (obvious, not worth documenting)
+
+**Worth documenting:**
+- "We use optimistic locking for inventory" (non-obvious pattern)
+- "Rate limiting uses token bucket algorithm" (specific approach)
+
+### What if It's Extremely Specific?
+
+**Guideline:** Very feature-specific logic goes in specs, not shared docs.
+
+**Spec-level:**
+- `specs/023-checkout/SDD.md` - Checkout flow specifics
+
+**Shared docs:**
+- `docs/patterns/state-machines.md` - Reusable state machine pattern
+- `docs/domain/order-workflow.md` - General order rules
+
+## Performance Considerations
+
+### Keep Docs Focused
+- Single file shouldn't exceed 1000 lines
+- Split large topics into multiple focused docs
+- Use cross-references instead of duplicating
+
+### Optimize for Searchability
+- Use keywords in filename
+- Include synonyms in content
+- Add tags/topics section at top
+
+### Progressive Detail
+```markdown
+# Caching Strategy
+
+Quick overview: We use Redis for session and API response caching.
+
+## Details
+[Detailed implementation...]
+
+## Advanced Configuration
+[Complex edge cases...]
+```
+
+## Integration with Specifications
+
+### During Analysis (`/start:analyze`)
+Documentation skill captures discovered patterns:
+- Code analysis reveals patterns → Document in `docs/patterns/`
+- Business rules discovered → Document in `docs/domain/`
+- External APIs found → Document in `docs/interfaces/`
+
+### During Specification (`/start:specify`)
+- PRD/SDD references existing documentation
+- New patterns discovered → Document them
+- Specifications live in `docs/specs/`, reference shared docs
+
+### During Implementation (`/start:implement`)
+- Implementation follows documented patterns
+- Deviations discovered → Update documentation
+- New patterns emerge → Document for reuse
+
+## Automation Support
+
+### Pre-documentation Checks
+Automate the search process:
+```bash
+# Check if topic exists
+./scripts/check-doc-exists.sh "authentication"
+
+# List related docs
+./scripts/find-related-docs.sh "payment"
+```
+
+### Post-documentation Validation
+```bash
+# Verify no duplicates
+./scripts/validate-docs.sh
+
+# Check cross-references
+./scripts/check-links.sh
+```
+
+## Summary
+
+The documentation skill ensures:
+1. **No duplication** - Always check before creating
+2. **Correct categorization** - Business vs Technical vs External
+3. **Discoverability** - Descriptive names and cross-references
+4. **Consistency** - Template-based structure
+5. **Maintainability** - Clear, complete, and up-to-date
+
+When in doubt, ask:
+- Does related documentation already exist?
+- Which category fits best?
+- What name would I search for?
+- What template applies?
+- How does this connect to other knowledge?
--- a/skills/documentation/templates/domain-template.md
+++ b/skills/documentation/templates/domain-template.md
@@ -0,0 +1,325 @@
+# [Domain Concept/Entity Name]
+
+> **Category:** Domain/Business Rules
+> **Last Updated:** [Date]
+> **Status:** [Active/Under Review/Deprecated]
+
+## Overview
+
+**What:** [What this concept represents in the business]
+**Why:** [Why this exists, business justification]
+**Scope:** [Where in the application this applies]
+
+## Business Context
+
+### Background
+
+[Business context and history of this domain concept]
+
+### Stakeholders
+
+- **[Role 1]:** [How they interact with this]
+- **[Role 2]:** [How they interact with this]
+- **[Role 3]:** [How they interact with this]
+
+### Business Goals
+
+1. [Goal 1]
+2. [Goal 2]
+3. [Goal 3]
+
+## Core Concepts
+
+### [Concept 1]
+
+**Definition:** [Clear definition]
+**Examples:** [Real-world examples]
+**Constraints:** [Business constraints]
+
+### [Concept 2]
+
+**Definition:** [Clear definition]
+**Examples:** [Real-world examples]
+**Constraints:** [Business constraints]
+
+## Business Rules
+
+### Rule 1: [Rule Name]
+
+**Statement:** [Clear rule statement]
+
+**Rationale:** [Why this rule exists]
+
+**Applies to:** [Who/what this affects]
+
+**Exceptions:** [When this rule doesn't apply]
+
+**Example:**
+```
+Given: [Initial state]
+When: [Action occurs]
+Then: [Expected outcome]
+```
+
+### Rule 2: [Rule Name]
+
+[Same structure as above]
+
+## States and Transitions
+
+### State Machine (if applicable)
+
+```
+[Initial State]
+    ↓ [Event/Action]
+[Next State]
+    ↓ [Event/Action]
+[Final State]
+```
+
+### State Definitions
+
+**[State 1]**
+- **Meaning:** [What this state represents]
+- **Entry conditions:** [How entity enters this state]
+- **Exit conditions:** [How entity leaves this state]
+- **Allowed actions:** [What can happen in this state]
+
+**[State 2]**
+[Same structure]
+
+### Transition Rules
+
+**[State A] → [State B]**
+- **Trigger:** [What causes transition]
+- **Conditions:** [Required conditions]
+- **Side effects:** [What else happens]
+- **Validation:** [What must be true]
+
+## Permissions and Access Control
+
+### Who Can Do What
+
+**[Role 1]:**
+- ✅ Can: [Action 1, Action 2]
+- ❌ Cannot: [Action 3, Action 4]
+- ⚠️ Conditional: [Action 5 - under conditions]
+
+**[Role 2]:**
+[Same structure]
+
+### Permission Rules
+
+**Rule:** [Permission rule statement]
+**Logic:**
+```
+IF [condition]
+  AND [condition]
+  THEN [permission granted/denied]
+```
+
+## Validation Rules
+
+### Field Validations
+
+**[Field 1]:**
+- **Type:** [Data type]
+- **Required:** [Yes/No]
+- **Format:** [Pattern or format]
+- **Range:** [Min/max values]
+- **Business rule:** [Any business constraint]
+
+**[Field 2]:**
+[Same structure]
+
+### Cross-Field Validations
+
+**Validation 1:** [Description]
+```
+IF [field1] is [value]
+  THEN [field2] must be [constraint]
+```
+
+**Validation 2:** [Description]
+```
+[Validation logic]
+```
+
+## Workflows
+
+### Workflow 1: [Workflow Name]
+
+**Trigger:** [What initiates this workflow]
+
+**Steps:**
+1. **[Step 1]**
+   - Actor: [Who performs this]
+   - Action: [What happens]
+   - Validation: [What's checked]
+   - Outcome: [Result]
+
+2. **[Step 2]**
+   [Same structure]
+
+3. **[Step 3]**
+   [Same structure]
+
+**Success Criteria:** [What defines success]
+**Failure Scenarios:** [What can go wrong]
+
+## Calculations and Algorithms
+
+### Calculation 1: [Name]
+
+**Purpose:** [What this calculates]
+
+**Formula:**
+```
+[Mathematical or logical formula]
+```
+
+**Example:**
+```
+Given:
+  - input1 = [value]
+  - input2 = [value]
+
+Calculation:
+  result = [formula applied]
+
+Output: [result]
+```
+
+**Edge Cases:**
+- [Edge case 1 and handling]
+- [Edge case 2 and handling]
+
+## Constraints and Limits
+
+### Business Constraints
+
+1. **[Constraint 1]:** [Description and rationale]
+2. **[Constraint 2]:** [Description and rationale]
+3. **[Constraint 3]:** [Description and rationale]
+
+### System Limits
+
+- **[Limit 1]:** [Value and reason]
+- **[Limit 2]:** [Value and reason]
+- **[Limit 3]:** [Value and reason]
+
+## Edge Cases
+
+### Edge Case 1: [Scenario]
+
+**Situation:** [Describe the edge case]
+**Business Rule:** [How to handle it]
+**Example:** [Concrete example]
+
+### Edge Case 2: [Scenario]
+
+[Same structure]
+
+## Compliance and Regulations
+
+### Regulatory Requirements
+
+**[Regulation 1]:** [How it affects this domain concept]
+**[Regulation 2]:** [How it affects this domain concept]
+
+### Audit Requirements
+
+- **What to log:** [Events/changes to track]
+- **Retention:** [How long to keep records]
+- **Who can access:** [Audit log access rules]
+
+## Reporting and Analytics
+
+### Key Metrics
+
+1. **[Metric 1]:** [What it measures and why it matters]
+2. **[Metric 2]:** [What it measures and why it matters]
+3. **[Metric 3]:** [What it measures and why it matters]
+
+### Reporting Requirements
+
+- **[Report 1]:** [Purpose, frequency, audience]
+- **[Report 2]:** [Purpose, frequency, audience]
+
+## Examples and Scenarios
+
+### Scenario 1: [Happy Path]
+
+**Description:** [Common successful scenario]
+
+**Flow:**
+```
+1. [Step with data]
+2. [Step with data]
+3. [Step with outcome]
+```
+
+**Business Rules Applied:** [Which rules from above]
+
+### Scenario 2: [Error Case]
+
+**Description:** [Common error scenario]
+
+**Flow:**
+```
+1. [Step with data]
+2. [Error condition]
+3. [Error handling per business rules]
+```
+
+**Business Rules Applied:** [Which rules from above]
+
+### Scenario 3: [Edge Case]
+
+**Description:** [Unusual but valid scenario]
+
+**Flow:**
+```
+1. [Step with data]
+2. [Edge condition]
+3. [Special handling]
+```
+
+**Business Rules Applied:** [Which rules from above]
+
+## Integration Points
+
+### System Touchpoints
+
+**[System 1]:**
+- **Interaction:** [How they interact]
+- **Data shared:** [What data flows]
+- **Trigger:** [What causes interaction]
+
+**[System 2]:**
+[Same structure]
+
+## Glossary
+
+**[Term 1]:** [Definition in this context]
+**[Term 2]:** [Definition in this context]
+**[Term 3]:** [Definition in this context]
+
+## Related Documentation
+
+- **Patterns:** [Pattern Doc](../patterns/doc.md) - [Technical implementation]
+- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [External systems]
+- **Specifications:** [Spec](../specs/NNN-name/PRD.md) - [Feature requirements]
+
+## References
+
+- [Business document or policy]
+- [Industry standard or regulation]
+- [Internal decision document]
+
+## Version History
+
+| Date | Change | Reason | Author |
+|------|--------|--------|--------|
+| [Date] | Initial documentation | [Why] | [Name/Tool] |
+| [Date] | Updated [aspect] | [Why] | [Name/Tool] |
--- a/skills/documentation/templates/interface-template.md
+++ b/skills/documentation/templates/interface-template.md
@@ -0,0 +1,255 @@
+# [Service Name] Integration
+
+> **Category:** External Interface
+> **Service:** [Service Name]
+> **Last Updated:** [Date]
+> **Status:** [Active/Deprecated/Planned]
+
+## Overview
+
+**Service:** [Full service name]
+**Provider:** [Company/organization]
+**Purpose:** [What this integration accomplishes]
+**Documentation:** [Link to official API docs]
+
+## Authentication
+
+### Method
+
+[OAuth 2.0 / API Key / Basic Auth / JWT / etc.]
+
+### Credentials Management
+
+**Location:** [Where credentials are stored]
+**Environment Variables:**
+```bash
+SERVICE_API_KEY=xxx
+SERVICE_SECRET=xxx
+SERVICE_ENDPOINT=https://...
+```
+
+**Rotation Policy:** [How often credentials change]
+
+### Authentication Example
+
+```[language]
+// Example of authentication setup
+[Code snippet]
+```
+
+## API Endpoints Used
+
+### Endpoint 1: [Name]
+
+**URL:** `[METHOD] /path/to/endpoint`
+**Purpose:** [What this endpoint does]
+
+**Request:**
+```json
+{
+  "field1": "value",
+  "field2": "value"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": { }
+}
+```
+
+**Error Handling:**
+- `400`: [How we handle]
+- `401`: [How we handle]
+- `500`: [How we handle]
+
+### Endpoint 2: [Name]
+
+**URL:** `[METHOD] /path/to/endpoint`
+**Purpose:** [What this endpoint does]
+
+[Same structure as above]
+
+## Webhooks (if applicable)
+
+### Webhook 1: [Event Name]
+
+**Event Type:** `[event.type]`
+**Trigger:** [When this fires]
+**URL:** `[Your webhook endpoint]`
+
+**Payload:**
+```json
+{
+  "event": "type",
+  "data": { }
+}
+```
+
+**Signature Verification:**
+```[language]
+// How to verify webhook authenticity
+[Code snippet]
+```
+
+**Handling:**
+```[language]
+// How we process this webhook
+[Code snippet]
+```
+
+## Rate Limits
+
+- **Requests per second:** [Limit]
+- **Requests per day:** [Limit]
+- **Burst limit:** [Limit]
+
+**Handling Strategy:** [How we respect limits]
+```[language]
+// Rate limiting implementation
+[Code snippet]
+```
+
+## Data Mapping
+
+### Our Model → Service Model
+
+| Our Field | Service Field | Transformation |
+|-----------|---------------|----------------|
+| `userId` | `external_id` | String conversion |
+| `email` | `email_address` | Direct mapping |
+| `amount` | `total_cents` | Multiply by 100 |
+
+### Service Model → Our Model
+
+| Service Field | Our Field | Transformation |
+|---------------|-----------|----------------|
+| `id` | `externalId` | Direct mapping |
+| `status` | `state` | Enum mapping |
+| `created_at` | `createdAt` | ISO 8601 parse |
+
+## Error Handling
+
+### Common Errors
+
+**Error 1: [Name/Code]**
+- **Cause:** [What triggers this]
+- **Recovery:** [How we handle it]
+- **Retry:** [Yes/No, strategy]
+
+**Error 2: [Name/Code]**
+- **Cause:** [What triggers this]
+- **Recovery:** [How we handle it]
+- **Retry:** [Yes/No, strategy]
+
+### Retry Strategy
+
+```[language]
+// Exponential backoff implementation
+[Code snippet]
+```
+
+## Testing
+
+### Test Credentials
+
+**Sandbox URL:** `https://sandbox.service.com`
+**Test API Key:** `[Where to get it]`
+
+### Mock Server
+
+**Location:** `tests/mocks/[service]-mock.ts`
+**Usage:**
+```[language]
+// How to use mock in tests
+[Code snippet]
+```
+
+### Integration Tests
+
+```[language]
+// Example integration test
+[Code snippet]
+```
+
+## Monitoring
+
+### Health Checks
+
+**Endpoint:** `[Service status endpoint]`
+**Frequency:** [How often we check]
+
+### Metrics to Track
+
+- Request success rate
+- Response time (p50, p95, p99)
+- Error rate by type
+- Rate limit proximity
+
+### Alerts
+
+- **Critical:** [Conditions that trigger urgent alerts]
+- **Warning:** [Conditions that trigger warnings]
+
+## Security Considerations
+
+- [Security consideration 1]
+- [Security consideration 2]
+- [Security consideration 3]
+
+## Compliance
+
+**Data Handling:**
+- PII fields: [List]
+- Retention policy: [Duration]
+- Geographic restrictions: [Any]
+
+**Regulations:**
+- GDPR: [Compliance notes]
+- CCPA: [Compliance notes]
+- Other: [Relevant regulations]
+
+## Cost Considerations
+
+**Pricing Model:** [How service charges]
+**Cost per request:** [Estimate]
+**Monthly estimate:** [Based on usage]
+
+## Migration/Upgrade Path
+
+**Current Version:** [Version]
+**Upgrade Available:** [Yes/No, version]
+**Breaking Changes:** [List if applicable]
+
+**Migration Steps:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Related Documentation
+
+- **Patterns:** [Pattern Doc](../patterns/doc.md) - [How we use this service]
+- **Domain:** [Domain Doc](../domain/doc.md) - [Business rules related to this]
+- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Implementation details]
+
+## External Resources
+
+- [Official API documentation]
+- [Status page]
+- [Developer community/forum]
+- [SDK/library used]
+
+## Contact
+
+**Support:** [How to get help]
+**Account Manager:** [If applicable]
+**Escalation:** [Critical issue contact]
+
+## Version History
+
+| Date | Change | Author |
+|------|--------|--------|
+| [Date] | Initial integration | [Name/Tool] |
+| [Date] | Updated to v2 API | [Name/Tool] |
--- a/skills/documentation/templates/pattern-template.md
+++ b/skills/documentation/templates/pattern-template.md
@@ -0,0 +1,144 @@
+# [Pattern Name]
+
+> **Category:** Technical Pattern
+> **Last Updated:** [Date]
+> **Status:** [Active/Deprecated/Proposed]
+
+## Purpose
+
+[Brief description of what this pattern accomplishes and why it exists]
+
+## Context
+
+**When to use this pattern:**
+- [Scenario 1]
+- [Scenario 2]
+- [Scenario 3]
+
+**When NOT to use this pattern:**
+- [Anti-scenario 1]
+- [Anti-scenario 2]
+
+## Implementation
+
+### Overview
+
+[High-level description of how the pattern works]
+
+### Structure
+
+```
+[Directory structure or component organization]
+```
+
+### Key Components
+
+**[Component 1 Name]**
+- Purpose: [What it does]
+- Responsibilities: [What it handles]
+- Location: [Where to find it]
+
+**[Component 2 Name]**
+- Purpose: [What it does]
+- Responsibilities: [What it handles]
+- Location: [Where to find it]
+
+### Code Example
+
+```[language]
+// Example implementation showing the pattern in action
+[Code snippet]
+```
+
+## Usage Examples
+
+### Example 1: [Scenario Name]
+
+**Situation:** [Describe the use case]
+
+**Implementation:**
+```[language]
+[Code showing how pattern is applied]
+```
+
+**Result:** [What this achieves]
+
+### Example 2: [Scenario Name]
+
+**Situation:** [Describe the use case]
+
+**Implementation:**
+```[language]
+[Code showing how pattern is applied]
+```
+
+**Result:** [What this achieves]
+
+## Edge Cases and Gotchas
+
+### Edge Case 1: [Case Name]
+
+**Problem:** [What can go wrong]
+**Solution:** [How to handle it]
+
+### Edge Case 2: [Case Name]
+
+**Problem:** [What can go wrong]
+**Solution:** [How to handle it]
+
+## Best Practices
+
+1. **[Practice 1]:** [Description]
+2. **[Practice 2]:** [Description]
+3. **[Practice 3]:** [Description]
+
+## Anti-Patterns
+
+❌ **Don't:** [What to avoid]
+**Why:** [Reason]
+**Instead:** [Better approach]
+
+❌ **Don't:** [What to avoid]
+**Why:** [Reason]
+**Instead:** [Better approach]
+
+## Testing Strategy
+
+**How to test code using this pattern:**
+- [Testing approach 1]
+- [Testing approach 2]
+- [Testing approach 3]
+
+**Example test:**
+```[language]
+[Test code example]
+```
+
+## Performance Considerations
+
+- **[Aspect 1]:** [Performance implication]
+- **[Aspect 2]:** [Performance implication]
+- **[Aspect 3]:** [Performance implication]
+
+## Related Patterns
+
+- [Pattern Name](./pattern-file.md) - [Relationship description]
+- [Pattern Name](./pattern-file.md) - [Relationship description]
+
+## Related Documentation
+
+- **Domain:** [Domain Doc](../domain/doc.md) - [Relevance]
+- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [Relevance]
+- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Relevance]
+
+## References
+
+- [External resource 1]
+- [External resource 2]
+- [Internal decision doc or RFC]
+
+## Version History
+
+| Date | Change | Author |
+|------|--------|--------|
+| [Date] | Initial documentation | [Name/Tool] |