Add backlog status vocabulary to the user-story template and a real-time disconnect edge-case item to the definition-of-ready checklist — two upstream-candidate lessons learned from the Scrum Poker App sprintsmain
| @@ -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 | |||
| --- | |||
| @@ -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 | | |||
| @@ -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 | |||
| @@ -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 | |||
| @@ -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 | |||
| @@ -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. | | |||
Powered by TurnKey Linux.