oimiragieo Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.
Step 1: Identify Documentation Type
Determine documentation type:
- API Documentation: Endpoint references
- Developer Guide: Setup and usage
- Architecture Docs: System overview
- User Manual: Feature guides
Step 2: Extract Information
Gather documentation content:
- Read code and comments
- Analyze API endpoints
- Extract examples
- Understand architecture
Step 3: Generate Documentation
Create documentation:
- Follow documentation templates
- Include examples
- Add troubleshooting
- Create clear structure
Step 4: Validate Documentation
Validate quality:
- Check completeness
- Verify examples work
- Ensure clarity
- Validate links
Integration with Developer Agent:
- Generates API documentation
- Creates inline documentation
- Updates docs with code changes
- Extract from Code: Use code as source of truth
- Include Examples: Provide working examples
- Keep Updated: Sync docs with code
- Clear Structure: Organize logically
- User-Focused: Write for users, not system
# Users API
## Endpoints
### GET /api/users
List all users with pagination.
**Query Parameters:**
- `page` (number): Page number (default: 1)
- `limit` (number): Items per page (default: 10)
**Response:**
```json
{
"data": [
{
"id": "uuid",
"email": "user@example.com",
"name": "User Name"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100
}
}
```
Example:
curl -X GET "http://localhost:3000/api/users?page=1&limit=10"
</formatting_example>
<formatting_example>
**Developer Guide**
```markdown
# Developer Guide
## Getting Started
### Prerequisites
- Node.js 18+
- pnpm 8+
### Installation
```bash
pnpm install
Development
pnpm dev
Architecture
[Architecture overview]
Development Workflow
[Development process]
</formatting_example>
</examples>
<examples>
<usage_example>
**Example Commands**:
Generate API documentation
Generate API documentation for app/api/users
Generate developer guide
Generate developer guide for this project
Generate architecture docs
Generate architecture documentation
Generate OpenAPI spec
Generate OpenAPI specification from API routes
</usage_example>
</examples>
## Iron Laws
1. **ALWAYS** extract documentation from code as the source of truth — never write documentation that describes how you wish the code worked rather than how it actually works.
2. **NEVER** publish documentation with non-runnable examples — every code example must be copy-paste ready and verified to work before the documentation is written.
3. **ALWAYS** structure documentation with the progressive disclosure pattern (Setup → Quick Start → Reference → Troubleshooting) — readers need orientation before details.
4. **NEVER** document internal implementation details that consumers don't need to know — documentation of private internals creates false contracts and maintenance burden.
5. **ALWAYS** regenerate documentation when the code it describes changes — stale documentation is worse than no documentation because it actively misleads users.
## Anti-Patterns
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| No working code examples | Users can't understand how to use the API without runnable examples | Include minimal copy-paste examples verified to work for every public API |
| Aspirational documentation (describes intended behavior) | Creates false contracts; users file bugs when docs don't match code | Read the actual implementation first; document only observed behavior |
| Documenting private/internal APIs | Creates implicit dependencies; refactoring breaks "documented" behavior | Only document public APIs; mark internal functions with `@internal` if needed |
| Monolithic reference dumps without Quick Start | Users abandon before finding what they need | Always include a Quick Start section with the simplest possible working example |
| Documentation in a separate PR from code change | Docs drift immediately; often abandoned | Require documentation updates in the same PR as API changes |
## Memory Protocol (MANDATORY)
**Before starting:**
Read `.claude/context/memory/learnings.md`
**After completing:**
- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`
> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.