bmad-template/.agents/skills/bmad-create-prd/steps-c/step-11-polish.md

# Step 11: Document Polish

**Progress: Step 11 of 12** - Next: Complete PRD

## MANDATORY EXECUTION RULES (READ FIRST):

- 🛑 CRITICAL: Load the ENTIRE document before making changes
- 📖 CRITICAL: Read complete step file before taking action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- ✅ This is a POLISH step - optimize existing content
- 📋 IMPROVE flow, coherence, and readability
- 💬 PRESERVE user's voice and intent
- 🎯 MAINTAIN all essential information while improving presentation
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`

## EXECUTION PROTOCOLS:

- 🎯 Load complete document first
- 📝 Review for flow and coherence issues
- ✂️ Reduce duplication while preserving essential info
- 📖 Ensure proper ## Level 2 headers throughout
- 💾 Save optimized document
- ⚠️ Present A/P/C menu after polish
- 🚫 DO NOT skip review steps

## CONTEXT BOUNDARIES:

- Complete PRD document exists from all previous steps
- Document may have duplication from progressive append
- Sections may not flow smoothly together
- Level 2 headers ensure document can be split if needed
- Focus on readability and coherence

## YOUR TASK:

Optimize the complete PRD document for flow, coherence, and professional presentation while preserving all essential information.

## DOCUMENT POLISH SEQUENCE:

### 1. Load Context and Document

**CRITICAL:** Load the PRD purpose document first:

- Read `../data/prd-purpose.md` to understand what makes a great BMAD PRD
- Internalize the philosophy: information density, traceability, measurable requirements
- Keep the dual-audience nature (humans + LLMs) in mind

**Then Load the PRD Document:**

- Read `{outputFile}` completely from start to finish
- Understand the full document structure and content
- Identify all sections and their relationships
- Note areas that need attention

### 2. Document Quality Review

Review the entire document with PRD purpose principles in mind:

**Information Density:**
- Are there wordy phrases that can be condensed?
- Is conversational padding present?
- Can sentences be more direct and concise?

**Flow and Coherence:**
- Do sections transition smoothly?
- Are there jarring topic shifts?
- Does the document tell a cohesive story?
- Is the progression logical for readers?

**Duplication Detection:**
- Are ideas repeated across sections?
- Is the same information stated multiple times?
- Can redundant content be consolidated?
- Are there contradictory statements?

**Header Structure:**
- Are all main sections using ## Level 2 headers?
- Is the hierarchy consistent (##, ###, ####)?
- Can sections be easily extracted or referenced?
- Are headers descriptive and clear?

**Readability:**
- Are sentences clear and concise?
- Is the language consistent throughout?
- Are technical terms used appropriately?
- Would stakeholders find this easy to understand?

### 2b. Brainstorming Reconciliation (if brainstorming input exists)

**Check the PRD frontmatter `inputDocuments` for any brainstorming document** (e.g., `brainstorming-session*.md`, `brainstorming-report.md`). If a brainstorming document was used as input:

1. **Load the brainstorming document** and extract all distinct ideas, themes, and recommendations
2. **Cross-reference against the PRD** — for each brainstorming idea, check if it landed in any PRD section (requirements, success criteria, user journeys, scope, etc.)
3. **Identify dropped ideas** — ideas from brainstorming that do not appear anywhere in the PRD. Pay special attention to:
   - Tone, personality, and interaction design ideas (these are most commonly lost)
   - Design philosophy and coaching approach ideas
   - "What should this feel like" ideas (UX feel, not just UX function)
   - Qualitative/soft ideas that don't map cleanly to functional requirements
4. **Present findings to user**: "These brainstorming ideas did not make it into the PRD: [list]. Should any be incorporated?"
5. **If user wants to incorporate dropped ideas**: Add them to the most appropriate PRD section (success criteria, non-functional requirements, or a new section if needed)

**Why this matters**: Brainstorming documents are often long, and the PRD's structured template has an implicit bias toward concrete/structural ideas. Soft ideas (tone, philosophy, interaction feel) frequently get silently dropped because they don't map cleanly to FR/NFR format.

### 3. Optimization Actions

Make targeted improvements:

**Improve Flow:**
- Add transition sentences between sections
- Smooth out jarring topic shifts
- Ensure logical progression
- Connect related concepts across sections

**Reduce Duplication:**
- Consolidate repeated information
- Keep content in the most appropriate section
- Use cross-references instead of repetition
- Remove redundant explanations

**Enhance Coherence:**
- Ensure consistent terminology throughout
- Align all sections with product differentiator
- Maintain consistent voice and tone
- Verify scope consistency across sections

**Optimize Headers:**
- Ensure all main sections use ## Level 2
- Make headers descriptive and action-oriented
- Check that headers follow consistent patterns
- Verify headers support document navigation

### 4. Preserve Critical Information

**While optimizing, ensure NOTHING essential is lost:**

**Must Preserve:**
- All user success criteria
- All functional requirements (capability contract)
- All user journey narratives
- All scope decisions (whether phased or single-release), including consent-critical evidence (explicit user confirmations and rationales for any scope changes from step 8)
- All non-functional requirements
- Product differentiator and vision
- Domain-specific requirements
- Innovation analysis (if present)

**Can Consolidate:**
- Repeated explanations of the same concept
- Redundant background information
- Multiple versions of similar content
- Overlapping examples

### 5. Generate Optimized Document

Create the polished version:

**Polishing Process:**
1. Start with original document
2. Apply all optimization actions
3. Review to ensure nothing essential was lost
4. Verify improvements enhance readability
5. Prepare optimized version for review

### 6. Present MENU OPTIONS

Present the polished document for review, then display menu:
- Show what changed in the polish
- Highlight improvements made (flow, duplication, headers)
- Ask if they'd like to refine further, get other perspectives, or proceed
- Present menu options naturally as part of conversation

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Complete PRD (Step 12 of 12)"

#### Menu Handling Logic:
- IF A: Invoke the `bmad-advanced-elicitation` skill with the polished document, process the enhanced refinements that come back, ask user "Accept these polish improvements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original polish then redisplay menu
- IF P: Invoke the `bmad-party-mode` skill with the polished document, process the collaborative refinements to flow and coherence, ask user "Accept these polish changes? (y/n)", if yes update content with improvements then redisplay menu, if no keep original polish then redisplay menu
- IF C: Save the polished document to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-12-complete.md
- IF Any other: help user respond, then redisplay menu

#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After other menu items execution, return to this menu

## APPEND TO DOCUMENT:

When user selects 'C', replace the entire document content with the polished version.

## SUCCESS METRICS:

✅ Complete document loaded and reviewed
✅ Flow and coherence improved
✅ Duplication reduced while preserving essential information
✅ All main sections use ## Level 2 headers
✅ Transitions between sections are smooth
✅ User's voice and intent preserved
✅ Document is more readable and professional
✅ A/P/C menu presented and handled correctly
✅ Brainstorming reconciliation completed (if brainstorming input exists)
✅ Polished document saved when C selected

## FAILURE MODES:

❌ Loading only partial document (leads to incomplete polish)
❌ Removing essential information while reducing duplication
❌ Not preserving user's voice and intent
❌ Changing content instead of improving presentation
❌ Not ensuring ## Level 2 headers for main sections
❌ Making arbitrary style changes instead of coherence improvements
❌ Not presenting A/P/C menu for user approval
❌ Saving polished document without user selecting 'C'

❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
❌ **CRITICAL**: Making changes without complete understanding of document requirements

## NEXT STEP:

After user selects 'C' and polished document is saved, load `./step-12-complete.md` to complete the workflow.

Remember: Do NOT proceed to step-12 until user explicitly selects 'C' from the A/P/C menu and polished document is saved!