# Using Technical Writer

> Use when writing or improving documentation - ADRs, APIs, runbooks, READMEs, architecture docs, security/compliance docs, post-mortems, register review or translation (technical/policy/government/public-facing/executive/academic), fact-checking research papers, or surgical edits on large (>=2000 line) files

- Skill: `tachyon-beep/using-technical-writer` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add tachyon-beep/using-technical-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tachyon-beep/using-technical-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tachyon-beep (https://skillmd.com/u/tachyon-beep)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tachyon-beep/using-technical-writer

---


# Using Technical Writer

## Overview

This meta-skill routes you to the right technical writing skills based on your documentation task. Load this skill when you need to create, improve, or organize documentation but aren't sure which specific writing skill to use.

**Core Principle**: Different document types and audiences require different skills. Match your situation to the appropriate skill, load only what you need.

## When to Use

Load this skill when:
- Starting any documentation task
- User mentions: "document", "write docs", "README", "API docs", "ADR", "runbook"
- Creating technical content for any audience
- Improving or reorganizing existing documentation

**Don't use for**: Non-technical writing (marketing copy, blog posts, creative content)

---

## How to Access Reference Sheets

**IMPORTANT**: All reference sheets are located in the SAME DIRECTORY as this SKILL.md file.

When this skill is loaded from:
  `skills/using-technical-writer/SKILL.md`

Reference sheets like `documentation-structure.md` are at:
  `skills/using-technical-writer/documentation-structure.md`

NOT at:
  `skills/documentation-structure.md` ← WRONG PATH

When you see a link like `[documentation-structure.md](documentation-structure.md)`, read the file from the same directory as this SKILL.md.

---

## Routing by Document Type

### Architecture Decisions (ADRs)

**Symptoms**: "Document why we chose X", "Record this architectural decision", "Explain technology choice"

**Route to**: [documentation-structure.md](documentation-structure.md)

**Key Pattern**: ADRs document Context → Decision → Consequences

**Example**: "Document why we chose PostgreSQL over MongoDB" → Load [documentation-structure.md](documentation-structure.md)

---

### API Documentation

**Symptoms**: "Document this API", "Create API reference", "Explain endpoints"

**Route to**:
1. [documentation-structure.md](documentation-structure.md) (API reference pattern)
2. [clarity-and-style.md](clarity-and-style.md) (examples, precision)

**Example**: "Document REST API for user management" → Load both skills

---

### Runbooks & Procedures

**Symptoms**: "Write deployment procedure", "Create incident runbook", "Document how to..."

**Route to**:
1. [documentation-structure.md](documentation-structure.md) (runbook pattern)
2. [clarity-and-style.md](clarity-and-style.md) (step-by-step clarity)

**Example**: "Create deployment runbook" → Load both skills

---

### README Files

**Symptoms**: "Add a README", "Quick start guide", "Installation instructions"

**For Complex Projects**:
Route to: [documentation-structure.md](documentation-structure.md) (README pattern)

**For Simple Utilities**:
Route to: **NONE** - basic technical writing sufficient

**Decision Point**: Complex (>100 lines, multiple features, deployment) vs Simple (script, single function)

---

### Security Documentation

**Symptoms**: "Document threat model", "Security controls", "Document security decisions"

**Route to (Cross-Faction)**:
1. `ordis/security-architect/documenting-threats-and-controls` (security content)
2. [documentation-structure.md](documentation-structure.md) (ADR format, organization)
3. [clarity-and-style.md](clarity-and-style.md) (explain to non-experts)

**Key Insight**: Security docs need BOTH content expertise (Ordis) AND writing skills (Muna)

**Example**: "Document authentication security decisions" → Load all three skills

---

## Routing by Audience

**Audience vs Register**: Audience (who-receives) and register (how-text-operates) are orthogonal. A document has both. Audience determines what information to include; register determines how to express it. For register-specific requests (institutional voice, policy language, writing conventions), see [Routing by Register](#routing-by-register) below.

### Developer Audience

**What They Need**: Architecture diagrams, code examples, API references, technical depth

**Route to**:
- [documentation-structure.md](documentation-structure.md) (architecture docs, API patterns)
- [diagram-conventions.md](diagram-conventions.md) (system diagrams, data flows)
- [clarity-and-style.md](clarity-and-style.md) (concrete examples, precision)

**Example**: "Write docs for internal developers" → Load all three

---

### Operator Audience

**What They Need**: Runbooks, troubleshooting, deployment procedures, configuration guides

**Route to**:
- [documentation-structure.md](documentation-structure.md) (runbook pattern)
- [clarity-and-style.md](clarity-and-style.md) (step-by-step, scannable)

**Example**: "Create SRE runbook" → Load both skills

---

### Executive Audience

**What They Need**: High-level summaries, business impact, risks, costs (minimal technical detail)

**Route to**:
- [clarity-and-style.md](clarity-and-style.md) (progressive disclosure, audience adaptation)

**Example**: "Executive summary of migration plan" → Load [clarity-and-style.md](clarity-and-style.md) only

---

### Mixed/Public Audience

**What They Need**: Progressive disclosure (quick start → advanced topics), multiple entry points

**Route to**:
- [documentation-structure.md](documentation-structure.md) (README pattern, API docs)
- [clarity-and-style.md](clarity-and-style.md) (progressive disclosure, audience adaptation)
- [diagram-conventions.md](diagram-conventions.md) (high-level overviews)

**Example**: "Public documentation for open-source project" → Load all three

---

## Routing by Register

Register routing applies AFTER audience determination. Use register routing when the user asks about institutional voice, writing conventions, or adapting a document for a specific institutional context.

**Keywords**: "register", "editorial", "policy language", "government style", "translate to [register]", "adapt for government", "public-facing version", "review style", "writing register"

**Priority rule**: Register-specific requests route to `editorial-registers` + `editorial-reviewer` agent. Generic style and audience requests ("write for executives", "make this clearer") continue to route to `clarity-and-style` as before.

### Register Review / Detection

**Symptoms**: "What register is this?", "Review the style", "Is this appropriate for government?", "Check the tone"

**Route to**:
- [editorial-registers.md](editorial-registers.md) (register definitions)
- `editorial-reviewer` agent (detect or review mode)

**Example**: "Is this policy document written in the right register?" → Load editorial-registers, use editorial-reviewer agent

---

### Register Translation

**Symptoms**: "Rewrite for public audience", "Adapt this for executives", "Translate from technical to government register"

**Route to**:
- [editorial-registers.md](editorial-registers.md) (register definitions + relationships)
- `editorial-reviewer` agent (translate mode)

**Example**: "Rewrite this technical spec for a public-facing FAQ" → Load editorial-registers, use editorial-reviewer agent in translate mode

---

### Complex Edits in Large Files

**Symptoms**: "Edit this 5000-line spec", "Rename X across this module and update all the callers", "Merge sections 4 and 5 and renumber the rest", "Refactor error handling in this 3000-line file", "Update all 30 endpoints in the API reference"

**Route to**:
- `complex-writer` agent (surgical edit with pre-work assessment)
- `complex-reviewer` agent (independent verification of the edit)

**Key Pattern**: Survey → Pre-work assessment (complexity / blast radius / risk / mitigations) → caller confirms → Plan → Edit → Verify → paired review.

**Cross-language**: The pair handles both documentation AND source code (Markdown, Python, Rust, TypeScript, Go, etc.). For language-specific *idiomatic* code review (after the edit is verified correct), prefer the language-specific reviewer (`rust-code-reviewer`, `python-code-reviewer`, etc.) — `complex-reviewer` verifies the edit landed correctly, not whether the code is idiomatic.

**Example**: "Rename all uses of `legacy_handler` in this 4000-line service module" → complex-writer produces a pre-work assessment showing 47 call sites and TOC-of-handlers update needed; caller confirms; writer applies edits; complex-reviewer verifies zero hits of the old name and all 47 sites updated correctly.

**When NOT to use**: Single-file changes <500 lines, simple typo fixes, or multi-file feature work (this pair is single-file scoped — for multi-file, use planning skills + subagent-driven-development).

---

### Fact-Checking & Verification

**Symptoms**: "Fact-check this paper", "Verify claims in this document", "Check if these citations are accurate"

**Route to**: `/fact-check <file-paths>` (slash command — this skill is token-intensive and should be invoked explicitly)

**Key Pattern**: Four-phase pipeline — extract claims, dual-verify with independent web-search agents, reconcile, output structured results + exception report

**Example**: "Fact-check my research paper at docs/paper.md" → Invoke `/fact-check docs/paper.md`

**Note**: This is an expensive operation. Only route here when the user explicitly asks for fact-checking or claim verification. Do not invoke speculatively.

---

## Cross-Faction Documentation

### Security + Documentation

**When**: Documenting threat models, security controls, classified systems, compliance

**Route to**:
- `ordis/security-architect/documenting-threats-and-controls`
- `ordis/security-architect/threat-modeling` (for threat content)
- [documentation-structure.md](documentation-structure.md) (for organization)
- [security-aware-documentation.md](security-aware-documentation.md) (if handling sensitive info)

**Example**: "Document MLS security architecture" → Load all four skills

---

### Compliance + Documentation

**When**: Audit documentation, SSP/SAR, compliance mappings

**Route to**:
- `ordis/security-architect/compliance-awareness-and-mapping` (compliance content)
- [operational-acceptance-documentation.md](operational-acceptance-documentation.md) (SSP/SAR structure)
- [documentation-structure.md](documentation-structure.md) (organization)

**Example**: "Create SOC2 compliance documentation" → Load all three skills

---

### Incident Response + Documentation

**When**: Post-mortem reports, incident runbooks, response procedures

**Route to**:
- [incident-response-documentation.md](incident-response-documentation.md) (incident-specific patterns)
- [documentation-structure.md](documentation-structure.md) (runbook pattern)
- [clarity-and-style.md](clarity-and-style.md) (clarity under pressure)

**Example**: "Write post-mortem for outage" → Load all three skills

---

## Documentation Workflow

### Standard Flow

```
1. Determine document type → Route to structure skill
2. Write content → Apply clarity/style skill
3. Add diagrams if needed → Use diagram conventions
4. Test documentation → Use documentation-testing
```

### Quick Reference

| Task | Load |
|------|------|
| "Why did we choose X?" | documentation-structure (ADR) |
| "Document API" | documentation-structure + clarity-and-style |
| "Deployment runbook" | documentation-structure + clarity-and-style |
| "README for utility" | NONE (simple) or documentation-structure (complex) |
| "Security docs" | documenting-threats + documentation-structure + clarity |
| "Developer guide" | documentation-structure + diagram-conventions + clarity |
| "Executive summary" | clarity-and-style only |
| "Fact-check paper" | `/fact-check <paths>` (slash command) |
| "Edit this large file" / "rename across this module" | complex-writer + complex-reviewer agents |

---

## When NOT to Load Documentation Skills

**Don't load skills for**:
- Simple utility README (<50 lines, single purpose, obvious usage)
- Code comments (use standard practices)
- Commit messages (use conventional commits)
- Chat/email (conversational writing)
- First drafts where you're exploring (capture ideas first, structure later)

**Example**: "Add README to hello-world script" → No special skills needed

---

## Core vs Extension Skills

### Core Skills (Universal - Any Project)

Use for **any** project:
- [documentation-structure.md](documentation-structure.md) - ADRs, APIs, runbooks, READMEs, architecture docs
- [clarity-and-style.md](clarity-and-style.md) - Active voice, concrete examples, audience adaptation
- [diagram-conventions.md](diagram-conventions.md) - System diagrams, data flows, architecture visuals
- [documentation-testing.md](documentation-testing.md) - Verify docs are accurate, complete, findable

### Extension Skills (Specialized Contexts)

Use **only** when context requires:
- [security-aware-documentation.md](security-aware-documentation.md) - Sanitizing examples with sensitive data, classification marking
- [incident-response-documentation.md](incident-response-documentation.md) - Post-mortems, incident runbooks, RCA templates
- [itil-and-governance-documentation.md](itil-and-governance-documentation.md) - ITIL processes, change management, governance frameworks
- [operational-acceptance-documentation.md](operational-acceptance-documentation.md) - SSP, SAR, POA&M for government authorization

**Decision**: If unsure whether context is "specialized", start with core skills. Specialized needs will be explicit.

---

## Common Routing Patterns

### Pattern 1: ADR for Architecture Decision

```
User: "We chose to use REST instead of GraphQL. Document this."
You: Loading [documentation-structure.md](documentation-structure.md) (ADR pattern)
```

### Pattern 2: API Documentation

```
User: "Document our user management API."
You: Loading [documentation-structure.md](documentation-structure.md) + [clarity-and-style.md](clarity-and-style.md)
```

### Pattern 3: Security Documentation (Cross-Faction)

```
User: "Document the threat model for authentication."
You: Loading ordis/security-architect/documenting-threats-and-controls +
     [documentation-structure.md](documentation-structure.md) +
     [clarity-and-style.md](clarity-and-style.md)
```

### Pattern 4: Simple README

```
User: "Add README to this backup script."
You: [Check script complexity]
     Simple utility → No skills needed
     OR
     Complex tool → Loading [documentation-structure.md](documentation-structure.md)
```

### Pattern 5: Operator Runbook

```
User: "Create runbook for database failover."
You: Loading [documentation-structure.md](documentation-structure.md) (runbook) +
     [clarity-and-style.md](clarity-and-style.md) (step-by-step clarity)
```

---

## Decision Tree

```
Starting documentation task?
├─ What type?
│  ├─ Architecture decision → documentation-structure (ADR)
│  ├─ API documentation → documentation-structure + clarity-and-style
│  ├─ Runbook/procedure → documentation-structure + clarity-and-style
│  ├─ README → Complex? documentation-structure : None
│  └─ Security/compliance → Cross-faction (Ordis + Muna)
│
├─ Who's the audience?
│  ├─ Developers → Add diagram-conventions
│  ├─ Operators → Focus on runbook patterns
│  ├─ Executives → clarity-and-style only (progressive disclosure)
│  └─ Mixed → All core skills
│
├─ What register/institutional context?
│  ├─ Policy conventions → editorial-registers + editorial-reviewer
│  ├─ Government/regulatory → editorial-registers + editorial-reviewer
│  ├─ Public-facing prose → editorial-registers + editorial-reviewer
│  ├─ Academic/research → editorial-registers + editorial-reviewer
│  ├─ Executive (register, not audience) → editorial-registers + editorial-reviewer
│  └─ Technical (default for dev docs) → No additional routing needed
│
└─ Specialized context?
   ├─ Sensitive data → ADD: security-aware-documentation
   ├─ Incident response → ADD: incident-response-documentation
   ├─ Government/compliance → ADD: operational-acceptance-documentation
   └─ None → Core skills sufficient
```

---

## Quick Reference Table

| Document Type | Primary Skill | Additional Skills | Cross-Faction? |
|---------------|---------------|-------------------|----------------|
| **ADR** | documentation-structure | clarity-and-style | No |
| **API docs** | documentation-structure | clarity-and-style | No |
| **Runbook** | documentation-structure | clarity-and-style | No |
| **README (complex)** | documentation-structure | clarity-and-style, diagram-conventions | No |
| **README (simple)** | NONE | NONE | No |
| **Security docs** | documenting-threats-and-controls | documentation-structure, clarity-and-style | **Yes (Ordis)** |
| **Compliance** | operational-acceptance-documentation | documentation-structure | **Yes (Ordis)** |
| **Developer guide** | documentation-structure | diagram-conventions, clarity-and-style | No |
| **Operator guide** | documentation-structure | clarity-and-style | No |
| **Executive summary** | clarity-and-style | NONE | No |
| **Post-mortem** | incident-response-documentation | documentation-structure, clarity-and-style | No |
| **Register review** | editorial-registers | editorial-reviewer agent | No |
| **Register translation** | editorial-registers | editorial-reviewer agent | No |

---

## Common Mistakes

### ❌ Loading All Skills for Every Task
**Wrong**: Load all 8 Muna skills for every documentation task
**Right**: Load only skills your situation needs (use decision tree)

### ❌ Missing Cross-Faction Needs
**Wrong**: Document security with only Muna skills (missing security content expertise)
**Right**: Load Ordis skills for content + Muna skills for structure/clarity

### ❌ Over-Engineering Simple Docs
**Wrong**: Load documentation-structure for 10-line README
**Right**: Simple docs don't need special skills (just write clearly)

### ❌ Not Considering Audience
**Wrong**: Same documentation for developers and executives
**Right**: Adapt content and skills based on audience needs

---

## Examples

### Example 1: Documenting Database Choice

```
User: "We decided on PostgreSQL. Document why."

Your routing:
1. Recognize: Architecture decision → ADR format
2. Load: [documentation-structure.md](documentation-structure.md)
3. Create: ADR with Context, Decision, Consequences
```

### Example 2: Security Threat Model Documentation

```
User: "Document the threat model for our API gateway."

Your routing:
1. Recognize: Security content (need Ordis) + Documentation (need Muna)
2. Load: ordis/security-architect/documenting-threats-and-controls (threats content)
3. Load: [documentation-structure.md](documentation-structure.md) (ADR for security decisions)
4. Load: [clarity-and-style.md](clarity-and-style.md) (explain to non-security team)
5. Create: Threat model doc with STRIDE analysis + mitigations + clear explanations
```

### Example 3: Simple Utility README

```
User: "Add README to this file-copy script."

Your routing:
1. Recognize: Simple utility (single function, obvious usage)
2. Decision: No special skills needed
3. Create: Basic README with usage example, no complex structure
```

---

## Summary

**This skill maps documentation tasks → specific writing skills to load.**

1. Identify document type (ADR, API, runbook, README, security)
2. Use decision tree to find applicable skills
3. Load core skills for universal needs
4. Add extension skills for specialized contexts
5. Cross-reference Ordis for security/compliance content
6. Don't load skills when not needed (simple docs)

**Meta-rule**: When in doubt about document type, start with [documentation-structure.md](documentation-structure.md) - it covers most common patterns (ADR, API, runbook, README).

---

## Technical Writer Specialist Skills Catalog

After routing, load the appropriate specialist skill for detailed guidance:

### Core Skills (Universal)

1. [documentation-structure.md](documentation-structure.md) - ADR format, API reference patterns, runbook templates, README structure, architecture documentation
2. [clarity-and-style.md](clarity-and-style.md) - Active voice, concrete examples, progressive disclosure, audience adaptation, step-by-step clarity
3. [diagram-conventions.md](diagram-conventions.md) - System diagrams, data flow visuals, architecture overviews, C4 model, consistent notation
4. [documentation-testing.md](documentation-testing.md) - Verify accuracy, completeness, findability, test examples, validate links

### Extension Skills (Specialized Contexts)

5. [security-aware-documentation.md](security-aware-documentation.md) - Sanitizing sensitive data, classification marking, redacting examples, security-conscious writing
6. [incident-response-documentation.md](incident-response-documentation.md) - Post-mortem templates, incident runbooks, RCA structure, timeline documentation
7. [itil-and-governance-documentation.md](itil-and-governance-documentation.md) - ITIL processes, change management, governance frameworks, policy documentation
8. [operational-acceptance-documentation.md](operational-acceptance-documentation.md) - SSP/SAR structure, POA&M templates, government authorization, compliance artifacts
9. [editorial-registers.md](editorial-registers.md) - Writing register definitions (technical, policy, government, public-facing, executive, academic), register relationships, custom register template

### Leaf Skills (Invoked Explicitly)

10. `fact-checking` (sibling skill) - Dual-verified fact-checking of research papers / documents. Invoked via `/fact-check <file-paths>` slash command. Token-intensive; do not invoke speculatively.