Documentation Mode

Generate documentation for: $ARGUMENTS

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

# Generate API documentation
/document "API endpoints for user service"

# Create architecture diagrams
/document "system architecture diagrams"

# Generate runbook
/document "deployment runbook for production"

# Create user guide
/document "user guide for admin dashboard"

Documentation Types

API Documentation

Format: OpenAPI 3.0 specification

openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      summary: Brief description
      parameters:
        - name: param
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
              example:
                id: "123"
                name: "Example"

Architecture Documentation

Format: C4 diagrams + ADR

Use framework-patterns skill to generate:

• Context diagram (Level 1)
• Container diagram (Level 2)
• Component diagram (Level 3)

Include Architecture Decision Records for major decisions.

Runbooks

Format: Step-by-step operational guides

# Runbook: [Operation Name]

## Purpose
[What this runbook helps with]

## Prerequisites
- Access to [system/tool]
- Permissions: [required permissions]

## Steps

### 1. Check Status
```bash
# Command to check status
curl https://api/health

Expected output: {"status": "healthy"}

2. Perform Operation

# Command with explanation
./script.sh --param value

If this fails: [Troubleshooting steps]

3. Verify Success

[How to confirm operation succeeded]

Rollback

[Steps to undo if needed]

Common Issues

• Error X: [Cause and solution]
• Error Y: [Cause and solution]

### User Guides
**Format**: Task-oriented tutorials

```markdown
# How to [Task]

## Overview
[Brief description of what user will accomplish]

## Prerequisites
- [Requirement 1]
- [Requirement 2]

## Steps

### Step 1: [Action]
[Detailed instructions with screenshots if applicable]

```python
# Example code
result = do_thing()

Expected outcome: [What user should see]

Step 2: [Next Action]

[Continue with detailed steps]

Troubleshooting

Problem: [Common issue] Solution: [How to fix]

Next Steps

[What user can do after completing this guide]

### Integration
- Auto-load: `framework-patterns` skill (C4 diagrams)
- Auto-load: `evaluation-framework` skill (documentation quality rubric)

## Required Tools

| Tool | Purpose | Required |
|------|---------|----------|
| `Read` | Analyze source code/existing docs | Yes |
| `Write` | Create documentation files | Yes |
| `Grep` | Search for code patterns to document | Optional |
| `Glob` | Find related files for context | Optional |

**Auto-Loaded Skills:**
- `framework-patterns` - C4 diagram generation
- `evaluation-framework` - Documentation quality rubric

## Best Practices

✅ **DO**:
- Include concrete examples
- Add expected outputs/outcomes
- Provide troubleshooting sections
- Use clear, simple language
- Include diagrams for architecture
- Link to related documentation

❌ **DON'T**:
- Use jargon without explanation
- Skip error cases
- Forget to update version numbers
- Omit prerequisites
- Make assumptions about user knowledge
---

## Action Policy

<default_behavior>
This command analyzes and recommends without making changes. Provides:
- Detailed analysis of current state
- Specific recommendations with justification
- Prioritized action items
- Risk assessment

User decides which recommendations to implement.
</default_behavior>

<verification>
After analysis, provide:
- Analysis completeness (all aspects covered)
- Recommendation confidence levels
- Specific examples from codebase
- Clear next steps for user
</verification>

## Success Output

When documentation mode completes:

✅ COMMAND COMPLETE: /document Type: <API|Architecture|Runbook|Guide> Topic: Format: <OpenAPI|C4|Markdown> Output: Sections: N

## Output Validation

Before completing, verify output contains:
- [ ] Document type identified (API/Architecture/Runbook/Guide)
- [ ] Correct format used (OpenAPI/C4/Markdown)
- [ ] Concrete code examples included
- [ ] Expected outputs documented
- [ ] Troubleshooting section present
- [ ] File saved to correct location
- [ ] Success summary with section count

## Completion Checklist

Before marking complete:
- [ ] Type determined
- [ ] Content analyzed
- [ ] Documentation created
- [ ] Examples included
- [ ] Troubleshooting added

## Failure Indicators

This command has FAILED if:
- ❌ No type specified
- ❌ No documentation created
- ❌ Missing examples
- ❌ Invalid format

## When NOT to Use

**Do NOT use when:**
- Documentation exists (update instead)
- Topic unclear
- Quick note (use README)

## Anti-Patterns (Avoid)

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Skip examples | Unclear usage | Add concrete examples |
| No troubleshooting | Stuck users | Add common issues |
| Jargon without explanation | Confusing | Define terms |

## Principles

This command embodies:
- **#6 Clear, Understandable** - Clear documentation
- **#3 Complete Execution** - Full doc sections
- **#9 Based on Facts** - Based on actual code

**Full Standard:** [CODITECT-STANDARD-AUTOMATION.md](pathname://coditect-core-standards/CODITECT-STANDARD-AUTOMATION.md)