diff --git a/.ai/checklists/definition-of-ready.md b/.ai/checklists/definition-of-ready.md index 77695eb..bc08b95 100644 --- a/.ai/checklists/definition-of-ready.md +++ b/.ai/checklists/definition-of-ready.md @@ -5,6 +5,7 @@ - [ ] Acceptance criteria exist - [ ] Dependencies are known - [ ] Risks are identified +- [ ] **If real-time or WebSocket feature:** disconnect, reconnect, and stale-presence scenarios are identified and either in scope or explicitly deferred. - [ ] Test approach is known --- diff --git a/.ai/evolution/learning-log.md b/.ai/evolution/learning-log.md index 531a284..48a16e0 100644 --- a/.ai/evolution/learning-log.md +++ b/.ai/evolution/learning-log.md @@ -5,3 +5,5 @@ Use this file to track durable lessons learned during projects. | Date | Source Project | Scope | Lesson | Proposed Update | Promotion Status | |---|---|---|---|---|---| | YYYY-MM-DD | Boilerplate baseline | upstream-candidate | Use controlled self-evolution instead of silent rewrites. | Added evolution protocol. | Approved | +| 2026-06-03 | ai-development-team-agent-pack (Scrum Poker App) | upstream-candidate | Backlog status labels should follow a defined vocabulary (`Proposed`, `Ready`, `In Progress`, `Done (Sprint N)`, `Deferred`) to preserve sprint traceability. | Added Status Convention section to `templates/user-story.md`. | Approved — EVOLVE-20260603-001 | +| 2026-06-03 | ai-development-team-agent-pack (Scrum Poker App) | upstream-candidate | Real-time/WebSocket stories must identify disconnect and reconnect edge cases at refinement, not mid-sprint. | Added conditional checklist item to `checklists/definition-of-ready.md`. | Approved — EVOLVE-20260603-002 | diff --git a/.ai/evolution/proposals/2026-06-03-backlog-status-vocabulary.md b/.ai/evolution/proposals/2026-06-03-backlog-status-vocabulary.md new file mode 100644 index 0000000..c90b2a3 --- /dev/null +++ b/.ai/evolution/proposals/2026-06-03-backlog-status-vocabulary.md @@ -0,0 +1,83 @@ +# Improvement Proposal — Backlog Status Vocabulary + +## Proposal ID + +EVOLVE-20260603-001 + +## Scope + +upstream-candidate + +## Source Project + +ai-development-team-agent-pack (Scrum Poker App — Sprints 1–3) + +## File To Update + +- `./.ai/templates/user-story.md` + +## Current Problem + +The user-story template has no guidance on what values are valid for story status, and no convention for recording which sprint completed a story. Teams default to ad-hoc labels (`Done`, `To Do`, `In Progress`, etc.) that lose sprint traceability and make it hard to reconstruct what was delivered when. + +## Evidence + +The Scrum Poker App backlog (`./.ai/project/backlog.md`) used `Done (Sprint N)` and `Proposed` organically across three sprints. When reviewing the backlog, sprint traceability was immediately readable from the status column. No equivalent guidance exists in the template. + +## Proposed Change + +Add a **Status Convention** section to the user-story template, immediately after the Story/Acceptance Criteria fields: + +```markdown +## Status + +Proposed | Ready | In Progress | Done (Sprint N) | Deferred + +**Vocabulary:** +- `Proposed` — idea not yet approved by the Product Owner for planning. +- `Ready` — meets the Definition of Ready; approved for a sprint. +- `In Progress` — actively being worked in the current sprint. +- `Done (Sprint N)` — accepted by the Product Owner; record the sprint number for traceability. +- `Deferred` — intentionally postponed; record the reason in Notes. +``` + +## Why This Generalizes + +Any project using this template will produce backlogs. Consistent status vocabulary is a baseline need regardless of domain, technology, or team size. Capturing the sprint number at completion is low effort and pays off in retrospectives and audits. + +## Benefit + +- Agents produce consistent backlog entries without inventing ad-hoc status labels. +- Sprint traceability is preserved at zero extra cost. +- Retrospectives and release notes can be generated from the backlog without disambiguation. + +## Risk + +Low. This is additive guidance only. Existing stories using other labels are not invalidated. + +## Rollback Plan + +Remove the Status Convention section from `user-story.md`. No other files are affected. + +## Validation + +The convention is working when: +- New backlog entries consistently use one of the five defined statuses. +- Agents do not invent alternative labels. +- Sprint numbers appear in `Done` entries after each sprint. + +## Product Owner Approval + +Approved + +## Promotion Decision + +Promote upstream + +## Applied Date + +2026-06-03 + +## Baseline Version Impact + +Patch diff --git a/.ai/evolution/proposals/2026-06-03-realtime-disconnect-edge-cases.md b/.ai/evolution/proposals/2026-06-03-realtime-disconnect-edge-cases.md new file mode 100644 index 0000000..bf3dd34 --- /dev/null +++ b/.ai/evolution/proposals/2026-06-03-realtime-disconnect-edge-cases.md @@ -0,0 +1,75 @@ +# Improvement Proposal — Real-Time Disconnect Edge Cases in Definition of Ready + +## Proposal ID + +EVOLVE-20260603-002 + +## Scope + +upstream-candidate + +## Source Project + +ai-development-team-agent-pack (Scrum Poker App — Epic 3, Story 5) + +## File To Update + +- `./.ai/checklists/definition-of-ready.md` + +## Current Problem + +The Definition of Ready checklist has no prompt for identifying connection-state edge cases in real-time or WebSocket features. These edge cases (participant disconnects, reconnects, stale presence state) are consistently discovered mid-sprint rather than during refinement, causing scope creep and blocking stories that assumed clean connection state. + +## Evidence + +Scrum Poker App Epic 3 (Real-Time Presence): Stories 1–4 were completed in Sprints 1–2. Story 5 — "away participants excluded from the 'everyone has voted' check" — was discovered mid-sprint as a gap only after the disconnect indicator was built. The original story for disconnect detection did not ask whether downstream logic (vote reveal gating) correctly handled the disconnected state. Story 5 entered the backlog as `Proposed` and was not scheduled, leaving a functional gap that a refinement question would have surfaced. + +## Proposed Change + +Add a conditional item to the Definition of Ready checklist: + +```markdown +- [ ] **If real-time or WebSocket feature:** disconnect, reconnect, and stale-presence scenarios are identified and either in scope or explicitly deferred. +``` + +Insert after the existing `- [ ] Risks are identified` line. + +## Why This Generalizes + +Any collaborative or multiplayer application with live presence (chat, voting tools, collaborative editors, dashboards) will encounter these edge cases. The question is domain-neutral: "what happens when a participant drops?" This belongs at the refinement gate so it is never accidentally scoped out. + +## Benefit + +- Teams identify disconnect/reconnect scope during refinement, not mid-sprint. +- Blocking dependencies between real-time stories are visible before sprint planning. +- Reduces the risk of shipping presence features with silent gaps in connection-state logic. + +## Risk + +Low. The item is conditional and explicitly scoped to real-time features. It will not add friction to stories that have no real-time component. + +## Rollback Plan + +Remove the added checklist item from `definition-of-ready.md`. No other files are affected. + +## Validation + +The change is working when: +- Real-time stories entering a sprint have an explicit note in Acceptance Criteria or Notes about disconnect/reconnect handling. +- No mid-sprint scope surprises about connection-state edge cases occur in the next real-time feature. + +## Product Owner Approval + +Approved + +## Promotion Decision + +Promote upstream + +## Applied Date + +2026-06-03 + +## Baseline Version Impact + +Patch diff --git a/.ai/templates/user-story.md b/.ai/templates/user-story.md index 94aaba8..9489f35 100644 --- a/.ai/templates/user-story.md +++ b/.ai/templates/user-story.md @@ -9,6 +9,17 @@ As a [user], I want [capability], so that [benefit]. - [ ] Criteria 1 - [ ] Criteria 2 +## Status + +Proposed | Ready | In Progress | Done (Sprint N) | Deferred + +**Vocabulary:** +- `Proposed` — idea not yet approved by the Product Owner for planning. +- `Ready` — meets the Definition of Ready; approved for a sprint. +- `In Progress` — actively being worked in the current sprint. +- `Done (Sprint N)` — accepted by the Product Owner; record the sprint number for traceability. +- `Deferred` — intentionally postponed; record the reason in Notes. + ## Notes ## Test Ideas diff --git a/.ai/version.md b/.ai/version.md index 80002cd..370cb41 100644 --- a/.ai/version.md +++ b/.ai/version.md @@ -2,7 +2,7 @@ ## Current Baseline -0.1.0 +0.1.1 ## Purpose @@ -19,3 +19,4 @@ Track the reusable AI system baseline for this boilerplate repository. | Version | Date | Notes | |---|---|---| | 0.1.0 | 2026-06-03 | Initial boilerplate baseline with upstream promotion workflow. | +| 0.1.1 | 2026-06-03 | EVOLVE-20260603-001: backlog status vocabulary in user-story template. EVOLVE-20260603-002: real-time disconnect edge case item in definition-of-ready checklist. |