# Documentation Writer Agent

**Agent**: `docs-writer`
**Tracking Prefix**: `AUTO-DOCS`
**Reporting Interval**: Every 10 cycles (~3.3 hours)

The `docs-writer` agent is a continuous documentation monitoring and generation
service.  It runs in an isolated clone of the repository, polls for merged code
and milestone completions, and keeps project documentation current without human
intervention.

---

## Responsibilities

| Task | Output |
|------|--------|
| README updates | `README.md` — new features appended to Highlights |
| API documentation | `docs/api/` — one file per module |
| Architecture overview | `docs/architecture.md` — component map, data flow |
| Changelog entries | `CHANGELOG.md` — Keep-a-Changelog format |
| Module documentation | `docs/modules/` — per-module usage guides |

The agent **extends** existing documentation; it never overwrites content that
is already accurate.

---

## Monitoring Loop

```
last_sha = master HEAD
cycle = 0

LOOP:
    cycle += 1

    # Create tracking issue every 10 cycles
    if cycle % 10 == 0:
        automation-tracking-manager: CREATE_TRACKING_ISSUE
          agent_prefix: AUTO-DOCS
          tracking_type: Documentation Report

    # Pull latest code
    git fetch && git reset --hard origin/master
    current_sha = HEAD

    if current_sha == last_sha and cycle > 1:
        sleep 20 minutes
        continue

    last_sha = current_sha

    # Check for documentation-worthy changes
    query recently merged PRs
    check milestone completions
    run_docs_update() if changes found

    sleep 20 minutes
```

The agent uses `sleep 1200` (20-minute intervals) between cycles and never
voluntarily exits.

---

## Automation Tracking

The `docs-writer` participates in the [Automation Tracking System](automation-tracking.md)
via the `automation-tracking-manager` subagent.

### Tracking Issue Format

```
Title: [AUTO-DOCS] Documentation Report (Cycle N)
```

**Default label** (applied automatically by the manager):

| Label | Purpose |
|-------|---------|
| `Automation Tracking` | Enables system-watchdog health monitoring |

Additional labels (for example `Type/Automation`, `State/In Progress`, or
`Priority/Medium`) can be added manually when teams need extra filtering, but
they are optional and not applied by the manager today.

### Cleanup Protocol

The `automation-tracking-manager` handles all cleanup:

1. Finds the previous open `[AUTO-DOCS] Documentation Report (Cycle N)` issue
2. Posts a closure comment
3. Closes the issue
4. Creates the new tracking issue with the `Automation Tracking` label

Announcement issues (`[AUTO-DOCS] Announce: …`) are **never** deleted.

---

## Documentation Standards

All documentation produced by this agent follows the project's
[CONTRIBUTING.md](../../CONTRIBUTING.md) documentation standards:

- **Continuous documentation** — updated alongside code, not after the fact
- **Single documentation surface** — one canonical location per doc type
- **Traceability** — logical references, not line numbers
- **MkDocs-compatible** — all files are valid MkDocs Markdown

---

## Clone Isolation

The agent always works in an isolated clone at `/tmp/docs-writer-<instance-id>/`.
It never modifies files in `/app` or any shared directory.  The clone is
deleted on exit (including on error).

Push conflicts are resolved with `git pull --rebase origin master && git push`.
After five consecutive push failures the clone is deleted and re-cloned fresh.

Since `master` is a protected branch, all documentation changes are submitted
as pull requests from a feature branch.

---

## Related Documentation

- [Automation Tracking System](automation-tracking.md) — full tracking system reference
- [System Watchdog](system-watchdog.md) — health monitoring that watches this agent
- [Quality Automation](quality-automation.md) — quality gate context