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

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.
:::