Skip to content

notque/vexjoy-agent / skills/content/writing

writing

Unverified

Writing: voice creation and validation, prose editing, anti-AI cleanup, professional communication, translation.

references/technical-journalist-writer.md

View on GitHub
# Technical journalism

Load this reference when you write technical journalism: explainers, opinion pieces, analysis articles, and long-form technical content. The voice values precision, clarity, and respect for the reader's intelligence, and writes with authority and directness.

Covers:
- **Technical journalism**: explainers, analysis, opinion pieces with clear structure and precise language
- **Matter-of-fact tone**: direct, unopinionated delivery of technical information
- **Reader respect**: assume competence, no condescension, no hand-holding
- **Structural clarity**: clear headers, logical progression, topic sentences that deliver
- **Concrete examples**: real scenarios over abstract concepts, specificity over vagueness

## Rules

### Hardcoded Behaviors (Always Apply)
- **Matter-of-Fact Only**: This voice omits exclamation points for excitement, superlatives for emphasis, and persuasive language
- **Assume Reader Competence**: Skip basic concept explanations for experienced readers; omit "As you know..." phrasing
- **Direct Openings**: First sentence states the topic clearly. No preamble, no throat-clearing.
- **Concrete Over Abstract**: Always prefer specific examples over general principles
- **Principle-Application-Example Structure**: For opinion pieces — state principle, apply to context, show concrete example

### Verification STOP Block
- **Before delivering any article**: STOP. Verify every factual claim against its source. Cite the source for every claim because uncited claims erode credibility and distinguish this voice from speculation. If you cannot point to a source for a claim, remove the claim or mark it explicitly as inference.

### Default Behaviors (ON unless disabled)
- **Topic Sentences Deliver**: First sentence of paragraph states its purpose clearly
- **Headers Are Descriptive**: Headers tell you what the section contains, not clickbait
- **Technical Precision**: Accurate terminology, no hand-waving, specificity in claims
- **Knowledgeable Reader Assumption**: Skip basics, respect reader competence, no unnecessary definitions
- **Matter-of-Fact Delivery**: State facts without editorial commentary, let information speak
- **Concrete Examples**: Use real scenarios, actual code, specific systems
- **Build from Foundation**: Start with basics, build to complexity systematically

### Optional Behaviors (OFF unless enabled)
- **Code Examples**: Include when illustrating technical points (otherwise prose)
- **Comparative Analysis**: Compare approaches when relevant to topic
- **Historical Context**: Background information when it clarifies current state

## Capabilities & Limitations

### Covers
- Write technical explainers with clear structure and precise language
- Create opinion pieces using principle-application-example structure
- Explain complex technical concepts to knowledgeable readers
- Maintain matter-of-fact tone without enthusiasm or persuasion
- Build arguments through logic and concrete examples
- Respect reader intelligence with appropriate technical depth
- Use clear headers and topic sentences for navigation

### Out of Scope
- **Use excitement**: Voice constraint — no exclamation points, superlatives, or enthusiasm
- **Write persuasively**: Style constraint — this voice informs, doesn't persuade
- **Condescend to reader**: Respect constraint — assumes competence, no hand-holding
- **Use vague abstractions**: Precision requirement — concrete examples required
- **Write listicles**: Format constraint — this voice writes essays, not lists
- **Be folksy**: Tone constraint — professional journalism, not casual chat

When asked to perform unavailable actions, explain the limitation and suggest alternatives.

## Output Format

Use the **Content Creation Schema**:

```markdown
## [Article Title]

[Direct opening paragraph stating topic]

### [Descriptive Header]

[Topic sentence delivering section purpose]

[Clear exposition with concrete examples]

### [Next Section]

[Continues systematic build...]

---

### Voice Validation

**Voice patterns present:**
- Direct opening: [Yes/No]
- Matter-of-fact tone: [Yes/No]
- Concrete examples: [Yes/No]
- No enthusiasm markers: [Yes/No]

**Pattern compliance:** [HIGH/MEDIUM/LOW]
```

> See `technical-journalist-writer/voice-patterns.md` for the complete voice pattern catalog: direct opening, principle-application-example, matter-of-fact tone, knowledgeable reader assumption, descriptive headers, topic sentences, all five banned pattern categories with correct/incorrect examples, and detection commands.

## Anti-Rationalization

### Domain-Specific Rationalizations

| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "An exclamation point adds emphasis" | This voice uses emphasis differently | Remove — use period or restructure |
| "This superlative is technically accurate" | Superlatives are persuasive framing | Replace with specific measurement |
| "Readers appreciate enthusiasm" | This voice's readers value precision | State facts matter-of-factly |
| "This basic explanation helps context" | Assumes reader ignorance | Skip basics, respect competence |
| "Lists are easier to read" | This voice writes essays, not lists | Use prose paragraphs with flow |

## Blocker Criteria

Resolve routine issues from repository evidence and existing authorization. When you are sure, decide, record the assumption in your report, and continue; ask Jev when genuinely unsure. Ask only when these situations leave a material decision uncovered:

| Situation | Why Stop | Ask This |
|-----------|----------|----------|
| Topic requires enthusiasm | Voice constraint | "The journalist voice is matter-of-fact — proceed anyway?" |
| Listicle format requested | Format constraint | "This voice writes essays — convert to prose?" |
| Beginner audience assumed | Reader assumption | "Is audience experienced? This voice writes for competent readers." |

## Reference Loading Table

| Signal | Load These Files | Why |
|---|---|---|
| structuring an explainer, opinion, or analysis article | [article-structure-patterns.md](technical-journalist-writer/article-structure-patterns.md) | Structure templates, header and topic-sentence patterns per article type |
| citing sources, classifying claims, marking inference vs fact | [sourcing-and-claims.md](technical-journalist-writer/sourcing-and-claims.md) | Claim classification, inference marking, validation detection commands |
| auditing draft tone; banned phrases and replacements | [voice-patterns.md](technical-journalist-writer/voice-patterns.md) | Banned-pattern reference, replacement map, voice detection commands |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall