ensemble-refine-prd

name	ensemble-refine-prd
description	Refine and enhance existing PRD with stakeholder feedback and additional detail (Codex skill for /ensemble:refine-prd)
user-invocable	true
model	gpt-5.1-codex

Ensemble Command: /ensemble:refine-prd

This Codex skill mirrors the Ensemble slash command /ensemble:refine-prd. Follow the workflow below, adapt to the current repository, and keep outputs structured.

Refine and enhance an existing Product Requirements Document based on stakeholder feedback, additional research, or identified gaps. Updates PRD while maintaining version history, traceability, and alignment with the create-prd v2.2.0 format including PRD Health summaries, MoSCoW priorities, and Implementation Readiness Gate scoring.

Workflow

Phase 1: PRD Review

1. Current PRD Analysis Review existing PRD content and establish baseline metrics

• Read the PRD file from the path provided in $ARGUMENTS
• Parse frontmatter for Document ID, Version, Status, and Readiness Score
• Count requirements by type (functional, non-functional) and priority (Must/Should/Could/Won't)
• Count acceptance criteria and compute AC coverage percentage (requirements with at least one AC / total requirements)
• Check if PRD Health summary exists and whether its numbers match actual requirement counts
• Note the current version number for version bumping later

2. Synthesis After reviewing the PRD, generate a numbered list of findings WITHOUT making any edits yet. Scan for the following issues:

• '[NEEDS CLARIFICATION] markers from create-prd — present each one verbatim as a finding so the user''s answers replace the marker with actual content'
• Requirements missing REQ-NNN IDs as H3 headings
• Acceptance criteria that are missing or not in Given/When/Then format
• Missing PRD document ID (PRD-YYYY-NNN) in frontmatter
• Unclear or ambiguous requirement language
• Scope gaps (scenarios or edge cases not addressed)
• Missing technical constraints or dependencies
• Missing priority ordering of features or requirements
• Open questions or unresolved decisions
• Requirements missing MoSCoW priority tags (Must/Should/Could/Won't)
• Requirements missing complexity tags (Low/Medium/High)
• Requirements missing risk indicators where complexity is Medium or High
• Missing or incomplete dependency map (cross-requirement dependencies)
• PRD Health summary missing or outdated (requirement counts by priority don't match actual counts)
• Missing Implementation Readiness Gate scorecard
• Acceptance criteria coverage gaps (Must requirements with fewer than 2 ACs, Should requirements with zero ACs)

Use the AskUserQuestion tool to present a consolidated numbered list in this exact format, then capture the user's selection as SELECTED_ITEMS:

---

Based on my review of , here are the areas I suggest improving:

1. [issue description — e.g., "REQ-003 is missing acceptance criteria"]
2. [issue description] ...N. [issue description]

Which would you like to address? Reply with: all, a comma-separated list of numbers (e.g. 1,3), or skip to exit without changes.

If the user replies "skip" or selects nothing, exit immediately without making any changes. If the user replies "all", set SELECTED_ITEMS to every finding number.

3. Interview REQUIRED: Conduct a targeted user interview covering ONLY the topics corresponding to SELECTED_ITEMS. Skip any findings the user did not select.

Use the AskUserQuestion tool to present questions interactively:

• Ask questions ONE AT A TIME (not all at once)
• Wait for user answer before asking the next question
• Do NOT just write questions in your response text
• The user should see interactive question UI prompts

'For [NEEDS CLARIFICATION] findings: quote the marker verbatim, then ask the embedded question directly. Replace the marker with the user''s answer in the Content Refinement step.'

For each selected finding, ask a focused follow-up question. Examples:

• For unclear requirements: ask the user to clarify intent or expected behavior
• For missing ACs: ask what testable conditions define success
• For missing REQ-NNN IDs: confirm the correct ID to assign
• For missing frontmatter: ask for the PRD document ID (PRD-YYYY-NNN)
• For scope gaps: ask whether the missing scenario should be in or out of scope
• For missing constraints: ask for the relevant technical or business constraints
• For priority ordering: ask the user to rank or confirm priority
• For missing MoSCoW tags: present the requirement and ask user to assign Must/Should/Could/Won't
• For missing complexity tags: ask user to assess Low/Medium/High based on implementation effort
• For missing risk indicators: ask what risks apply to Medium/High complexity items
• For dependency gaps: ask which requirements depend on or are blocked by others

4. Feedback Integration Incorporate the answers gathered during the Interview step. Apply changes only for SELECTED_ITEMS — do not modify sections the user did not select.

Phase 2: Enhancement

1. Content Refinement Enhance clarity, detail, and completeness for SELECTED_ITEMS only. Retroactively assign REQ-NNN IDs to any unnumbered requirements selected by the user. Rewrite non-GWT acceptance criteria in Given/When/Then format for selected items. Add PRD frontmatter block if it was a selected finding (Document ID, Version, Status, Requirement count). Add MoSCoW priority and complexity tags to requirements that were selected for tagging. Add risk indicators to Medium/High complexity requirements that were selected. Update or create the dependency map section if dependency gaps were selected.

2. Validation Verify structural integrity of all changes made during refinement

• Verify all REQ-NNN IDs are unique and sequential (no duplicates, no gaps)
• Verify all AC-NNN-M IDs are properly formatted and co-located under their parent requirements
• Verify MoSCoW tags are present on all requirements touched during refinement
• Verify Given/When/Then format on all acceptance criteria touched during refinement
• Check that no requirements were accidentally removed during editing (compare count with baseline from Step 1.1)

Phase 3: Readiness Gate Re-Score

1. Readiness Assessment Re-score the PRD after refinement to measure improvement

• Check frontmatter for an existing Readiness Score from a previous create-prd or refine-prd run
• If no previous score exists, inform the user: 'This PRD has no readiness score yet. Running the Implementation Readiness Gate for the first time.'
• Score these 4 dimensions (1-5 scale): Completeness (are all feature areas covered?), Testability (does every Must/Should requirement have verifiable ACs?), Clarity (could two developers read this and build the same thing?), Feasibility (are all requirements achievable within stated constraints?)
• Compute overall score: average of all 4 dimensions
• If a previous score exists, print delta: 'Readiness score: X.X -> Y.Y (improved/declined)'
• If the score dropped compared to previous, warn the user and identify which dimensions declined
• Update the Readiness Score in the PRD frontmatter

Phase 4: Output Management

1. PRD Update Save the refined PRD with updated metadata and changelog

• Bump version in frontmatter (increment patch: e.g. 1.0.0 -> 1.0.1, 1.2.3 -> 1.2.4)
• Update the PRD Health summary: recalculate requirement counts by priority, AC coverage percentage, risk flag count, dependency count
• Add changelog entry at the bottom of the PRD: date, version, list of changes made during this refinement
• Save the updated PRD to the same file path (overwrite the original)
• Print summary: number of changes made, new version, updated readiness score and delta (if applicable)

Expected Output

Format: Refined Product Requirements Document (PRD)

Structure:

• Updated PRD: Enhanced PRD with feedback incorporated and structural improvements
• Updated PRD Health Summary: Recalculated requirement counts by priority, AC coverage percentage, risk flags, and dependency count
• Updated Readiness Scorecard: Re-scored Implementation Readiness Gate with comparison to previous score (if applicable)
• Version History: Changelog entry documenting refinement date, version, and list of changes

Usage

/ensemble:refine-prd