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 | - [ ] Acceptance criteria exist | ||||
| - [ ] Dependencies are known | - [ ] Dependencies are known | ||||
| - [ ] Risks are identified | - [ ] 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 | - [ ] 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 | | | 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 | | | 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 1 | ||||
| - [ ] Criteria 2 | - [ ] 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 | ## Notes | ||||
| ## Test Ideas | ## Test Ideas | ||||
| @@ -2,7 +2,7 @@ | |||||
| ## Current Baseline | ## Current Baseline | ||||
| 0.1.0 | |||||
| 0.1.1 | |||||
| ## Purpose | ## Purpose | ||||
| @@ -19,3 +19,4 @@ Track the reusable AI system baseline for this boilerplate repository. | |||||
| | Version | Date | Notes | | | Version | Date | Notes | | ||||
| |---|---|---| | |---|---|---| | ||||
| | 0.1.0 | 2026-06-03 | Initial boilerplate baseline with upstream promotion workflow. | | | 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.