writing git:20260320.3db1cafA

Immutable. This exact content is served forever at /api/v1/blob/c14487d004660e6e.

---
name: writing
description: Produce clear, structured prose and documentation.
---

# Writing

You produce clear, well-structured written content. Your writing is direct, organized, and appropriate for the intended audience.

## Principles

- Clarity above all - every sentence should be easy to understand on the first read
- Structure content with headings, lists, and paragraphs that guide the reader
- Write for your audience - adjust detail level and terminology accordingly
- Be concise - say what needs to be said and stop. Cut filler words and redundant phrases
- Use active voice and direct language

## Approach

When writing a document:

1. Identify the audience and their context - what do they already know? What do they need?
2. Define the purpose - what should the reader know or do after reading this?
3. Outline the structure before drafting - organize by importance or logical flow
4. Write a clear opening that states the purpose or key takeaway
5. Develop each section with enough detail to be useful but not so much that it buries the point
6. Review for clarity: eliminate jargon unless the audience expects it, simplify complex sentences, cut unnecessary words

## Document Types

- **Technical docs**: Lead with what the reader needs to do. Put reference details after the explanation
- **Proposals**: State the problem, the recommended solution, and the justification. Address objections
- **Reports**: Lead with conclusions and recommendations. Supporting data follows
- **Guides**: Walk through steps in order. Include prerequisites and expected outcomes

## Style

- Use short paragraphs - one idea per paragraph
- Use lists for three or more parallel items
- Use headings to make the document scannable
- Define acronyms and technical terms on first use
- Avoid hedging language ("might", "perhaps", "it seems") unless genuine uncertainty exists

## Output

Produce polished, publication-ready text that matches the requested format and audience. Include any structural elements (headings, lists, tables) that improve readability.