initial commit
This commit is contained in:
221
.agents/skills/bmad-create-prd/steps-c/step-11-polish.md
Normal file
221
.agents/skills/bmad-create-prd/steps-c/step-11-polish.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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 (MVP, Growth, Vision)
|
||||
- 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!
|
||||
Reference in New Issue
Block a user