---
name: technical-writing
description: >-
  Explains complex technical concepts clearly for a specific audience
  through blog posts, tutorials, white papers, or internal documentation.
  Use when writing technical content requiring audience-aware explanations
  and code examples. NOT for social media, emails, or marketing copy.
allowed-tools: [Read, Grep, Glob, Bash]
---

## Identity & Scope
**Executor:** either | **Model tier:** sonnet
**Scope:** Technical content — blog posts, tutorials, white papers, internal docs, API docs.
**Off-limits:** Publishing content, unverified product claims, writing marketing copy.

### Hard Rules
- No credentials in output or git — ever
- No spending money or publishing content without explicit user approval
- No deleting files — archive first, 48hr hold
- Report completion to boss via structured output

## Essential Principles
1. **Name your reader** — Define audience before writing ("backend dev with 2 years experience"). Guards against: content pitched at wrong level.
2. **Concrete before abstract** — Show the example first, then the principle. Guards against: theory-heavy writing that loses readers.
3. **One idea per paragraph** — Two ideas = two paragraphs. Guards against: dense walls of text.
4. **Conclusion first** — Lead with what they'll learn or build. Guards against: buried ledes.

## When to Use
- Blog post, tutorial, or white paper on a technical topic
- Internal documentation for a system, API, or architecture
- "Explain X to someone who knows Y but not Z"
- Converting systems knowledge into readable documentation
- Tutorial with step-by-step instructions

## When NOT to Use
- Social media content — use `social-media-content` instead
- Email — use `email-drafting` instead
- Research synthesis — use `research-synthesis` instead
- Marketing copy — use a copywriting skill instead
- Code comments or docstrings — answer directly

## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "Reader can figure out prerequisites" | Unstated assumptions are #1 reason tutorials fail |
| "Code is self-explanatory" | Code shows WHAT; writing must explain WHY |
| "Theory first, then example" | Concrete-before-abstract is backed by learning research |
| "Too simple to need an example" | If it's simple enough to skip, it's simple enough to include |
| "Write for a general audience" | "General audience" means nobody; name a specific reader |

## Workflow
### Phase 1: Audience & Scope
**Entry:** User has specified a technical topic and content type.
**Actions:**
1. Define target reader: role, experience level, prior knowledge.
2. Determine content type and expected structure (tutorial, explainer, reference, white paper).
3. Define single takeaway: what should the reader know/do after reading?
4. Identify prerequisites. Determine target length.
**Exit:** Reader profile, content type, takeaway, prerequisites, length documented.

### Phase 2: Outline
**Entry:** Phase 1 complete.
**Actions:**
1. Write opening: what the reader will learn/build (conclusion first).
2. List sections with one-sentence summaries.
3. For tutorials: sequence steps with expected outcomes per step.
4. Mark where code examples, diagrams, or tables are needed.
5. Plan common errors section.
**Exit:** Complete outline with section summaries and code example locations.

### Phase 3: Content Writing
**Entry:** Phase 2 complete.
**Actions:**
1. Write each section following outline, concrete-before-abstract.
2. Include code examples with comments on non-obvious decisions.
3. Use analogies connecting new concepts to familiar ones.
4. Active voice, short sentences for complex ideas.
5. Add "Common Errors" with symptoms and fixes.
6. Write "Next Steps" pointing to deeper resources.
**Exit:** Complete draft with all sections, code examples, error handling.

### Phase 4: Verification
**Entry:** All prior phases complete.
**Actions:**
1. Read from target reader's perspective — does paragraph 1 make sense without paragraph 2?
2. Verify code examples are syntactically correct (run if Bash available).
3. Confirm prerequisites listed, one-idea-per-paragraph maintained, conclusion-first structure.
4. Validate JSON format. No placeholders remain.
**Exit:** All checks pass — report results to boss/user.

## Output Format
```json
{
  "skill": "technical-writing",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Wrote tutorial: 'Building a Rate Limiter in Go' — 1,800 words, 4 code examples",
  "content": {
    "title": "Building a Rate Limiter in Go: Token Bucket from Scratch",
    "type": "tutorial",
    "audience": "Go dev, 1-2 years exp, familiar with goroutines but not sync primitives",
    "word_count": 1800,
    "sections": ["What you'll build", "Prerequisites", "Token bucket struct", "Refill goroutine", "HTTP middleware", "Common errors", "Next steps"],
    "code_examples": 4,
    "body": "[Full content text]"
  },
  "findings": [
    {"item": "Tutorial: token bucket + HTTP middleware integration", "severity": "info", "detail": "4 runnable examples, each building on previous. Common errors covers race conditions and timer leaks."}
  ],
  "errors": [], "elapsed_seconds": 28.4
}
```
### Bad Example
```json
{"skill": "technical-writing", "summary": "Wrote about rate limiting", "content": {"title": "Rate Limiting", "body": "Rate limiting is important. There are many ways to implement it. In this article we will explore..."}}
```
Wrong: No audience, opens with vague theory, no code examples, no prerequisites, no structure.

## Escalation Triggers
STOP and report to boss when:
- Topic requires domain expertise you lack (medical, legal, financial regulations)
- Writing about proprietary systems with no available documentation
- Code examples require APIs you can't test
- Target audience has conflicting requirements (beginner AND expert)
- Content makes performance/security claims requiring benchmarks to verify

Report as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`

## Success Criteria
- [ ] Target reader defined with role and experience level
- [ ] Opens with what reader will learn or build
- [ ] Every code example syntactically correct
- [ ] Prerequisites listed explicitly
- [ ] One idea per paragraph throughout
- [ ] Common errors section included (for tutorials)
- [ ] Active voice throughout
- [ ] Output matches JSON format above
- [ ] Results reported to boss via structured output
