# Doc Updater Agent

> **Purpose:** Keep documentation in sync with code through automated analysis and updates.

---

## When to Use

This agent is automatically invoked when:
- Code changes affect public APIs
- New functions/classes are added
- File structure changes significantly
- The `/update-docs` command is used

You can also invoke it manually with `/update-docs` or `/update-codemaps`.

---

## Capabilities

### 1. Codemap Generation
Creates architecture documentation from code analysis:

```markdown
## Project Structure

src/
├── api/           # REST API endpoints
│   ├── users.py   # User CRUD operations
│   └── auth.py    # Authentication handlers
├── services/      # Business logic
│   └── user_service.py
└── models/        # Data models
    └── user.py
```

### 2. API Documentation
Extracts and documents public interfaces:

```markdown
## UserService

### Methods

#### `create_user(name: str, email: str) -> User`
Create a new user account.

**Parameters:**
- `name`: User's display name
- `email`: User's email address (must be unique)

**Returns:** Newly created User object

**Raises:**
- `ValidationError`: If email is invalid
- `DuplicateError`: If email already exists
```

### 3. Docstring Sync
Updates docstrings to match function signatures:

```python
# Before: outdated docstring
def process(data, threshold=0.8, validate=True):
    """Process the data."""
    ...

# After: comprehensive docstring
def process(data: pd.DataFrame, threshold: float = 0.8, validate: bool = True) -> ProcessedData:
    """Process the input data with optional validation.

    Args:
        data: Input DataFrame to process
        threshold: Quality threshold (0.0-1.0)
        validate: Whether to validate input

    Returns:
        ProcessedData with results and metadata

    Raises:
        ValidationError: If data fails validation
    """
    ...
```

### 4. README Updates
Keeps README in sync with:
- Installation instructions
- Environment variables (from `.env.example`)
- Available commands (from `package.json` / `Justfile`)
- Project structure

---

## Analysis Methods

### AST Analysis (Abstract Syntax Tree)
- Parse code to understand structure
- Extract function signatures
- Identify class hierarchies
- Map imports and dependencies

### Pattern Matching
- Detect API endpoints from decorators
- Find configuration from env reads
- Identify test fixtures

### Git History
- Track what changed recently
- Identify documentation debt
- Prioritize updates for active code

---

## Output Artifacts

### Codemaps (`docs/codemaps/`)
```
docs/codemaps/
├── overview.md      # High-level architecture
├── api.md           # API endpoint documentation
├── models.md        # Data model documentation
└── services.md      # Business logic documentation
```

### Changelogs
Automatic changelog generation from commit messages.

### Type Stubs
Generate `.pyi` files for untyped modules.

---

## Language Support

### Python
- Sphinx/Google-style docstrings
- FastAPI/Flask route documentation
- Pydantic model documentation
- Type hint extraction

### TypeScript/JavaScript
- JSDoc comment generation
- React component prop documentation
- Next.js API route documentation
- Type interface documentation

---

## Integration with Other Agents

- **Code Reviewer:** Flags missing documentation
- **Planner:** Includes documentation tasks in plans
- **Architect:** Generates ADRs for architectural decisions

---

## Commands

| Command | Description |
|---------|-------------|
| `/update-docs` | Sync documentation with current code |
| `/update-codemaps` | Regenerate architecture documentation |
| `/doc-check` | Report documentation gaps |

---

## Configuration

In project settings:

```json
{
  "docUpdater": {
    "codemapsDir": "docs/codemaps",
    "docstringStyle": "google",
    "autoSync": true,
    "excludePaths": ["tests/", "scripts/"]
  }
}
```

---

## Best Practices

1. **Doc with Code** - Update docs in same commit as code
2. **Keep it Current** - Outdated docs are worse than no docs
3. **Be Concise** - Document the why, not the what
4. **Use Examples** - Code examples are better than prose
5. **Automate** - Let the agent handle routine updates
