technical-writer

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: technical-writer
description: >
  Write or review technical documents, including READMEs, system overviews, and
  skill files.
allowed-tools: Agent, Read, Write, Bash, Glob
---

## Mode Selection

| Mode             | When to use                                                 |
| ---------------- | ----------------------------------------------------------- |
| **readme**       | Write or rewrite a project-level README                     |
| **overview**     | Write a technical overview of a system, subsystem, or topic |
| **skill-writer** | Write a new skill file or review and polish an existing one |
| **other**        | Write any other technical document                          |

If the user specifies a mode, use it. Otherwise, infer from the request:

- "write a README" / "document this project" / "generate a README" → `readme`
- "write a technical overview" / "document this system" → `overview`
- "write a skill" / "create a skill" / "new skill" → `skill-writer`

If no other mode matches, use `other` as the default.

## Variable Setup

Set these path variables once and use throughout:

```
MODE={{detected-mode}}
MODE_DIR=references/modes/$MODE
WORK_DIR={{session working directory}}
```

Pass `$WORK_DIR` and `$MODE_DIR` to all sub-agents.

Read this skill first, then read `$MODE_DIR/instructions.md` and apply any
mode-specific overrides before running the workflow.

### Review Variant

When the user provides an existing document to review, ask which variant to run
unless context makes the intended variant clear. Use these as default variants:

- **Validity** — run Discovery and Research, then review the existing document
  directly without a writer pass
- **Revision** — edit or rewrite an existing document from user feedback, then
  run review
- **Clarity** — run reviewer directly on existing document without codebase
  research

Mode instructions may override variant names and phase entry behavior.

| Phase        | Write | Validity | Revision | Clarity |
| ------------ | ----- | -------- | -------- | ------- |
| 1: Discovery | Run   | Run      | Skip     | Skip    |
| 2: Research  | Run   | Run      | Skip     | Skip    |
| 3: Write     | Run   | Skip     | Run      | Skip    |
| 4: Review    | Run   | Run      | Run      | Run     |

---

## Your Role

Act as the workflow manager. Launch sub-agents and confirm that each phase has
produced non-empty output. Route, delegate, and verify. Do not read or
synthesize file contents.

Read only these four files:

1. `$MODE_DIR/instructions.md` — workflow configuration
2. A user-provided existing document — when the user supplies one for review or
   as a baseline
3. `$WORK_DIR/discovery.md` — researcher scope definition
4. `$WORK_DIR/review.md` — revision decision

Pass all other files — role files, rule files, templates, examples, checklists,
research outputs, and drafts — as file paths to sub-agents. Do not open those
files.

## Workflow: Four Phases, Multiple Sub-Agents

Use a separate, isolated **general-purpose** sub-agent for each phase. Do not
use Explore agents — all phases write output files to `$WORK_DIR` and require
Write access.

If `$MODE_DIR/instructions.md` defines phase behavior (for example, Pre-flight
steps or mode-specific discovery/research flow), follow it.

---

### Phase 1: Discovery

Run a **discovery sub-agent** to enumerate the project's components,
integrations, and existing documentation.

Launch the sub-agent with:

- `$WORK_DIR` — the output directory path
- Instructions to scan the codebase for application modules, external system
  references, and existing documentation files

The discovery sub-agent writes its output to `$WORK_DIR/discovery.md` with four
sections:

- **Modules & Services** — all application modules, services, or major
  components. One line each, no descriptions.
- **External Systems** — all external systems referenced in config, code, or
  documentation. One line each, no descriptions.
- **Processes & Workflows** —