technical-writing

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

---
name: technical-writing
description: "Internal engineering docs: specs, ADRs, architecture, runbooks, migrations, rollout plans, and maintainer guides."
allowed-tools: Read Write Edit Glob Grep
license: MIT
metadata:
  tags: technical-writing, documentation, specs, architecture, adr, runbooks, migration, developer-docs, docs-as-code
  platforms: Claude, ChatGPT, Gemini
  version: "2.1.0"
  modernization: 2026-04-13
  hardening: 2026-04-17
---

# Technical Writing

Use this skill when the deliverable is **internal technical documentation for builders and operators**.

`technical-writing` is the documentation-cluster anchor for:
- technical specs
- product requirements documents (PRDs)
- architecture docs
- ADRs / decision records
- runbooks and incident procedures
- rollout / rollback / migration guides
- developer-facing implementation or maintenance guides

## When to use this skill
- A team needs a technical spec before implementation starts
- A team needs a PRD for product/feature requirements before design or implementation
- An engineer needs an architecture document or ADR that records trade-offs and decisions
- Ops needs a runbook, rollback guide, or incident response procedure
- A migration or rollout needs a durable written path with validation and rollback notes
- A developer-facing internal guide needs to explain how a system works and how to work on it safely

## When not to use this skill

The lane is *internal* documentation. Say so and hand back when the real job is:

- **Published API, SDK, OpenAPI or developer-portal content** — an external
  reference surface with its own versioning and consumers.
- **End-user onboarding, tutorials, FAQs or help-centre flows** — the audience
  is a customer, not a builder or operator.
- **Release notes, `CHANGELOG.md` or customer-facing migration announcements.**
- **Slides, decks or roadmap presentations.**
- **Product positioning, launch copy or GTM messaging.**
- **Deciding the feature or API itself**, which has to happen before the
  document describing it can be written.

These boundaries are stated as *work*, not as skill names, so they stay true
whichever documentation skills happen to be installed. Name a specific skill
only if one is actually available in the current session.

## Reference map

Load on demand; do not read all of these up front.

| File | Use it for |
| --- | --- |
| `references/document-modes-and-boundaries.md` | Choosing the primary mode and deciding what is out of scope |
| `references/mode-structures.md` | The smallest fitting section layout for the chosen mode |
| `references/prd.md` | PRD-specific structure: personas, stories, acceptance criteria, metrics |
| `references/quality-checklists.md` | The Step 7 quality check in full |
| `references/docs-as-code-and-maintenance.md` | Repo-friendly conventions and long-term doc maintenance |

## Instructions

### Step 1: Classify one primary mode
Normalize the request into one primary mode before drafting.

```yaml
technical_writing_mode:
  primary_mode: prd | spec | architecture | adr | runbook | migration | internal-guide
  audience: engineers | operators | mixed | unknown
  source_of_truth: repo | incident-notes | existing-doc | mixed | unknown
  lifecycle_state: draft | review | rewrite | maintenance
  docs_surface: markdown-repo | docs-site | wiki | unknown
  review_need: decision-signoff | operational-accuracy | handoff-clarity | unknown
```

Use one primary mode per run:
- `prd` → product requirement, personas, stories, acceptance criteria, success metrics, risks
- `spec` → planned change, goals, constraints, design, rollout, rollback, open questions
- `architecture` → system structure, boundaries, interfaces, trade-offs, failure modes
- `adr` → one material decision with options and rationale
- `runbook` → operate, diagnose, recover, escalate
- `migration` → move from old to new safely with validation and rollback
- `internal-guide` → implementation-facing explanation for maintainers

### S