BMAD-METHOD/.claude/skills/bmad-os-diataxis-style-fix/SKILL.md

name	description	license
bmad-os-diataxis-style-fix	Fixes documentation to comply with Diataxis framework and BMad Method style guide rules. Use when user asks to check or fix style of files under the docs folder.	MIT

Diataxis Style Fixer

Automatically fixes documentation to comply with the Diataxis framework and BMad Method style guide.

CRITICAL RULES

• NEVER commit or push changes — let the user review first
• NEVER make destructive edits — preserve all content, only fix formatting
• Use Edit tool — make targeted fixes, not full file rewrites
• Show summary — after fixing, list all changes made

Input

Documentation file path or directory to fix. Defaults to docs/ if not specified.

Step 1: Understand Diataxis Framework

Diataxis is a documentation framework that categorizes content into four types based on two axes:

	Learning (oriented toward future)	Doing (oriented toward present)
Practical	Tutorials — lessons that guide learners through achieving a specific goal	How-to guides — step-by-step instructions for solving a specific problem
Conceptual	Explanation — content that clarifies and describes underlying concepts	Reference — technical descriptions, organized for lookup

Key principles:

• Each document type serves a distinct user need
• Don't mix types — a tutorial shouldn't explain concepts deeply
• Focus on the user's goal, not exhaustive coverage
• Structure follows purpose (tutorials are linear, reference is scannable)

Step 2: Read the Style Guide

Read the project's style guide at docs/_STYLE_GUIDE.md to understand all project-specific conventions.

Step 3: Detect Document Type

Based on file location, determine the document type:

Location	Diataxis Type
/docs/tutorials/	Tutorial
/docs/how-to/	How-to guide
/docs/explanation/	Explanation
/docs/reference/	Reference
/docs/glossary/	Reference (glossary)

Step 4: Find and Fix Issues

For each markdown file, scan for issues and fix them:

Universal Fixes (All Doc Types)

Horizontal Rules (---)

• Remove any --- outside of YAML frontmatter
• Replace with ## section headers or admonitions as appropriate

#### Headers

• Replace with bold text: #### Header → **Header**
• Or convert to admonition if it's a warning/notice

"Related" or "Next:" Sections

• Remove entire section including links
• The sidebar handles navigation

Deeply Nested Lists

• Break into sections with ## headers
• Flatten to max 3 levels

Code Blocks for Dialogue/Examples

• Convert to admonitions:

  :::note[Example]
  [content]
  :::
  

Bold Paragraph Callouts

• Convert to admonitions with appropriate type

Too Many Admonitions

• Limit to 1-2 per section (tutorials allow 3-4 per major section)
• Consolidate related admonitions
• Remove less critical ones if over limit

Table Cells / List Items > 2 Sentences

• Break into multiple rows/cells
• Or shorten to 1-2 sentences

Header Budget Exceeded

• Merge related sections
• Convert some ## to ### subsections
• Goal: 8-12 ## per doc; 2-3 ### per section

Type-Specific Fixes

Tutorials (/docs/tutorials/)

• Ensure hook describes outcome in 1-2 sentences
• Add "What You'll Learn" bullet section if missing
• Add :::note[Prerequisites] if missing
• Add :::tip[Quick Path] TL;DR at top if missing
• Use tables for phases, commands, agents
• Add "What You've Accomplished" section if missing
• Add Quick Reference table if missing
• Add Common Questions section if missing
• Add Getting Help section if missing
• Add :::tip[Key Takeaways] at end if missing

How-To (/docs/how-to/)

• Ensure hook starts with "Use the X workflow to..."
• Add "When to Use This" with 3-5 bullets if missing
• Add :::note[Prerequisites] if missing
• Ensure steps are numbered ### with action verbs
• Add "What You Get" describing outputs if missing

Explanation (/docs/explanation/)

• Ensure hook states what document explains
• Organize content into scannable ## sections
• Add comparison tables for 3+ options
• Link to how-to guides for procedural questions
• Limit to 2-3 admonitions per document

Reference (/docs/reference/)

• Ensure hook states what document references
• Ensure structure matches reference type
• Use consistent item structure throughout
• Use tables for structured/comparative data
• Link to explanation docs for conceptual depth
• Limit to 1-2 admonitions per document

Glossary (/docs/glossary/ or glossary files)

• Ensure categories as ## headers
• Ensure terms in tables (not individual headers)
• Definitions 1-2 sentences max
• Bold term names in cells

Step 5: Apply Fixes

For each file with issues:

1. Read the file
2. Use Edit tool for each fix
3. Track what was changed

Step 6: Summary

After processing all files, output a summary:

# Style Fixes Applied

**Files processed:** N
**Files modified:** N

## Changes Made

### `path/to/file.md`
- Removed horizontal rule at line 45
- Converted `####` headers to bold text
- Added `:::tip[Quick Path]` admonition
- Consolidated 3 admonitions into 2

### `path/to/other.md`
- Removed "Related:" section
- Fixed table cell length (broke into 2 rows)

## Review Required

Please review the changes. When satisfied, commit and push as needed.

Common Patterns

Converting #### to bold:

#### Important Note
Some text here.

→

**Important Note**

Some text here.

Removing horizontal rule:

Some content above.

---

Some content below.

→

Some content above.

## [Descriptive Section Header]

Some content below.

Converting code block to admonition:

User: What should I do?

Agent: Run the workflow.

→

:::note[Example]

**User:** What should I do?

**Agent:** Run the workflow.

:::

Converting bold paragraph to admonition:

**IMPORTANT:** This is critical that you read this before proceeding.

→

:::caution[Important]
This is critical that you read this before proceeding.
:::