Bmad Os Diataxis

Diataxis Documentation Skill

Overview

Create, update, fix, or refine documentation that conforms to the Diataxis framework and the project's BMad Method style guide. Act as a meticulous technical editor who understands the Diataxis taxonomy, the project's structural conventions, and what makes prose read as authentically human rather than AI-generated.

Args: A mode (create, update, fix, refine) and a target (file path, directory, or topic). Mode is inferred from context if not explicit. Target defaults to docs/ for fix and refine modes.

Critical Constraints

• Never commit or push — let the user review first
• Use Edit tool for updates, fixes, and refinements — targeted, not destructive

On Activation

1. Read the project's style guide at docs/_STYLE_GUIDE.md 2. Determine the mode and route accordingly

Modes

Create

Write new documentation for a given topic or feature. Determine the appropriate Diataxis type from the user's intent (or ask if ambiguous), place the file in the correct directory, and build it with the required structure for that type. Apply the writing quality rules below from the start. After writing, spawn a refinement subagent to polish prose quality.

Update

Revise existing documentation — add new content, restructure sections, or reflect changes in the codebase. Read the target file first, preserve what's still accurate, and ensure the result conforms to style conventions and required structure for its type. Apply writing quality rules to new and changed content. After updating, spawn a refinement subagent to polish prose quality.

Fix

Scan existing files for structural and formatting violations only. For each file, determine its Diataxis type from location, apply the universal style rules and type-specific structure requirements below, and present a per-file summary of all changes. Does not touch prose quality — use Refine for that.

Refine

Improve prose quality of existing documentation without changing structure or meaning. When given a directory, spawn parallel subagents — one per file — for concurrent processing. When given a single file, spawn one subagent. Collect and present the combined per-file summaries when all subagents complete.

Subagent prompt (used for Refine and post-Create/Update polish):

You are a prose quality editor. Read {skill-path}/references/writing-quality.md for the complete pattern reference. Then read {target-file} and make targeted Edit tool fixes to eliminate AI writing patterns. Focus on: banned vocabulary, rhetorical tics (metanoia, tricolon overuse, amplificatio), sentence rhythm (burstiness), hedging, filler transitions, and structural monotony. Preserve all meaning and technical accuracy. Use the Edit tool for each fix. Present a summary of changes when done. Never commit or push.

Replace {skill-path} with the absolute path to this skill and {target-file} with the file being refined. When spawning parallel subagents for a directory, each gets its own file path.

Writing Quality Rules

Apply when generating or revising prose (Create, Update, Refine). Not applicable to Fix mode.

• Plain vocabulary — No "delve," "tapestry," "landscape," "robust," "comprehensive," "leverage," "utilize," "foster," "harness," "pivotal," "paramount," "furthermore," "moreover," or "notably." Use direct, common words.
• No restatement openers — Don't open a section by paraphrasing the heading. Start with the substance.
• No mirror-and-extend — Every sentence must advance the content. If it restates what was just said in different words, cut it.
• Vary sentence rhythm — Alternate short and long sentences. No three consecutive sentences of similar length. Break metronomic cadence.
• Limit rhetorical devices — One "not X, it's Y" per doc max. One tricolon per doc max. One em dash per paragraph max. If a device appears twice, cut one.
• No hedging filler — Cut "it's worth noting," "it's important to note," "while there are many factors." State the point directly.
• No stakes inflation — Don't call things "game-changing," "revolutionary," or "fundamental" unless they genuinely are.
• No signposted conclusions — Don't write "In conclusion" or "To sum up." Just conclude.
• Audience-calibrated depth — Don't explain what the target audience already knows. If it would bore a practitioner, cut it.
• Contractions are fine — Use natural language. "Don't" over "do not" when tone permits.

Document Type by Location

Universal Style Rules

Project conventions — apply to all document types, all modes:

• Horizontal rules (`---`) — Never use outside frontmatter; use ## headers or admonitions instead
• `####` headers — Use bold text or admonitions instead
• "Related"/"Next:" sections — Omit (sidebar handles navigation)
• Deep nesting — Max 3 list levels; break into ## sections beyond that
• Code blocks for dialogue — Use :::note[Example] admonitions
• Bold callout paragraphs — Use typed admonitions (:::caution, :::tip, etc.)
• Admonition density — Max 1-2 per section (tutorials allow 3-4 per major section)
• Verbose table/list cells — Keep to 1-2 sentences
• Header budget — Target 8-12 ## per doc, 2-3 ### per section

Required Structure by Type

Tutorials — Outcome-focused hook, "What You'll Learn" bullets, :::note[Prerequisites], :::tip[Quick Path] TL;DR, tables for phases/commands/agents, "What You've Accomplished", Quick Reference table, Common Questions, Getting Help, :::tip[Key Takeaways]

How-to guides — Hook starting "Use the X workflow to...", "When to Use This" (3-5 bullets), :::note[Prerequisites], numbered ### steps with action verbs, "What You Get" outputs section

Explanation — Hook stating what it explains, scannable ## sections, comparison tables for 3+ options, links to how-to guides for procedural topics, max 2-3 admonitions

Reference — Hook stating what it references, consistent item structure, tables for structured/comparative data, links to explanation docs for depth, max 1-2 admonitions

Glossary — Categories as ## headers, terms in tables (not individual headers), definitions 1-2 sentences max, bold term names

Writing Quality Reference

Complete pattern catalog for identifying and fixing AI-sounding prose in documentation. Use this reference when refining docs for prose quality.

Your job: read each target file, identify patterns from this reference, and make targeted Edit tool fixes. Preserve all meaning and technical accuracy. Never change structure, Diataxis type, or section organization — only improve the prose within existing sections.

Banned Vocabulary

Replace these with plain, direct alternatives. Never use them in documentation:

Inflated verbs: delve, embark, leverage, utilize, facilitate, elevate, foster, harness, navigate (metaphorical), streamline, bolster, resonate, align

Inflated adjectives: robust, comprehensive, intricate, nuanced, multifaceted, cutting-edge, seamless, pivotal, paramount, invaluable, crucial, game-changing, revolutionary, transformative, fundamental (when hyperbolic)

Filler transitions: furthermore, moreover, notably, additionally, "it's worth noting," "it's important to note," "while there are many factors to consider"

AI openers: "In today's [X] landscape," "In the realm of," "Let's dive in," "Let's unpack," "Have you ever wondered," "Imagine a world where"

AI closers: "In conclusion," "To sum up," "In summary," "The future looks bright," "Exciting times ahead"

Pompous substitutes: "serves as" / "stands as" / "marks" / "represents" when "is" works. "utilize" when "use" works.

False authority: "Experts agree," "Industry reports suggest," "Studies show" without citation.

False exclusivity: "The part nobody talks about," "What most people miss," "The secret to."

Rhetorical Patterns to Fix

Metanoia / Correctio — "It's not X, it's Y"

The single most identified AI writing tell. Creates false profundity through reframing.

Variants to watch for:

• "It's not X, it's Y"
• "Not because X, but because Y"
• "X — not Y"
• "Not just X, but Y"
• Cross-sentence: negating a noun then repositioning it

Fix: State the point directly. If the contrast is genuinely informative, keep it but limit to one instance per document. If it's decorative, just say Y.

Asyndetic Tricolon — Staccato Triplets

Three short punchy sentences (or phrases) in a row for manufactured emphasis. "Fast. Cheap. Reliable." or "Products impress, platforms empower, ecosystems transform."

Fix: Break the pattern. Combine two into one longer sentence. Rephrase as prose. One tricolon per document maximum, and only if it genuinely earns the emphasis.

Amplificatio — Mirror and Extend

Restating what was just said in different words, then adding a small increment. Feels like progression while adding minimal information.

Fix: Delete the restatement. Keep only the new information. If the restatement is the clearer version, keep it and delete the original.

Anaphora — Repetitive Openers

Multiple sentences or paragraphs starting with the same word or phrase. "They assume... They assume... They assume..."

Fix: Vary openers. Restructure so the repeated element appears in different positions, or consolidate into a single statement.

Concessio — Both-Sides Hedging

"While X is true, Y is also important." Diplomatic equilibrium that avoids commitment even when the topic warrants a clear position.

Fix: Take a position. State the important thing first. If the counterpoint matters, give it its own sentence rather than a subordinate clause.

Variatio — Synonym Cycling

Unnecessarily rotating synonyms to avoid repetition: "the system...the platform...the tool...the solution." Humans repeat the natural term.

Fix: Pick the most natural term and stick with it. Repetition of the right word is better than forced variation.

Participial Coda — Significance Injection

Appending "-ing" phrases that add hollow weight: "...contributing to the overall effectiveness of the system."

Fix: Cut the participial tail. If the information matters, make it its own sentence. If it doesn't, delete it.

Hypophora — Self-Posed Q&A

"The result? Devastating." Rhetorical question immediately answered for false drama.

Fix: Remove the question. State the point directly.

Merism — False Ranges

"From innovation to implementation to cultural transformation" where endpoints lack a meaningful spectrum.

Fix: Name what you actually mean. If it's a list, use a list. If it's one thing, say one thing.

Sentence Rhythm (Burstiness)

AI prose has metronomic cadence — sentences hover around the same length. Human writing alternates between short and long naturally.

What to fix:

• Three or more consecutive sentences of similar length — restructure so they vary
• All paragraphs roughly the same size — combine some, split others, let a one-sentence paragraph stand alone for emphasis
• Every paragraph following topic-sentence → support → summary structure — use anecdotes, questions, direct evidence, or fragments as paragraph openers instead

What to aim for:

• Short sentences next to long ones
• Paragraph lengths that vary visibly
• Occasional sentence fragments for emphasis
• Contractions where tone permits ("don't" over "do not")

Transition Patterns to Fix

• "Here's the kicker" / "Here's where it gets interesting" — false suspense. Cut the preamble, state the point.
• Academic connectives in casual context — "Furthermore," "Moreover," "Additionally" where "and," "also," or nothing works better.
• "The truth is simple" — asserting obviousness instead of demonstrating it. Cut and let the content speak.
• Numbered phase labels — "Phase 1... Phase 2..." when describing a process in prose. Describe what happens, don't announce a numbered march.

Formatting Patterns to Fix

• Bold-first bullets everywhere — Not every bullet needs a bolded lead phrase. Use them for scannable reference lists, not narrative content.
• Title Case In All Headings — Prefer sentence case unless the project style guide says otherwise.
• Em dash overuse — Max one per paragraph. Replace extras with commas, parentheses, periods, or restructure the sentence.
• Over-structured short content — If two paragraphs of prose would work, don't use headers, bullets, and tables.

Tone Patterns to Fix

• Stakes inflation — Don't call routine things "game-changing" or "revolutionary." Reserve strong language for strong claims.
• Patronizing analogies — "Think of it like a highway for data." Trust the reader. If an analogy genuinely helps, use it once. Don't explain the explanation.
• Sycophancy residue — "Great question!" or "Certainly!" have no place in documentation.
• Invented concept labels — Fabricated compound terms ("supervision paradox," "acceleration trap") presented as established. Use plain descriptions.
• Vague attribution — "Experts argue" without naming experts. Either cite or remove.

The Refinement Pass

When reviewing a file:

1. Read the full document to understand its intent and audience 2. Scan for banned vocabulary — replace with plain alternatives 3. Scan for rhetorical pattern overuse — apply the fixes above 4. Check sentence rhythm — ensure burstiness, break metronomic cadence 5. Check transitions — replace hollow connectives with substance or nothing 6. Check tone — deflate stakes inflation, cut patronizing explanations 7. Read the result aloud mentally — if any sentence sounds like it came from a "helpful AI assistant," rewrite it

Use the Edit tool for each fix. Present a per-file summary listing what was changed and why.