---
name: documentation
source: botcore
description: >
  Review and maintain project documentation for accuracy and completeness.
  Covers README, AGENTS.md, CHANGELOG, guides, and API docs.
  Uses git log for changelog verification.
version: "1.0.0"
triggers:
  - documentation
  - docs review
  - readme
  - changelog
  - agents.md
  - documentation audit
---

# Documentation

Comprehensive documentation review for AI-assisted codebases.

## When to Use

- Running documentation audits (`lush-subagent run role='documentation'`)
- Verifying README accuracy after major changes
- Updating CHANGELOG before releases
- Ensuring AGENTS.md reflects current codebase
- Reviewing guides and tutorials for accuracy

---

## Documentation Types

| File | Purpose | Review Focus |
|------|---------|--------------|
| `README.md` | Project overview | Installation, quickstart, accuracy |
| `AGENTS.md` | AI agent instructions | Tool list, conventions, commands |
| `CLAUDE.md` | Claude-specific context | Project knowledge, patterns |
| `CHANGELOG.md` | Version history | Git log alignment, completeness |
| `docs/guides/` | Tutorials | Code examples work, paths valid |
| `docs/research/` | Research notes | References current, not stale |

---

## Review Protocol

### 1. Pre-Review: Gather Context

```bash
# Get recent commit history for CHANGELOG verification
git log --oneline -20

# Find recently modified files
git diff --stat HEAD~10

# Check for TODO/FIXME in docs
grep -r "TODO\|FIXME\|WIP" docs/ README.md AGENTS.md
```

### 2. README.md Checklist

- [ ] **Project description** — Accurate, matches current state
- [ ] **Installation** — Commands work, dependencies listed
- [ ] **Quick start** — Example runs without errors
- [ ] **Usage examples** — Code snippets are current
- [ ] **Contributing** — Instructions reflect actual workflow
- [ ] **License** — Present and correct
- [ ] **Badges** — Links work, statuses accurate

### 3. AGENTS.md Checklist

- [ ] **Tool list** — All current MCP tools documented
- [ ] **Commands** — All CLI commands listed
- [ ] **Conventions** — Naming patterns accurate
- [ ] **Workflows** — Step-by-step instructions work
- [ ] **Permissions** — Any restrictions documented
- [ ] **Skills** — Lists available skills and triggers

### 4. CHANGELOG.md Checklist

**Use git log to verify accuracy:**

```bash
# Compare CHANGELOG entries against actual commits
git log --oneline --since="2026-01-01" --grep="feat\|fix\|breaking"

# Check if version tags exist
git tag -l "v*"

# Get commit count between versions
git rev-list v1.0.0..v1.1.0 --count
```

**Verify:**
- [ ] **Version numbers** — Match git tags
- [ ] **Dates** — Match release commits
- [ ] **Breaking changes** — All marked clearly
- [ ] **New features** — All `feat:` commits included
- [ ] **Bug fixes** — All `fix:` commits included
- [ ] **No phantom entries** — No changelog entries without commits

### 5. Code Examples Checklist

- [ ] **File paths** — All referenced files exist
- [ ] **Import statements** — Packages/modules exist
- [ ] **Function signatures** — Match actual code
- [ ] **Configuration** — Environment variables documented
- [ ] **Output examples** — Reflect actual command output

### 6. Cross-Reference Checklist

- [ ] **Internal links** — All `[link](path)` references resolve
- [ ] **External links** — No 404 errors (spot check)
- [ ] **Code references** — Function names, file paths exist
- [ ] **Version references** — No stale version numbers

---

## Common Issues

### Stale Documentation

| Symptom | Detection | Fix |
|---------|-----------|-----|
| Old file paths | `grep -r "src/old/"` | Update paths |
| Deprecated APIs | Search for removed functions | Update examples |
| Wrong version | Check `package.json` vs docs | Sync versions |
| Missing features | Compare AGENTS.md to code | Add documentation |

### Changelog Drift

```bash
# Find commits not in CHANGELOG
git log --oneline --since="last-release-date" | head -20
# Compare against CHANGELOG entries
```

### Installation Rot

```bash
# Test installation instructions in clean environment
docker run --rm -it python:3.12 bash -c "pip install -e . && lushbot --help"
```

---

## Output Format

```markdown
# Documentation Audit: [Project Name]

## 🔴 CRITICAL (Must Fix)
1. [Broken installation instructions, missing required docs]

## 🟡 WARNINGS (Should Fix)
1. [Stale examples, outdated references]

## 🟢 SUGGESTIONS (Nice to Have)
1. [Formatting improvements, additional examples]

## Changelog Sync Status
- Last documented version: v1.2.0
- Latest git tag: v1.2.0
- Undocumented commits since tag: 5
  - feat: Add new tool
  - fix: Handle edge case

## Summary
[Overall documentation health assessment]
```

---

## Automation Tips

### Generate Changelog Entry

```bash
# Get commits since last tag for changelog
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
```

### Find Undocumented Tools

```python
# Compare AGENTS.md tool list against actual MCP server
import re

# Extract documented tools from AGENTS.md
with open("AGENTS.md") as f:
    doc_tools = set(re.findall(r'`(lush-\w+)`', f.read()))

# Extract actual tools from mcp_server.py
with open("src/lushbot/mcp_server.py") as f:
    code_tools = set(re.findall(r'name="(lush-\w+)"', f.read()))

# Find gaps
undocumented = code_tools - doc_tools
print(f"Undocumented tools: {undocumented}")
```

### Verify Links

```bash
# Check for broken internal links (requires markdown-link-check)
npx markdown-link-check README.md AGENTS.md
```

---

## Related Files

- `.agent/roles/documentation.yaml` — Documentation audit role
- `docs/` — Project documentation directory
- `CHANGELOG.md` — Version history
