From 3c85747355a0f8f8f89c836bd3c3fefdc1a83073 Mon Sep 17 00:00:00 2001
From: Eratostenes de Gitjabia <eratostenes@blocaolabs.com>
Date: Sat, 9 May 2026 18:48:05 +0000
Subject: [PATCH] docs(backlog): index and conventions

---
 backlog/README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 backlog/README.md

diff --git a/backlog/README.md b/backlog/README.md
new file mode 100644
index 0000000..0d8b153
--- /dev/null
+++ b/backlog/README.md
@@ -0,0 +1,75 @@
+# Backlog
+
+User stories, sprint plan, and cross-product reuse for both Blocao (video forensics) and Transcript Forensics products.
+
+## Files in this folder
+
+| File | Purpose |
+|---|---|
+| [`blocao-sprint-backlog.md`](blocao-sprint-backlog.md) | Stories specific to the Blocao video product. Story IDs `BL-XX.Y`. |
+| [`transcript-sprint-backlog.md`](transcript-sprint-backlog.md) | Stories specific to the transcript audio product. Story IDs `WDM-T-XX.Y`. |
+| [`shared-stories.md`](shared-stories.md) | Stories that touch both products. Cross-references both backlogs. |
+| [`sprint-plan.md`](sprint-plan.md) | Calendar view, dependencies, milestones. |
+
+## Story ID convention
+
+| Prefix | Meaning |
+|---|---|
+| `BL-XX.Y` | Blocao (video) story. `XX` = epic number, `Y` = sequence within epic. |
+| `WDM-T-XX.Y` | Transcript audio story. Same structure. |
+| `SHARED-XX.Y` | Shared infrastructure story. Lives in `shared-stories.md`. |
+
+Examples:
+
+- `BL-02.3` — Blocao Epic 2, story 3.
+- `WDM-T-04.1` — Transcript Epic 4, story 1.
+- `SHARED-00.2` — Shared foundation, story 2.
+
+## Reading the backlog
+
+For each story:
+
+- **Title**: short imperative (e.g., "Implement camera auto-discovery").
+- **Description**: what needs to exist when done.
+- **Acceptance criteria**: testable conditions.
+- **Estimate**: T-shirt size (S, M, L, XL) — S ≈ 1-2 days, M ≈ 3-5 days, L ≈ 1-2 weeks, XL ≈ 2-3 weeks.
+- **Dependencies**: explicit links to other stories that must close first.
+- **Tier**: which tier(s) this touches (router / cell / hub / console).
+
+## Estimation calibration
+
+T-shirt sizes assume one engineer comfortable with the relevant stack:
+
+- **S** (1-2 days): config tweak, single-component bug fix, small UI panel.
+- **M** (3-5 days): feature in one component with clear contract.
+- **L** (1-2 weeks): cross-component feature, multi-file changes, design + implementation + tests.
+- **XL** (2-3 weeks): epic-level feature with significant uncertainty; should be broken down before starting.
+
+Velocity assumption: ~10-15 story points per engineer per sprint (2 weeks). Adjust as actual velocity emerges.
+
+## Status conventions
+
+- **Inbox**: just written, not yet refined.
+- **Refined**: estimated, dependencies identified, acceptance criteria written.
+- **Ready**: refined and unblocked.
+- **In progress**: someone is working on it.
+- **In review**: PR open, awaiting review/QA.
+- **Done**: merged + deployed to staging at minimum.
+
+## Issue tracking
+
+Stories will be mirrored as Gitea issues (planned via MCP) once Sprint 0 closes. Until then, the markdown files are the source of truth.
+
+Issue labels:
+
+- `epic:0-foundation`, `epic:1-first-boot`, ..., `epic:7-hardening`
+- `tier:router`, `tier:cell`, `tier:hub`, `tier:console`
+- `size:S`, `size:M`, `size:L`, `size:XL`
+- `product:blocao`, `product:transcript`, `product:shared`
+- `priority:must-mvp`, `priority:should-mvp`, `priority:nice-to-have`
+
+## Sprint 0 must close before UI work
+
+Sprint 0 covers monorepo setup, CI, OpenWrt Image Builder pipeline, Balena fleet provisioning. Until that's in place, UI stories can be designed and mocked but not productively built.
+
+The exception is the operator console SPA itself, which can be developed against a mock backend until Sprint 0 closes.