8d32a5c2
docs: require reuse and ownership evidence in sprint delivery
a73x 2026-09-06 06:53
Commit message
docs/native-sprint-workflow.md
| Old | New | ||
|---|---|---|---|
| @@ -10,6 +10,8 @@ the [delivery plan](superpowers/plans/2026-09-05-native-tiling.md) breaks it int | |||
| 10 | packages. Keep one sprint active, ending in a working demo and explicit acceptance. | 10 | packages. Keep one sprint active, ending in a working demo and explicit acceptance. |
| 11 | 11 | ||
| 12 | 1. **Review and scope.** Read the previous sprint's actions in [RETRO.md](../RETRO.md). | 12 | 1. **Review and scope.** Read the previous sprint's actions in [RETRO.md](../RETRO.md). |
| 13 | Produce the reuse and ownership map required by the shared skill, using the | ||
| 14 | [component briefs](component-ownership.md) and actual code/callers as evidence. | ||
| 13 | Define the smallest useful deliverable, its acceptance scenarios, and what | 15 | Define the smallest useful deliverable, its acceptance scenarios, and what |
| 14 | belongs to later sprints. Use existing agreements for material scope and | 16 | belongs to later sprints. Use existing agreements for material scope and |
| 15 | destructive-action semantics; clarify only unresolved points before | 17 | destructive-action semantics; clarify only unresolved points before |
| @@ -43,10 +45,11 @@ packages. Keep one sprint active, ending in a working demo and explicit acceptan | |||
| 43 | 4. **Build a functional slice.** Establish the smallest model/interface contract, | 45 | 4. **Build a functional slice.** Establish the smallest model/interface contract, |
| 44 | then connect actual input, rendering, and daemon behavior. Keep changes small | 46 | then connect actual input, rendering, and daemon behavior. Keep changes small |
| 45 | enough to review. Avoid expanding into later sprint features. | 47 | enough to review. Avoid expanding into later sprint features. |
| 46 | 5. **Resolve concrete review findings.** The reviewer supplies a failing scenario, | 48 | 5. **Resolve concrete review findings.** Apply the shared skill's correctness and |
| 47 | consequence, and expected result directly to the implementer. The implementer | 49 | structural review criteria. The reviewer supplies a scenario or structural |
| 48 | returns a fix and evidence, or a reason the finding does not apply. Root | 50 | finding, consequence, and expected result directly to the implementer. The |
| 49 | adjudicates disagreement against requirements and observed behavior. Agreement | 51 | implementer returns a fix and evidence, or a reason the finding does not apply. |
| 52 | Root adjudicates disagreement against requirements and observed behavior. Agreement | ||
| 50 | is not a substitute for independent validation. | 53 | is not a substitute for independent validation. |
| 51 | 6. **Validate through real boundaries.** Drive ordinary SDL events into an isolated | 54 | 6. **Validate through real boundaries.** Drive ordinary SDL events into an isolated |
| 52 | GUI using `test/native_tiling.py`'s Rig. Compare actual framebuffer pixels and | 55 | GUI using `test/native_tiling.py`'s Rig. Compare actual framebuffer pixels and |
docs/skills/sprint-delivery/SKILL.md
| Old | New | ||
|---|---|---|---|
| @@ -41,28 +41,60 @@ commit IDs, or temporary service URLs in this skill. | |||
| 41 | 41 | ||
| 42 | ## Run a bounded sprint | 42 | ## Run a bounded sprint |
| 43 | 43 | ||
| 44 | 1. **Scope and acceptance.** Choose the smallest functional deliverable within | 44 | Planner, implementer and reviewer are responsibilities with required outputs. |
| 45 | the user's authorized plan. Define observable acceptance scenarios and carry | 45 | Assign them to people or agents using the pairing and fallback below; no separate |
| 46 | forward applicable retrospective actions. Clarify material unknowns early; | 46 | persona or additional agent is required for each step. Prefer less maintained |
| 47 | continue independent work while waiting. Existing authorization still applies. | 47 | code, clear ownership and small interfaces. Each new abstraction must earn its |
| 48 | place by removing duplication or simplifying dependencies. | ||
| 49 | |||
| 50 | 1. **Plan from existing code.** Choose the smallest functional deliverable within | ||
| 51 | the user's authorized plan. Before proposing new code, search relevant modules | ||
| 52 | and callers, verify what their APIs actually do, and identify reusable behavior, | ||
| 53 | duplicated rules and refactors that would simplify the slice. Record a short | ||
| 54 | **reuse and ownership map** in the plan: | ||
| 55 | |||
| 56 | | Behavior or rule | Existing implementation and callers | Intended owner | Reuse, refactor or add; what can be deleted | | ||
| 57 | | --- | --- | --- | --- | | ||
| 58 | |||
| 59 | Cite actual file/symbol evidence. If nothing suitable exists, record where you | ||
| 60 | searched. Explain why an existing owner cannot take any proposed new module's | ||
| 61 | responsibility. Keep domain rules with their owner; input, rendering, storage | ||
| 62 | and transport adapters should use those rules. Assess whether separating policy | ||
| 63 | from external dependencies would help this slice; use the smallest justified | ||
| 64 | boundary. Define observable acceptance scenarios and carry forward applicable | ||
| 65 | retrospective actions. Clarify material unknowns early and continue independent | ||
| 66 | work while waiting. Existing authorization still applies. | ||
| 48 | 2. **Opening cleanup.** Inspect the touched code for small refactors that help | 67 | 2. **Opening cleanup.** Inspect the touched code for small refactors that help |
| 49 | the slice. Review, validate, and commit these separately within existing | 68 | the slice. Review, validate, and commit these separately within existing |
| 50 | authorization. If the code is ready, say so; there is no cleanup quota. | 69 | authorization. If the code is ready, say so; there is no cleanup quota. |
| 51 | 3. **Delegate implementation and review.** Use the pairing below. Deliver through | 70 | 3. **Delegate implementation and review.** Use the pairing below. Deliver through |
| 52 | actual user interactions and system boundaries, then integrate the result. | 71 | actual user interactions and system boundaries. The implementer follows the |
| 53 | 4. **Closing cleanup.** Explicitly review duplication, obsolete paths, temporary | 72 | ownership map, reuses existing behavior and removes superseded paths. Report |
| 54 | scaffolding, and unnecessary state. Refactor what the slice exposed. Record | 73 | discoveries that change the plan and update the map before extending scope. |
| 55 | retained debt with its location, consequence, and next owner or trigger. | 74 | 4. **Review correctness and structure.** The reviewer checks behavior and failure |
| 75 | paths, duplicated rules, misplaced responsibilities, unnecessary state, | ||
| 76 | excessive dependencies, obsolete code and opportunities to delete code. Supply | ||
| 77 | concrete evidence and resolve findings through the exchange below. Review net | ||
| 78 | production-code and dependency changes; explain growth and its benefit rather | ||
| 79 | than treating line count as a quota. Complete closing cleanup and integrate the | ||
| 80 | result. Record retained debt with its location, consequence, and next owner or | ||
| 81 | trigger. "Architecture reviewed" alone is not evidence: identify the rule, | ||
| 82 | owner, dependency or removable path and its disposition. | ||
| 56 | 5. **Validate and demonstrate.** Run required repository gates and meaningful | 83 | 5. **Validate and demonstrate.** Run required repository gates and meaningful |
| 57 | checks for the change. Independently verify real behavior beyond agent | 84 | checks for the change. Independently verify real behavior beyond agent |
| 58 | agreement. Freeze source before final checks; rerun affected checks after | 85 | agreement. Prove claimed architectural boundaries with an appropriate check, |
| 59 | meaningful changes. Demonstrate the working result, including relevant failure | 86 | such as policy tests running without the external library or service that its |
| 60 | paths. A recording must show the actual application, not a slideshow. | 87 | adapter uses; moving files alone does not establish isolation. Freeze source |
| 88 | before final checks; rerun affected checks after meaningful changes. Demonstrate | ||
| 89 | the working result, including relevant failure paths. A recording must show | ||
| 90 | the actual application, not a slideshow. | ||
| 61 | 6. **Close and hand off.** Commit validated work within existing authorization. | 91 | 6. **Close and hand off.** Commit validated work within existing authorization. |
| 62 | Update the spec/plan status and `RETRO.md`: results, lessons, retained debt, | 92 | Update the spec/plan and ownership map to match the delivered code. Record |
| 63 | and checkable next-sprint actions. Record demo acceptance only when given; | 93 | results, removed duplication/paths, justified retained debt, lessons, and |
| 64 | test success does not imply user acceptance. Begin the next sprint only when | 94 | checkable next-sprint actions in `RETRO.md`; give each open item an owner or |
| 65 | authorized, preserving any acceptance requirement in the agreed plan. | 95 | concrete trigger. Record demo acceptance only when given; test success does not |
| 96 | imply user acceptance. Begin the next sprint only when authorized, preserving | ||
| 97 | any acceptance requirement in the agreed plan. | ||
| 66 | 98 | ||
| 67 | ## Economical pairing | 99 | ## Economical pairing |
| 68 | 100 | ||
| @@ -75,9 +107,9 @@ commit IDs, or temporary service URLs in this skill. | |||
| 75 | constraints, acceptance checks, and its partner's name. They should read only | 107 | constraints, acceptance checks, and its partner's name. They should read only |
| 76 | necessary code. The main session coordinates, integrates, and independently | 108 | necessary code. The main session coordinates, integrates, and independently |
| 77 | validates; assign each implementation or investigation one owner. | 109 | validates; assign each implementation or investigation one owner. |
| 78 | - The reviewer sends concrete findings directly to the implementer: trigger, | 110 | - The reviewer sends concrete findings directly to the implementer: trigger or |
| 79 | consequence, and expected behavior. The implementer returns a fix and evidence | 111 | structural evidence, consequence, and expected result. The implementer returns |
| 80 | or a reason the finding does not apply. Continue focused exchanges until | 112 | a fix and evidence or a reason the finding does not apply. Continue focused exchanges until |
| 81 | findings are resolved; root adjudicates persistent disagreement against the | 113 | findings are resolved; root adjudicates persistent disagreement against the |
| 82 | spec and observations. Re-review changed parts and unresolved findings rather | 114 | spec and observations. Re-review changed parts and unresolved findings rather |
| 83 | than repeating a broad review each round. | 115 | than repeating a broad review each round. |