bmad 6.11

2026-08-14 17:08:24 +02:00
parent 0edaef0be7
commit 373857c868
268 changed files with 26063 additions and 0 deletions
@@ -0,0 +1,30 @@
+# Fix Sprint Status
+
+Rebuild `sprint-status.yaml` to a pristine, script-valid state when it is broken, hand-mangled, drifted from reality, or the user simply asks to fix it. Inference determines what the state *should* be; the user confirms it; the script writes it. Never write without the confirmation.
+
+1. **Scope the damage.** Run `sprint_plan.py validate` and share what it found. If even the epic files are missing or unparseable, say so — there is nothing to rebuild tracking against until planning artifacts exist.
+
+2. **Determine the true state by inference.** This is judgment work — fan out subagents in parallel, each gathering one kind of evidence, and have each return proposed `key=status` pairs with the evidence behind them:
+   - **Epics** — read the epic files in `{planning_artifacts}`: the authoritative work breakdown (which epics, stories, and retrospectives should exist at all)
+   - **Story files** — scan `{implementation_artifacts}`: which stories have files on disk, and what their content says about progress (acceptance criteria checked off, completion notes, review sections)
+   - **Code evidence** — git history and the codebase: commits or merged work referencing story keys are evidence a story is done or in progress
+   - **The current file** — salvage everything credible from the existing `sprint-status.yaml`, especially `action_items`, even when its structure is broken
+
+3. **Reconcile into one proposed state.** Merge the evidence into a single table: key → proposed status, evidence, and anything uncertain. When evidence conflicts or is thin, prefer the lower status and flag it — a false `done` costs more than a false `in-progress`.
+
+4. **Confirm with `{user_name}`.** Show the table. Highlight every entry that differs from the current file — especially downgrades — and every low-confidence call. Adjust to their corrections. Headless: halt with `blocked` instead of confirming.
+
+5. **Write pristine.** One command, from the confirmed table:
+
+   ```
+   uv run {skill-root}/scripts/sprint_plan.py generate \
+     --epic-file <path> [...] \
+     --status-file {implementation_artifacts}/sprint-status.yaml \
+     --stories-dir {implementation_artifacts} \
+     --project "{project_name}" --date "{date}" \
+     --fresh --set <key>=<status> [--set <key>=<status> ...]
+   ```
+
+   `--fresh` rebuilds the document cleanly (canonical vocabulary, standard header) while still carrying `action_items`; `--set` applies the confirmed statuses and is the one path allowed to downgrade. Only confirmed entries that differ from the fresh defaults need a `--set`.
+
+6. **Verify.** Run `validate` again (expect `valid: true`) and present the status view summary so the user sees the repaired state.
@@ -0,0 +1,25 @@
+# Generate Tracking
+
+Discovery is your call; everything after it is the script's.
+
+1. Identify the epic files. The gate inventory already surfaced them — typically `epics.md`, `epic-*.md`, or a sharded `epics/` folder in `{planning_artifacts}`, but trust content over filename. If both a whole document and a sharded version exist, ask which is current rather than guessing.
+2. Run the script, passing every epic file:
+
+   ```
+   uv run {skill-root}/scripts/sprint_plan.py generate \
+     --epic-file <path> [--epic-file <path> ...] \
+     --status-file {implementation_artifacts}/sprint-status.yaml \
+     --stories-dir {implementation_artifacts} \
+     --project "{project_name}" --date "{date}"
+   ```
+
+   `{date}` must be `MM-DD-YYYY HH:MM` — the format the staleness check parses. The script owns parsing (`## Epic N:` / `### Story N.M: Title` → kebab-case keys; fenced code blocks ignored), ordering (epic, its stories, its retrospective), merging with any existing file (preserve advanced statuses, never downgrade; legacy v6 values like `drafted`/`contexted` are normalized to their modern meaning, never reset; `action_items`, custom keys, and user comments carried through; `project_key`/`tracking_system`/`story_location` kept from the existing file unless overridden by flag), story-file detection (a story file on disk floors its status at `ready-for-dev`), atomic writes, and post-write validation. It prints a JSON report. Add `--dry-run` to preview — the report's `in_sync`, `new_entries`, `dropped_orphans`, `illegal`, and `legacy_mapped` fields answer "is tracking in sync?" without writing.
+
+3. Read the JSON report and act on it — this is where judgment re-enters:
+   - `warnings` about unparsed Epic/Story-like headings mean the epic file deviates from the standard format. Show the user, fix the headings together (or accept the omission), and rerun.
+   - `dropped_orphans` are entries that existed in the old status file but match nothing in the epics — usually renames. Each carries its old status; reconcile with the user, then transplant by rerunning with `--set <new-key>=<old-status>`.
+   - If the epics defeat the parser entirely (a format the regexes can't see), fall back to building the file yourself against `sprint-status-template.yaml`, and tell the user the deterministic path didn't apply.
+
+## Report
+
+Present the result from the script's JSON in `{communication_language}`: file path, epic/story counts, status breakdown, anything upgraded from disk. Suggest next steps — review the file, `bmad-build` to start the first story, rerun this skill anytime to refresh after epics change.
@@ -0,0 +1,20 @@
+# Readiness Gate
+
+Before generating any tracking, judge whether the plan can actually be built. If the user only asked to check readiness, this gate is the deliverable — report the verdict and stop.
+
+Inventory what planning actually exists: scan `{planning_artifacts}` and `{project_knowledge}` for intent and planning artifacts — briefs, PRFAQs, PRDs, specs, UX outputs, architecture, epics and stories. Identify documents by reading what they are, not by filename patterns; projects arrive with different artifact mixes and naming.
+
+Assess the plan as a whole against one question: **could a developer implement these epics without inventing decisions nothing records?**
+
+- Requirements and decisions in the intent artifacts trace forward into stories; stories trace back to recorded intent — flag orphans in both directions
+- Epics deliver user value and carry no forward dependencies; stories are independently completable
+- Architecture and UX decisions the stories rely on are recorded somewhere, not assumed
+- Conflicts between artifacts (a spec and an epic disagreeing) are surfaced, not silently resolved
+
+A missing document type is only a finding if stories depend on decisions nothing records — a project with no UX artifact and no UI stories is fine.
+
+Deliver a verdict:
+
+- **PASS** — state it in one line; for the full sprint-planning intent, continue with `generate-tracking.md`
+- **CONCERNS** — list them briefly with where each gap lives; ask `{user_name}` whether to proceed anyway or fix first
+- **FAIL** — the plan is not implementable as recorded. Present findings ordered by severity, name the skill that fixes each (the relevant plan skill, or `bmad-correct-course` for cross-cutting changes), offer to save the findings to `{planning_artifacts}/implementation-readiness.md`, and stop
@@ -0,0 +1,14 @@
+# Status View
+
+When the user wants to know where the sprint stands ("show sprint status", "where are we"), run:
+
+```
+uv run {skill-root}/scripts/sprint_plan.py status \
+  --status-file {implementation_artifacts}/sprint-status.yaml --date "{date}"
+```
+
+`{date}` is `MM-DD-YYYY HH:MM`. The script computes everything: counts by status (legacy values like `drafted` mapped transparently and reported in `legacy_mapped`), risk flags (stale file, orphaned stories, in-progress epics without stories, stories waiting in review, unrecognized keys), open action items from retrospectives, and the next recommended action by fixed priority — resume in-progress → review what's in review → start the next ready or backlog story → run an open retrospective → all done. If the file is missing, the script says so — offer to run sprint planning to create it.
+
+Render the JSON as a compact summary in `{communication_language}`: counts, risks, open action items, and the recommendation with its story key. Offer to run the recommended skill. Surface `illegal` and `unrecognized` entries and the script's `warnings` (malformed action items land there); if the user gives corrections, apply them via the fix flow rather than ad-hoc edits. No time estimates — status, risks, and next steps only.
+
+If the script errors — malformed YAML, a hand-edited structure it can't parse, anything — do not stop at the error. Read `sprint-status.yaml` yourself, apply best judgment to give the user the same summary (counts, risks, next recommended action), tell them the deterministic path failed and why, and offer the fix flow (`fix-sprint-status.md`) so the script works next time.
@@ -0,0 +1,10 @@
+# Validate
+
+When the user asks whether `sprint-status.yaml` is well-formed, run:
+
+```
+uv run {skill-root}/scripts/sprint_plan.py validate \
+  --status-file {implementation_artifacts}/sprint-status.yaml
+```
+
+Never writes; exits 0 whether valid or not. Report `valid` in one line. If `problems` is non-empty, list them plainly (each names the key or field at fault) and offer the fix flow (`fix-sprint-status.md`). If `legacy_mapped` is non-empty, note the file still uses v6 status names and that any regenerate will rewrite them to the modern vocabulary — progress is preserved either way.