technical-writer

Files (20)

• SKILL.md
• checklist.md · references/modes/other/
• instructions.md · references/modes/other/
• checklist.md · references/modes/overview/
• examples.md · references/modes/overview/
• instructions.md · references/modes/overview/
• template.md · references/modes/overview/
• checklist.md · references/modes/readme/
• examples.md · references/modes/readme/
• instructions.md · references/modes/readme/
• template.md · references/modes/readme/
• checklist.md · references/modes/skill-writer/
• examples.md · references/modes/skill-writer/
• instructions.md · references/modes/skill-writer/
• template.md · references/modes/skill-writer/
• researcher.md · references/roles/
• reviewer.md · references/roles/
• writer.md · references/roles/
• abstraction-rules.md · references/rules/
• style-guide.md · references/rules/

SKILL.md (first lines)

## 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** — named processes, jobs, pipelines, or multi-step
  operations the system performs. One line each: process name and trigger (e.g.,
  "Order Provisioning — triggered by incoming order event", "Nightly
  Reconciliation — scheduled daily"). Include both primary and background
  processes.
- **Documentation & Specs** — any existing documentation files worth consulting:
  READMEs, OpenAPI/WSDL specs, architecture docs, wikis, significant
  configuration files. One line each with relative path.

Read `$WORK_DIR/discovery.md` and use it to define researcher scopes in Phase 2.

---

### Phase 2: Research

Read the Research Topics section of `$MODE_DIR/instructions.md` to determine
researcher assignments. Each assignment includes a topic name, description, and

From cederberg/incubator, MIT.

More from cederberg/incubator