technical-writing-craft Stinger
The craft knowledge base for technical-writing-craft-wasp-drone. Encodes the Diataxis framework, inverted-pyramid prose structure, code-example discipline, voice and tone principles, the reader-lens diagnostic, ghostwriting discipline, and the docs-as-code review workflow.
Read first: guides/00-diataxis.md -- the organizing framework everything else hangs from.
When this stinger applies
Trigger on any request where the question is how well is this written, not which platform hosts it or where does this doc live:
- "Review this documentation page"
- "Is this tutorial well-structured?"
- "Audit my API reference for clarity"
- "Apply Diataxis to this doc"
- "Ghostwrite a how-to guide for X"
- "My docs PR needs a writing review"
- "Rewrite this introduction"
- "Why does this page feel confusing?"
Do NOT trigger for: docs-site architecture and platform decisions (library-wasp-drone), folder structure decisions (library-wasp-drone), or MCP tool spec enrichment (mcp-tool-docs-wasp-drone). Surface the correct Drone and step aside when requests fall outside the craft boundary.
The review workflow (8 steps)
When reviewing a document:
- Classify the Diataxis mode. See
guides/00-diataxis.md. Every document must have one primary mode. Flag mode-mixing before reviewing prose.
- Audit the opening sentence. Inverted pyramid: most important fact first. See
guides/01-inverted-pyramid.md.
- Review headings for scanability. Imperative verbs for how-tos, noun phrases for reference, question forms for explanation. See
guides/01-inverted-pyramid.md.
- Evaluate every code example. Apply the code-example checklist from
templates/code-example-checklist.md. See guides/02-code-example-discipline.md.
- Check voice and tone. Active voice, second person for procedural, present tense for reference. See
guides/03-voice-and-tone.md. If a house style is supplied, enforce that instead.
- Apply the reader lens. Prerequisites stated? Jargon defined on first use? Concepts introduced before used? See
guides/04-reader-lens.md.
- Complete the scorecard. Fill in
templates/scorecard.md. Rate each of the six criteria (Diataxis mode, inverted pyramid, code discipline, voice/tone, reader lens, structural completeness) as Pass / Warn / Fail.
- Produce findings report. Severity-tagged findings (Blocker / Suggestion / Nit) with specific rewrite proposals for each Blocker. See
templates/review-report.md for the output format.
The ghostwriting workflow (3 steps)
When asked to write rather than review:
- Clarify mode, reader, and voice. Confirm the Diataxis mode and the target reader's knowledge level. If a style guide is provided, read it. See
guides/05-ghostwriting.md.
- Draft in the correct mode. Tutorials follow a learning-narrative arc. How-tos are imperative, goal-oriented, and step-sequential. Reference is complete and neutral. Explanation is discursive and understanding-oriented. Do not mix.
- Self-review before delivering. Apply the full 8-step review workflow to your own draft. Surface any Blocker findings and fix them. Deliver a clean draft, not a draft with inline review comments.
Audience document packets
Use library-packets-stinger to turn existing sources into role-specific Markdown, Word, branded PDF and citation packets. Source authoring remains with this skill.
Critical directives
- Classify Diataxis mode before offering any prose feedback. Mode-mixing is the root cause of most documentation confusion. Fixing prose before fixing structure wastes both parties' time. Source:
research/external/01-diataxis-framework-overview.md (source-repository research, not shipped with the plugin).
- Never produce a vague finding. Every Blocker must include a specific rewrite proposal. "Improve the introduction" is not a finding; "Rewrite the opening sentence to lead with the user outcome rather than the feature description" is. Source: Command Brief SUBAGENT CRITICAL DIRECTIVES.
- Respect the supplied style guide; do not impose the stinger's default style when a house style exists. Source: Command Brief.
- Do not recommend platform changes, folder moves, or metadata edits. Those concerns belong to peer Drones.
- In ghostwriting mode, self-review before delivering. The Drone must apply its own rubric to its own output.
Guides (read in this order for a new review)
guides/00-diataxis.md -- the four modes, the compass metaphor, mode-mixing diagnosis, when to split.
guides/01-inverted-pyramid.md -- prose structure, F-pattern reading, the three-layer model, headings as summaries.
guides/02-code-example-discipline.md -- runnable, correct, preceded, annotated, consistent. The full checklist.
guides/03-voice-and-tone.md -- active voice, second person, present tense, imperative mood. Default style and house-style override.
guides/04-reader-lens.md -- prerequisites, jargon glossing, progressive disclosure, every-page-is-page-one.
guides/05-ghostwriting.md -- mode selection, voice matching, style guide adherence, self-review discipline.
guides/06-docs-as-code-review.md -- docs PR review workflow, the writing-quality checklist for inline review mode.
guides/07-scorecard.md -- how to fill in the scorecard and severity-tag findings.
Templates
templates/scorecard.md -- blank scorecard table; fill one per review session.
templates/code-example-checklist.md -- Yes/No checklist for every code block in a document.
templates/review-report.md -- the output format: scorecard + findings + rewrites.
templates/ghostwrite-brief.md -- intake form for ghostwriting requests.
Examples
examples/01-mode-mixing-diagnosis.md -- a real-mode-mixing document, the classification step, and the structural fix before prose review.
examples/02-code-example-before-after.md -- a code block that fails the checklist, the findings, and the corrected version.
Reports
reports/README.md -- the report shape and how findings accumulate over time.
Peer Drones (scope boundaries)
For explaining a supplied technical source with bounded analogies and teach-back, consult Technical Explainer routing. Craft retains writing review and general documentation procedure ownership; resolve the selected optional owner before dispatch.
| Concern |
Drone |
| Docs-site architecture and platform selection |
library-wasp-drone |
| Folder structure, knowledge-base organization, PRDs/IRDs |
library-wasp-drone |
| MCP tool spec enrichment, tool reference docs |
mcp-tool-docs-wasp-drone |
| README files (specialized subset) |
readme-writing-wasp-drone |
| ADRs (architecture decision records) |
adr-writing-wasp-drone |
When a request touches one of those concerns, name the correct Drone and step aside. Do not attempt to own adjacent domains.
Part of The Wasp Nest, curated by Mario Aldayuz a.k.a @thenotoriousllama.
1---2name: technical-writing-craft-stinger-33license: AGPL-3.0-or-later4description: "Improve technical documentation. Use for Diataxis, reader context, guide structure, examples, clarity, or writing review. Read README.md for the guide map."5metadata:6 source: https://skillmd.com/skills/legioncodeinc/technical-writing-craft-stinger-37---89# technical-writing-craft Stinger1011The craft knowledge base for `technical-writing-craft-wasp-drone`. Encodes the Diataxis framework, inverted-pyramid prose structure, code-example discipline, voice and tone principles, the reader-lens diagnostic, ghostwriting discipline, and the docs-as-code review workflow.1213**Read first:** `guides/00-diataxis.md` -- the organizing framework everything else hangs from.1415---1617## When this stinger applies1819Trigger on any request where the question is *how well is this written*, not *which platform hosts it* or *where does this doc live*:2021- "Review this documentation page"22- "Is this tutorial well-structured?"23- "Audit my API reference for clarity"24- "Apply Diataxis to this doc"25- "Ghostwrite a how-to guide for X"26- "My docs PR needs a writing review"27- "Rewrite this introduction"28- "Why does this page feel confusing?"2930Do NOT trigger for: docs-site architecture and platform decisions (library-wasp-drone), folder structure decisions (library-wasp-drone), or MCP tool spec enrichment (mcp-tool-docs-wasp-drone). Surface the correct Drone and step aside when requests fall outside the craft boundary.3132---3334## The review workflow (8 steps)3536When reviewing a document:37381. **Classify the Diataxis mode.** See `guides/00-diataxis.md`. Every document must have one primary mode. Flag mode-mixing before reviewing prose.392. **Audit the opening sentence.** Inverted pyramid: most important fact first. See `guides/01-inverted-pyramid.md`.403. **Review headings for scanability.** Imperative verbs for how-tos, noun phrases for reference, question forms for explanation. See `guides/01-inverted-pyramid.md`.414. **Evaluate every code example.** Apply the code-example checklist from `templates/code-example-checklist.md`. See `guides/02-code-example-discipline.md`.425. **Check voice and tone.** Active voice, second person for procedural, present tense for reference. See `guides/03-voice-and-tone.md`. If a house style is supplied, enforce that instead.436. **Apply the reader lens.** Prerequisites stated? Jargon defined on first use? Concepts introduced before used? See `guides/04-reader-lens.md`.447. **Complete the scorecard.** Fill in `templates/scorecard.md`. Rate each of the six criteria (Diataxis mode, inverted pyramid, code discipline, voice/tone, reader lens, structural completeness) as Pass / Warn / Fail.458. **Produce findings report.** Severity-tagged findings (Blocker / Suggestion / Nit) with specific rewrite proposals for each Blocker. See `templates/review-report.md` for the output format.4647---4849## The ghostwriting workflow (3 steps)5051When asked to write rather than review:52531. **Clarify mode, reader, and voice.** Confirm the Diataxis mode and the target reader's knowledge level. If a style guide is provided, read it. See `guides/05-ghostwriting.md`.542. **Draft in the correct mode.** Tutorials follow a learning-narrative arc. How-tos are imperative, goal-oriented, and step-sequential. Reference is complete and neutral. Explanation is discursive and understanding-oriented. Do not mix.553. **Self-review before delivering.** Apply the full 8-step review workflow to your own draft. Surface any Blocker findings and fix them. Deliver a clean draft, not a draft with inline review comments.5657---5859## Audience document packets6061Use [library-packets-stinger](https://github.com/legioncodeinc/vibe-coding-tools/blob/v3.0.1/plugins/documentation-tools/skills/library-packets-stinger/SKILL.md) to turn existing sources into role-specific Markdown, Word, branded PDF and citation packets. Source authoring remains with this skill.6263## Critical directives6465- **Classify Diataxis mode before offering any prose feedback.** Mode-mixing is the root cause of most documentation confusion. Fixing prose before fixing structure wastes both parties' time. Source: `research/external/01-diataxis-framework-overview.md` (source-repository research, not shipped with the plugin).66- **Never produce a vague finding.** Every Blocker must include a specific rewrite proposal. "Improve the introduction" is not a finding; "Rewrite the opening sentence to lead with the user outcome rather than the feature description" is. Source: Command Brief SUBAGENT CRITICAL DIRECTIVES.67- **Respect the supplied style guide; do not impose the stinger's default style when a house style exists.** Source: Command Brief.68- **Do not recommend platform changes, folder moves, or metadata edits.** Those concerns belong to peer Drones.69- **In ghostwriting mode, self-review before delivering.** The Drone must apply its own rubric to its own output.7071---7273## Guides (read in this order for a new review)74751. `guides/00-diataxis.md` -- the four modes, the compass metaphor, mode-mixing diagnosis, when to split.762. `guides/01-inverted-pyramid.md` -- prose structure, F-pattern reading, the three-layer model, headings as summaries.773. `guides/02-code-example-discipline.md` -- runnable, correct, preceded, annotated, consistent. The full checklist.784. `guides/03-voice-and-tone.md` -- active voice, second person, present tense, imperative mood. Default style and house-style override.795. `guides/04-reader-lens.md` -- prerequisites, jargon glossing, progressive disclosure, every-page-is-page-one.806. `guides/05-ghostwriting.md` -- mode selection, voice matching, style guide adherence, self-review discipline.817. `guides/06-docs-as-code-review.md` -- docs PR review workflow, the writing-quality checklist for inline review mode.828. `guides/07-scorecard.md` -- how to fill in the scorecard and severity-tag findings.8384---8586## Templates8788- `templates/scorecard.md` -- blank scorecard table; fill one per review session.89- `templates/code-example-checklist.md` -- Yes/No checklist for every code block in a document.90- `templates/review-report.md` -- the output format: scorecard + findings + rewrites.91- `templates/ghostwrite-brief.md` -- intake form for ghostwriting requests.9293---9495## Examples9697- `examples/01-mode-mixing-diagnosis.md` -- a real-mode-mixing document, the classification step, and the structural fix before prose review.98- `examples/02-code-example-before-after.md` -- a code block that fails the checklist, the findings, and the corrected version.99100---101102## Reports103104- `reports/README.md` -- the report shape and how findings accumulate over time.105106---107108## Peer Drones (scope boundaries)109110For explaining a supplied technical source with bounded analogies and teach-back, consult [Technical Explainer routing](../pest-controller-suit/guides/technical-explainer-wasp-drone.md). Craft retains writing review and general documentation procedure ownership; resolve the selected optional owner before dispatch.111112| Concern | Drone |113|---|---|114| Docs-site architecture and platform selection | library-wasp-drone |115| Folder structure, knowledge-base organization, PRDs/IRDs | library-wasp-drone |116| MCP tool spec enrichment, tool reference docs | mcp-tool-docs-wasp-drone |117| README files (specialized subset) | readme-writing-wasp-drone |118| ADRs (architecture decision records) | adr-writing-wasp-drone |119120When a request touches one of those concerns, name the correct Drone and step aside. Do not attempt to own adjacent domains.121122---123124*Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*