From documenter
Document a system component by extracting architecture, design principles, and practical applications
npx claudepluginhub revans/buster-marketplace --plugin documentersonnet# Document System Component
You are documenting a system component following the **system-documentation-skill** methodology.
## Your Task
Create comprehensive documentation for: **{component_name}**
Output location: {output_path | or default to `docs/<component-slug>.md`}
## Process
### Phase 1: Discovery (Thorough Research)
**CRITICAL**: Do NOT start writing until you have thoroughly researched the component.
1. **Find all relevant files**:
2. **Read implementation files completely**:
- Read main implementation files (don't skim)
- Read related configuration files
- R...You are documenting a system component following the system-documentation-skill methodology.
Create comprehensive documentation for: {component_name}
Output location: {output_path | or default to docs/<component-slug>.md}
CRITICAL: Do NOT start writing until you have thoroughly researched the component.
Find all relevant files:
# Search for files related to the component
Glob pattern="**/*{component_name}*"
Read implementation files completely:
Search for usage examples:
# Find where this component is used
Grep pattern="{component_name}" output_mode="files_with_matches"
Map relationships:
Check git history (if helpful):
# See evolution of key files
git log --oneline -- path/to/component/files
Before writing, answer these questions:
What problem does this solve?
What are the design principles?
How is it actually used?
What makes this design good?
Use the system-documentation-skill template:
# [Component Name]
**Purpose**: [1-2 sentence explanation]
**Version**: [If applicable]
**Last Updated**: [Today's date]
---
## Table of Contents
1. [Overview](#overview)
2. [The Core Problem This Solves](#the-core-problem-this-solves)
3. [Architecture of [Component]](#architecture)
4. [Design Principles](#design-principles)
5. [Practical Applications](#practical-applications)
6. [Implementation Details](#implementation-details)
7. [Future Enhancements](#future-enhancements)
---
## Overview
[3-4 paragraphs explaining what this is and why it matters]
**Key capabilities**:
- [Capability 1]
- [Capability 2]
- [Capability 3]
**Creates both**:
- [Benefit 1]: [Explanation]
- [Benefit 2]: [Explanation]
---
## The Core Problem This Solves
[Traditional approach and its limitations]
### Problem 1: [Name]
- **What exists**: "[Current state]"
- **What we need**: "[Desired state]"
- **Pain points**: [Specific consequences]
### Problem 2: [Name]
[Continue for 4-6 problems]
**The Solution**: [1-2 sentences summarizing how this solves these problems]
---
## Architecture of [Component]
### [Schema/Structure name if applicable]
[Describe structure, show code/JSON examples]
### [Sub-component 1]
[Details, examples]
### [Sub-component 2]
[Details, examples]
---
## Design Principles
### Design Principle 1: [Name]
**Why**: [Rationale]
**Example**: [Code or scenario]
**Benefit**: [What this enables]
### Design Principle 2: [Name]
[Continue for 6-8 principles]
---
## Practical Applications
### 1. [Use Case Name]
**Problem**: "[User question or scenario]"
**Solution**: [How to use this]
```[language]
# Real code example showing usage
Value: [What this enables]
[Continue for 6-7 use cases]
[Deep dive into how it works]
[Technical details, data structures, algorithms]
[Technical details, data structures, algorithms]
Goal: [What this will enable]
Implementation:
# Code sketch showing how this would work
Value: [Why this matters]
[Continue for 5-7 enhancements]
[Summary paragraph about the component's role]
This component enables:
[Final statement about value and importance]
path/to/doc.md - [Brief description]path/to/doc.md - [Brief description]
## Quality Checklist
Before finishing, ensure your documentation:
- [ ] **Starts with problems** - Explains what pain this eliminates
- [ ] **Shows design rationale** - Explains WHY decisions were made
- [ ] **Includes real examples** - Uses actual code from the codebase
- [ ] **Discusses tradeoffs** - Mentions alternatives and why rejected
- [ ] **Explains failure modes** - What breaks and how to recover
- [ ] **Links related docs** - Points to relevant files/resources
- [ ] **Uses consistent structure** - Follows the template
## Anti-patterns to Avoid
❌ **Don't just describe what code does** ("This function takes X and returns Y")
✅ **Explain why it exists and what problem it solves**
❌ **Don't write abstract descriptions without examples**
✅ **Show real code and usage patterns**
❌ **Don't assume reader knows context**
✅ **Explain jargon and provide background**
❌ **Don't skip the "why"**
✅ **Always explain design rationale and tradeoffs**
---
## Example: orchestration.json Documentation
Reference: `docs/ORCHESTRATION_AND_LEARNING_SYSTEM.md`
**What makes it good**:
- Starts with 6 specific problems and pain points
- Explains 8 design principles with examples and rationale
- Provides 7 practical applications with real code
- Shows actual schemas and implementation patterns
- Discusses future enhancements with code sketches
- Uses consistent structure throughout
---
## Output
Create the documentation file at: **{output_path}** (or default location)
**After writing**:
1. Tell user where documentation was created
2. Summarize what was documented
3. Highlight 2-3 most interesting insights discovered
4. Suggest related components that might benefit from documentation