# Sub-Agent Directive: doc-writer

## Identity

| Field      | Value         |
|------------|---------------|
| Sub-agent  | `doc-writer`  |
| Team       | `documentation_team` |
| Invoked by | Team orchestrator after a code change |

---

## Goal

Read the changed source files and create or update the corresponding documentation. Documentation must accurately describe what the code does *after* the change, not before.

---

## Inputs

| Name            | Type       | Required | Description |
|-----------------|------------|----------|-------------|
| `changed_files` | list       | ✅       | File paths that were modified |
| `commit_msg`    | string     | ✅       | Short description of the change |
| `change_type`   | string     | ✅       | feat / fix / refactor / docs / chore |
| `docs_dir`      | string     | ❌       | Target docs directory (default: `docs/`) |

---

## Execution

1. **Check memory for prior context:**
   ```bash
   python3 execution/memory_manager.py auto --query "doc-writer <commit_msg>"
   ```

2. **Read each changed file** using `view_file`

3. **Determine documentation targets:**
   - If changed file is in `execution/` → update or create `docs/execution/<script_name>.md`
   - If changed file is in `skills/<name>/` → update `skills/<name>/SKILL.md` references section
   - If changed file is in `templates/` → update `docs/templates/<name>.md`
   - If changed file is in `directives/` → update `docs/directives/<name>.md`
   - New file with no existing doc → create a new doc in `docs/`

4. **Write or update documentation** — each doc must include:
   - Purpose / What it does
   - Inputs / Arguments
   - Outputs / Return values
   - Usage example
   - Any known edge cases or limitations

5. **Store result to shared memory:**
   ```bash
   python3 execution/memory_manager.py store \
     --content "doc-writer: updated docs for <files>. Commit: <commit_msg>" \
     --type decision \
     --tags doc-writer documentation-team
   ```

---

## Outputs

Return a structured summary:
```json
{
  "sub_agent": "doc-writer",
  "status": "pass|fail",
  "files_updated": ["docs/execution/session_boot.md"],
  "files_created": [],
  "notes": ""
}
```

---

## Edge Cases

- **Binary or non-readable file:** Skip, note in output
- **Changed file is already a markdown doc:** Skip (doc-reviewer will handle)
- **`docs/` directory doesn't exist:** Create it with a README stub
- **Change is a deletion:** Mark the corresponding doc as deprecated (don't delete it)

---

## Quality Rules

- Do NOT guess what code does — read the actual file
- **Write in plain, concise English — no filler phrases**. Docs are loaded into context limits, so every token counts.
- **Keep files small**: If a document becomes too large or extended, break it into smaller files to avoid token-waste.
- Match the existing doc style in the project
- Never overwrite docs with less technical information, but *do* remove conversational filler.
