technical-writing

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: technical-writing
description: >
  Write internal technical documentation for engineers and operators: technical
  specs, architecture docs, ADRs, runbooks, migration plans, and
  developer-facing implementation guides. Use when the main job is capturing a
  technical decision, system boundary, operating procedure, or rollout path for
  builders and maintainers. Triggers on: tech spec, design doc, architecture
  doc, ADR, runbook, migration guide, implementation guide, rollout doc,
  operational guide, and internal technical writing. End-user onboarding guides, tutorials, FAQs, and
  help-center flows belong here too. Route API portals to
  `api-documentation`, release
  notes to `changelog-maintenance`, decks to `presentation-builder`, and GTM
  messaging to `marketing-automation`.
allowed-tools: Read Write Edit Glob Grep
compatibility: >
  Best for repositories and docs-as-code workflows where the output lives in
  Markdown, ADR directories, architecture docs, runbooks, migration docs, or
  internal knowledge bases.
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
- architecture docs
- ADRs / decision records
- runbooks and incident procedures
- rollout / rollback / migration guides
- developer-facing implementation or maintenance guides

Read these support docs before choosing the mode or boundary:
- [references/document-modes-and-boundaries.md](references/document-modes-and-boundaries.md)
- [references/mode-structures.md](references/mode-structures.md)
- [references/quality-checklists.md](references/quality-checklists.md)
- [references/docs-as-code-and-maintenance.md](references/docs-as-code-and-maintenance.md)

## When to use this skill
- A team needs a technical spec before implementation starts
- 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
- **Published API docs, SDK docs, OpenAPI reference, developer portal content** → `api-documentation`
- **Release notes, `CHANGELOG.md`, migration announcements for customers/devs** → `changelog-maintenance`
- **Slides, pitch decks, roadmap presentations, architecture demos** → `presentation-builder`
- **Product positioning, launch copy, GTM messaging, marketing automation** → `marketing-automation`
- **The main job is deciding the feature or API itself before writing the doc** → `task-planning`, `api-design`, or the relevant planning skill first

## Instructions

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

```yaml
technical_writing_mode:
  primary_mode: 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:
- `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