bmad-correct-course

# Correct Course - Sprint Change Management Workflow **Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal. **Your Role:** You are a Developer navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff. ## Conventions - Bare paths (e.g. `checklist.md`) resolve from the skill root. - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives). - `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents. - `{skill-name}` resolves to the skill directory's basename. ## On Activation ### Step 1: Resolve the Workflow Block Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow` **If the script is not found**, BMad is not set up here. Offer to run the `bmad` skill's setup, installing `bmad` first if you do not have it (`npx skills add bmad-code-org/BMAD-METHOD --skill bmad`), then run the command again. **If it fails for any other reason**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding. ### Step 3: Load Persistent Facts Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. ### Step 4: Load Config Run: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative` - Script not found, or no `output_folder`: BMad is not set up here. Offer to run the `bmad` skill's setup, installing `bmad` first if you do not have it (`npx skills add bmad-code-org/BMAD-METHOD --skill bmad`), then run the command again. - No `active_initiative`: hand off to the `bmad` skill to set or create one, then run the command again and continue. - `date` as system-generated current datetime - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style - DOCUMENT OUTPUT: A Sprint Change Proposal with clear, actionable changes. ### Step 5: Greet the User Greet the user. ### Step 6: Execute Append Steps Execute each entry in `{workflow.activation_steps_append}` in order. Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed. ## Paths - `default_output_file` = `{output_folder}/{active_initiative}/change-{slug}/change-{slug}.md`, `{slug}` the change's title in kebab-case ## Input Files Look in `{output_folder}/{active_initiative}/` first, then `{output_folder}/`. | Input | Path | Load Strategy | |-------|------|---------------| | PRD | `prd-*/prd-*.md` | FULL_LOAD | | Architecture | `architecture-*/architecture-*.md` | FULL_LOAD | | UX Design | `ux-*/`: `DESIGN.md` and `EXPERIENCE.md` | FULL_LOAD | | Spec | `spec-*/spec-*.md` and the companions it lists | FULL_LOAD | | Project Context | `AGENTS.md` in the affected repo (the `bmad:context` block) | FULL_LOAD | ## Execution ### Document Discovery - Loading Project Artifacts **Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts. **Discovery Process for FULL_LOAD documents (PRD, Architecture, UX Design, Spec):** 1. **Find each document by type** - the folder and main file patterns in Input Files 2. **If the main file is an index of section files beside it**: - Read ALL section files listed in the index - Process the combined content as a single document **Discovery Process for Project Context:** 1. **Read `AGENTS.md`** in the repo the change affects — the block between the `bmad:context` markers carries the policy, frozen paths, and conventions a course correction must respect. 2. **Follow only the pointers that relate to the impacted areas** — nested component files or linked rule files listed under "Where things are". Do not load them all. 3. **This document is optional** — skip if the repo has no `AGENTS.md` (greenfield projects). **Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc. **Missing documents**: Not all documents may exist. A PRD or a spec is essential; Architecture, UX Design, and Project Context are loaded if available. HALT if neither a PRD nor a spec can be found. <workflow> <step n="1" goal="Initialize Change Navigation"> <action>Confirm change trigger and gather user description of the issue</action> <action>Ask: "What specific issue or change has been identified that requires navigation?"</action> <action>Verify access to project documents:</action> - PRD (Product Requirements Document) or spec — required - Architecture documentation — optional, load if available - UI/UX specifications — optional, load if available <action>Ask the user to describe the epics and stories the change affects: what each covers and where it stands</action> <action>Ask user for mode preference:</action> - **Incremental** (recommended): Refine each edit collaboratively - **Batch**: Present all changes at once for review <action>Store mode selection for use throughout workflow</action> <action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action> <action if="neither a PRD nor a spec is available">HALT: "Need access to a PRD or a spec to assess change impact. Please ensure one is accessible. Architecture and UI/UX will be used if available."</action> </step> <step n="2" goal="Execute Change Analysis Checklist"> <action>Read fully and follow the systematic analysis from: checklist.md</action> <action>Work through each checklist section interactively with the user</action> <action>Record status for each checklist item:</action> - [x] Done - Item completed successfully - [N/A] Skip - Item not applicable to this change - [!] Action-needed - Item requires attention or follow-up <action>Maintain running notes of findings and impacts discovered</action> <action>Present checklist progress after each major section</action> <action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action> </step> <step n="3" goal="Draft Specific Change Proposals"> <action>Based on checklist findings, create explicit edit proposals for each identified artifact</action> <action>For Story changes:</action> - Show old → new text format - Include story ID and section being modified - Provide rationale for each change - Example format: ``` Story: [STORY-123] User Authentication Section: Acceptance Criteria OLD: - User can log in with email/password NEW: - User can log in with email/password - User can enable 2FA via authenticator app Rationale: Security requirement identified during implementation ``` <action>For PRD modifications:</action> - Specify exact sections to update - Show current content and proposed changes - Explain impact on MVP scope and requirements <action>For Architecture changes:</action> - Identify affected components, patterns, or technology choices - Describe diagram updates needed - Note any ripple effects on other components <action>For UI/UX specification updates:</action> - Reference specific screens or components - Show wireframe or flow changes needed - Connect changes to user experience impact <check if="mode is Incremental"> <action>Present each edit proposal individually</action> <action>HALT and give the user a choice: - **Approve** — accept this proposal - **Edit** — refine this proposal - **Skip** — drop this proposal </action> <action>If the user chooses **Approve**, keep the proposal. If they choose **Edit**, refine it with them. If they choose **Skip**, drop it. Continue to the next proposal.</action> </check> <action if="mode is Batch">Collect all edit proposals and present together at end of step</action> </step> <step n="4" goal="Generate Sprint Change Proposal"> <action>Compile comprehensive Sprint Change Proposal document with following sections:</action> <action>Section 1: Issue Summary</action> - Clear problem statement describing what triggered the change - Context about when/how the issue was discovered - Evidence or examples demonstrating the issue <action>Section 2: Impact Analysis</action> - Epic Impact: Which epics are affected and how - Story Impact: Current and future stories requiring changes - Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates - Technical Impact: Code, infrastructure, or deployment implications <action>Section 3: Recommended Approach</action> - Present chosen path forward from checklist evaluation: - Direct Adjustment: Modify/add stories within existing plan - Potential Rollback: Revert completed work to simplify resolution - MVP Review: Reduce scope or modify goals - Provide clear rationale for recommendation - Include effort estimate, risk assessment, and timeline impact <action>Section 4: Detailed Change Proposals</action> - Include all refined edit proposals from Step 3 - Group by artifact type (Stories, PRD, Architecture, UI/UX) - Ensure each change includes before/after and justification <action>Section 5: Implementation Handoff</action> - Categorize change scope: - Minor: Direct implementation by Developer agent - Moderate: Backlog reorganization needed (PO/DEV) - Major: Fundamental replan required (PM/Architect) - List the epic and story changes (added, removed, resequenced, or rescoped) for the user to apply with `bmad-ticket` - Specify handoff recipients and their responsibilities - Define success criteria for implementation <action>Present complete Sprint Change Proposal to user</action> <action>Write Sprint Change Proposal document to {default_output_file}</action> <action>HALT and give the user a choice: - **Continue** — proceed to approval - **Edit** — revise the proposal first </action> <action>If the user chooses **Edit**, revise the proposal with them and write the updated document before continuing.</action> </step> <step n="5" goal="Finalize and Route for Implementation"> <action>Get explicit user approval for complete proposal</action> <ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask> <check if="no or revise"> <action>Gather specific feedback on what needs adjustment</action> <action>Return to appropriate step to address concerns</action> <goto step="3">If changes needed to edit proposals</goto> <goto step="4">If changes needed to overall proposal structure</goto> </check> <check if="yes the proposal is approved by the user"> <action>Finalize Sprint Change Proposal document</action> <action>Determine change scope classification:</action> - **Minor**: Can be implemented directly by Developer agent - **Moderate**: Requires backlog reorganization and PO/DEV coordination - **Major**: Needs fundamental replan with PM/Architect involvement <action>Provide appropriate handoff based on scope:</action> </check> <check if="Minor scope"> <action>Route to: Developer agent for direct implementation</action> <action>Deliverables: Finalized edit proposals and implementation tasks</action> </check> <check if="Moderate scope"> <action>Route to: Product Owner / Developer agents</action> <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action> </check> <check if="Major scope"> <action>Route to: Product Manager / Solution Architect</action> <action>Deliverables: Complete Sprint Change Proposal + escalation notice</action> <action>Confirm handoff completion and next steps with user</action> <action>Document handoff in workflow execution log</action> </check> </step> <step n="6" goal="Workflow Completion"> <action>Summarize workflow execution:</action> - Issue addressed: {{change_trigger}} - Change scope: {{scope_classification}} - Artifacts modified: {{list_of_artifacts}} - Routed to: {{handoff_recipients}} <action>Confirm all deliverables produced:</action> - Sprint Change Proposal document - Specific edit proposals with before/after - Implementation handoff plan <action>Report workflow completion to user: "Correct Course workflow complete!"</action> <action>Remind user of success criteria and next steps for Developer agent</action> <action>Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action> </step> </workflow>