# Product Backlog

Index of all epics, ordered by priority (top = highest priority). Each epic is its own file under `backlog/epics/`.

| Order | Epic | File | Status |
|---|---|---|---|
| 1 | End-to-End Text Rendering Slice | `epics/01_end_to_end_text_rendering_slice.md` | In Progress (2 of 3 stories Done — Sprint 1) |
| 2 | Template Designer GUI Foundation | `epics/02_template_designer_gui_foundation.md` | Done (6 of 6 stories — Sprint 4) |
| 3 | CSV Integration and Field Mapping | `epics/03_csv_integration_and_field_mapping.md` | Done (4 of 4 stories — Sprint 4) |
| 4 | CLI Rendering Engine and Debenu Integration | `epics/05_cli_rendering_engine_and_debenu_integration.md` | In Progress (5 of 7 stories Done — Sprint 1-3) |
| 5 | Live Preview and Record Navigation | `epics/04_live_preview_and_record_navigation.md` | Ready |
| 6 | Layout Efficiency and Operator Tooling | `epics/06_layout_efficiency_and_operator_tooling.md` | Not Started |
| 7 | Dynamic and Network Image Handling | `epics/07_dynamic_and_network_image_handling.md` | Not Started |
| 8 | Composite Address Controls and Mixed-Content Text | `epics/08_composite_address_controls.md` | Not Started (requirements gathered 2026-09-29, not yet sized) |

## Notes
- Prioritization favors the requirements document's recommended vertical slicing: deliver a text-only end-to-end workflow first, then layer images, shapes, and operator-efficiency tooling.
- The CLI/rendering epic now sits ahead of preview in the ordered backlog because it is a direct dependency for the first demonstrable PDF-generating slice.
- The top five epics now contain sprint-ready stories for the first one to two sprints of MVP work.
- Open requirement questions that may affect ordering: path strategy for template assets and timeout behavior for slow UNC shares.

### Sprint 1 Review outcome (2026-09-11)
- Sprint 1's 5 committed stories are Done; verification detail and any caveats are recorded story-by-story in `backlog/epics/01_end_to_end_text_rendering_slice.md` and `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`. Full summary: `backlog/sprints/sprint-1.md` (Sprint Review Outcome section).
- Recommend pulling "Time-box the first high-volume benchmark" (`epics/05`, 5 points, Ready) early in Sprint 2 refinement/planning alongside whatever else is pulled from epics 2-3 — it's a cheap, high-information risk check that's now overdue (not re-run since Sprint 1 Batch 2) rather than a reason to reorder the epic list itself.
- New stories added from this review: "Harden production configuration delivery for CLI runtime settings" (`epics/05`) and "Surface real warning counts in progress and completion reporting" (`epics/07`). Neither is urgent for Sprint 2's likely candidates (epics 2-3 touch neither CLI configuration nor warnings).
- The two open impediments (template asset path strategy; UNC timeout/retry behavior, both in `logs/impediment_log.md`) do **not** block Sprint 2's likely candidate epics (2 and 3) — neither of those epics' stories touch images or network asset paths. They only need to be resolved before epic 7 (Dynamic and Network Image Handling) stories are pulled into a sprint; recommend deciding them during backlog refinement once epic 7 nears the top of the backlog, per "delay firm decisions to the last responsible moment," rather than treating them as urgent now.

### Sprint 2 Review outcome (2026-09-18)
- Sprint 2's 5 committed stories (the full Template Designer GUI Foundation epic plus the high-volume benchmark spike, 19 points) are Done; verification detail is recorded story-by-story in `backlog/epics/02_template_designer_gui_foundation.md` and `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`. Full summary: `backlog/sprints/sprint-2.md` (Sprint Review Outcome section).
- **Material finding, not a defect in this sprint's delivery:** the benchmark spike found the render path badly misses the product's "100,000 records at 300 DPI in under 10 minutes" hard constraint — throughput degrades from ~399 rec/s to ~15 rec/s and falling at realistic scale, projecting 45-90+ minutes for a full 100k run (5x-10x+ over target), most likely due to Debenu Quick PDF Library 10.13's own document model rather than this repo's code. Full data: `code/BENCHMARK.md`. **Strong recommendation: prioritize the new "Investigate and address high-volume render throughput degradation" story (`epics/05`, Ready, not yet sized) at or near the top of Sprint 3**, ahead of or alongside CSV Integration — this is a High-impact item that directly threatens a hard product constraint (`project_config.md`) and gets worse, not better, the longer higher-volume-dependent feature work (CSV integration at scale, eventual 1M-record ceiling) is built on top of an unfixed render path.
- The stretch item ("Load CSV headers and sample rows into the desktop app," epic 3) was not pulled in Sprint 2; it remains the natural first CSV Integration story for Sprint 3.
- No changes to the two open impediments (template path strategy; UNC timeout/retry) — still non-blocking for Sprint 3's likely candidates (CSV Integration and the throughput investigation touch neither template image paths nor network shares).

### Sprint 3 planning outcome (2026-09-21)
- `scrum-master` facilitated with `dev-team` sizing; committed 18 points against a 19-20 point velocity range: the throughput-degradation story (newly sized at 8 points — see `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`), then "Load CSV headers and sample rows," "Create a dynamic text token from a CSV column," and "Re-map an existing dynamic field" (epic 3, in backlog order). Full plan: `backlog/sprints/sprint-3.md`.
- Not committed (capacity discipline): "Collapse blank optional address lines consistently" (5 pts, would overcommit) and "Harden production configuration delivery for CLI runtime settings" (2 pts, not urgent) — both clean pulls for Sprint 4.

### Sprint 3 Review outcome (2026-09-22)
- All 4 committed Sprint 3 stories (18/18 points) are Done; each is verified against its acceptance criteria with real, non-simulated evidence, recorded story-by-story in `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` (throughput story) and `backlog/epics/03_csv_integration_and_field_mapping.md` (the CSV Integration chain). Full daily detail: `backlog/sprints/sprint-3.md`.
- **Sprint goal met in full.** The throughput risk carried in from Sprint 2 review is closed with a confirmed root cause (Debenu's internal document model) and a measured mitigation (batch+merge) — the 100k-record benchmark now completes in 315s, ~47.5% under the 10-minute target, a real completed run rather than an extrapolation. The first slice of CSV field mapping is delivered end-to-end and live-verified against the real built `.exe`: load headers, bind a dynamic field, rebind it, with the mapping honored on the next CLI render.
- **One new open technical-debt item carried forward, not a defect in this sprint's delivery:** the throughput mitigation's per-batch font re-embedding cost extrapolates to ~4.5-5 GB in output file size at the product's stated 1,000,000-record ceiling, over the 2 GB constraint (`logs/technical_debt_log.md`, 2026-09-21 entry). No committed story renders anywhere near that scale, so this does not block Sprint 3 or any currently-planned Sprint 4 work, but it should be picked up and resolved before any future story commits to rendering near the 1,000,000-record ceiling — two candidate fixes (count-aware batch sizing; subsetted rather than fully-embedded fonts per batch) are already noted in the debt log.
- "Collapse blank optional address lines consistently" (epic 3, 5 points, Ready) is now unblocked — its dependency ("Create a dynamic text token from a CSV column") is Done — and is a clean, natural pull for Sprint 4 alongside "Harden production configuration delivery for CLI runtime settings" (epic 5, 2 points, Ready), both already identified as deliberately-deferred-not-dropped at Sprint 3 planning.
- No changes to the two open impediments (template asset path strategy; UNC timeout/retry behavior, both in `logs/impediment_log.md`) — still non-blocking for the Sprint 4 candidates named above.

### New feature added during backlog refinement (2026-09-22)
- User requested the ability to rotate text/dynamic field elements at an arbitrary angle. `product-owner` clarified scope directly with the user (angle range, UI interaction, pivot point) before writing the story, then split it into two dependent stories in `epics/02_template_designer_gui_foundation.md` (previously fully Done, now reopened): "Set a rotation angle for text and dynamic field elements" (properties-panel numeric entry, persistence, and render-side rotation about the bounding-box center — 8 points) and "Rotate elements by dragging a handle on the canvas" (interactive drag handle, depends on the first story — 5 points). `dev-team` sized both against real code inspection, confirming the vendor Debenu API (`DrawRotatedText`, `GetTextWidth`/`GetTextAscent`/`GetTextDescent`) supports the underlying capability but has no "rotate about center" primitive, so the center-pivot math is genuine new work, not a pass-through. Both pass the Definition of Ready; recommend against splitting further.
- **Placement recommendation (product-owner, not yet ordered into a sprint):** slot these two stories immediately after the two items already flagged as clean Sprint 4 carryover from Sprint 3 planning — "Collapse blank optional address lines consistently" (epic 3, 5 pts) and "Harden production configuration delivery for CLI runtime settings" (epic 5, 2 pts) — rather than ahead of them, since neither carryover item depends on rotation and both were already committed-to in spirit at Sprint 3 planning. Note for Sprint 4 planning: those two carryover items (7 pts) plus both rotation stories (13 pts) sum to exactly 20 points, matching the top of this team's 19-20 point velocity range — scrum-master/dev-team should treat that as a ceiling-level coincidence to watch, not a target to hit, and should still leave normal grooming buffer per `AGENTS.md`'s guidance. This ordering is a recommendation only; the human product owner can reprioritize the rotation stories ahead of the carryover items if rotation is more urgent than sequencing suggests.

### Sprint 4 Review outcome (2026-09-29)
- All 3 committed Sprint 4 stories (18/18 points) are Done; each is verified against its acceptance criteria with real, non-simulated evidence, recorded story-by-story in `backlog/epics/02_template_designer_gui_foundation.md` (both rotation stories) and `backlog/epics/03_csv_integration_and_field_mapping.md` (blank-line collapse). Full daily detail: `backlog/sprints/sprint-4.md`.
- **Sprint goal met in full.** The CSV Integration and Field Mapping epic is now Done outright (4 of 4 stories). The Template Designer GUI Foundation epic is also Done outright again (6 of 6 stories, having been reopened for the rotation work). Test suite grew to 288/288 (up from 223 at Sprint 3 close).
- No new technical debt logged this sprint. The one open item carried in from Sprint 3 (1,000,000-record file-size risk) remains untouched and non-blocking, as expected — nothing this sprint touched the render batching/font-embedding path.
- One honestly-reported, non-blocking note from dev-team's own verification: a testing-tooling focus glitch (`SetForegroundWindow` failing once during GUI automation) briefly misdirected some keystrokes during Batch 3's live verification; caught immediately from screenshot evidence and worked around, confirmed to be a tooling artifact rather than a product defect — no product-facing gap, not logged as technical debt.
- "Harden production configuration delivery for CLI runtime settings" (epic 5, 2 points, Ready) remains uncommitted, as planned — still a clean pull whenever it's prioritized, not urgent per the product owner's standing note.
- No changes to the two open impediments (template asset path strategy; UNC timeout/retry behavior, both in `logs/impediment_log.md`).

### New epic added during backlog refinement (2026-09-29)
- User requested, ahead of closing Sprint 4, the ability to compose an "address control" — a group of lines (mixing static text and CSV fields) placeable as one unit on both the canvas and the rendered PDF. `product-owner` gathered requirements directly with the user across two rounds of clarifying questions (composition model, single-anchor movement, collapse-default behavior, and — the highest-impact fork — whether mixed static+field content is scoped to the control or general) before writing anything down.
- Recorded as a new epic, `epics/08_composite_address_controls.md`, with two dependent stories: "Mix static text and CSV fields within a single text element" (a general upgrade to every text element in the designer, not just control lines — confirmed explicitly with the user) and "Group lines into a single, movable Address Control" (a fully custom, operator-built line list with single-anchor movement and automatic spacing, default-on-but-toggleable per-line blank-collapse). Full requirements, including several explicit "Development Team design decision" flags for details not resolved with the user, are in that epic file.
- **Not yet sized or ordered into the backlog.** This is deliberately left as a requirements-capture step, per the user's own framing ("before we close the sprint... get requirements"); dev-team sizing and backlog placement should happen in a subsequent backlog refinement pass, not folded into Sprint 4's close-out.

### Sprint 4 planning outcome (2026-09-28)
- `scrum-master` facilitated. Velocity range tightened to 18-20 points (three data points: 20, 19, 18 completed in Sprints 1-3, the last with zero scope change). Committed 18 points at the low end of the range rather than the 20-point ceiling, per the standing "reserve ~10% for grooming" guidance: "Collapse blank optional address lines consistently" (5 pts, epic 3 — completes that epic outright), plus the full rotation chain from epic 2 — "Set a rotation angle for text and dynamic field elements" (8 pts) then "Rotate elements by dragging a handle on the canvas" (5 pts, depends on the former). Full plan: `backlog/sprints/sprint-4.md`.
- Not committed (capacity discipline, explicit stretch item): "Harden production configuration delivery for CLI runtime settings" (2 pts) — still not urgent per product-owner's standing note on that story; pull only if the committed three finish early.