92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
---
|
|
title: Fix Documentation References
|
|
description: Corrects workflow, agent, and command references in BMad documentation
|
|
---
|
|
|
|
# Fix Documentation References
|
|
|
|
## Scope
|
|
|
|
Fix reference patterns ONLY. Do not modify links, formatting, structure, or other content.
|
|
|
|
## Purpose
|
|
|
|
Fix incorrect references to workflows, agents, and commands in BMad documentation files.
|
|
|
|
## Step 1: Establish Target Audience
|
|
|
|
Before fixing references, determine who the document is for:
|
|
|
|
| Audience | Indicators | Style |
|
|
|----------|------------|-------|
|
|
| **Newbies** | tutorials/, getting-started, installation/, "What You'll Learn" | Keep "workflow", include platform hints |
|
|
| **Experienced** | reference/, explanation/ | Drop "workflow", no platform hints |
|
|
| **How-To** | how-to/ | **Ask** — depends on the task |
|
|
|
|
**How-To guides require judgment**: Don't assume experienced. Ask: "Does this task require prior BMad knowledge?" Early-journey tasks (first PRD, first sprint) are newbie docs. Customization and advanced features are experienced.
|
|
|
|
**If unclear**: Ask the user "Who is the target audience for this document — new users learning BMad, or experienced users who know the system?"
|
|
|
|
This determines whether helper words like "workflow" and platform hints are helpful context or just noise.
|
|
|
|
## Reference Patterns to Fix
|
|
|
|
### Always Wrong
|
|
|
|
| Pattern | Example | Problem |
|
|
|---------|---------|---------|
|
|
| `*workflow` | `*prd` | Obsolete menu shortcut notation |
|
|
| `/workflow` | `/workflow-init` | Platform-specific slash command |
|
|
| `bmad_bmm_*` | `bmad_bmm_workflow-init` | Internal slash command name, platform-specific |
|
|
|
|
### Correct Format
|
|
|
|
Use backticks with plain workflow name:
|
|
- **Wrong**: Run `/workflow-init`
|
|
- **Wrong**: Run `*prd`
|
|
|
|
**When to say "workflow"**:
|
|
- **Newbie docs** (getting-started): "Run the `prd` workflow" — helps them learn what it is
|
|
- **Other docs**: "Run `prd`" — they already know, so "workflow" is noise
|
|
|
|
**Platform hint**: Only in newbie docs, and only on the **first** workflow mention:
|
|
- First mention: Run the `help` workflow (`/bmad-help` on most platforms)
|
|
- Subsequent mentions: Run `prd` — no hint, no "workflow" needed after they've seen the pattern
|
|
|
|
In experienced docs, the hint is always noise — just use the workflow name.
|
|
|
|
### Workflow Name Changes
|
|
|
|
| Old Name | New Name | Notes |
|
|
|----------|----------|-------|
|
|
| `workflow-init` | `bmad-help` | DEPRECATED - help system replaces initialization |
|
|
| `workflow-status` | `bmad-help` | DEPRECATED - help system replaces status checking |
|
|
|
|
### The Help System
|
|
|
|
The `bmad-help` workflow is the modern replacement for both `workflow-init` and `workflow-status`:
|
|
- **Universal**: Works regardless of workflow state or module
|
|
- **Contextual**: Infers completion from artifacts and conversation
|
|
- **Adaptive**: Guides users through workflows based on phase ordering
|
|
- **Anytime**: Can be run at any point, no pre-initialization needed
|
|
|
|
Users can run `bmad-help` to get guidance on what to do next. It detects:
|
|
- What workflows have been completed (by checking for output artifacts)
|
|
- What module is active
|
|
- What the next recommended/required step is
|
|
|
|
## Lessons Learned
|
|
|
|
1. **Platform-agnostic**: Docs should never include platform-specific invocation patterns (slashes, prefixes)
|
|
2. **Backtick the name**: Use backticks around workflow names: `workflow-name`
|
|
3. **Simple names**: Just the workflow name, no `bmad_bmm_` prefix, no `/` prefix
|
|
|
|
## Self-Check
|
|
|
|
Before finishing, verify you ONLY changed reference patterns:
|
|
|
|
- [ ] Did I change any hyperlinks? **If yes, revert.**
|
|
- [ ] Did I change any formatting (horizontal rules, whitespace, structure)? **If yes, revert.**
|
|
- [ ] Did I remove or add any sections? **If yes, revert.**
|
|
- [ ] Did I modify anything not matching the patterns in "Reference Patterns to Fix"? **If yes, revert.**
|