From fcaed18571c3caf5be213f68181e879557392fd8 Mon Sep 17 00:00:00 2001 From: Noah White Date: Wed, 18 Feb 2026 06:26:21 +0000 Subject: [PATCH 1/2] docs: add epic t-shirt sizing guide to CLAUDE.md Clarifies that t-shirt sizes represent complexity/uncertainty rather than duration, while providing planning guidelines derived from historical velocity. - Small: well-understood, single focus area, ~1 cycle - Medium: some unknowns, 2-3 focus areas, ~1-2 cycles - Large: significant unknowns, multiple phases, ~2-3 cycles --- CLAUDE.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b00c8c1..b71023f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,10 +61,7 @@ Do NOT proceed until the title prefix is verified. When creating epics (Linear projects): - **Name must be prefixed with `[EPIC]`** (e.g., `[EPIC] Ghost Stack Backup & Recovery`) - Apply the **"Epic"** label to identify it as an epic -- Apply a **t-shirt size label** based on total story points: - - T-Shirt Size Small: ~5-10 story points - - T-Shirt Size Medium: ~15-25 story points - - T-Shirt Size Large: ~30+ story points +- Apply a **t-shirt size label** based on complexity (see sizing guide below) - **Always set Noah White as the project lead** ### Epic Template @@ -104,6 +101,28 @@ All epics must follow this standard template format (see `[EPIC] Secure Remote M **Important:** Do NOT include "Issues / Stories" or "Related Projects or Epics" sections - these are visible via Linear's UI. +### Epic T-Shirt Sizing + +Sizes represent **complexity and uncertainty**, not duration. Higher complexity tends to correlate with longer duration, but the size itself measures "how hard is this to figure out and implement" rather than "how many days/weeks." + +**Complexity Indicators:** + +| Size | Characteristics | +|------|-----------------| +| **Small** | Well-understood work, single focus area, minimal dependencies, few unknowns | +| **Medium** | Some unknowns, 2-3 focus areas, moderate dependencies, may require research | +| **Large** | Significant unknowns, multiple phases, external integrations, new vendors/technologies | + +**Planning Guidelines** (derived from historical velocity): + +| Size | Typical Cycles | Story Points (approx) | Notes | +|------|----------------|----------------------|-------| +| **Small** | 1 | 5-10 | Single-phase, well-defined | +| **Medium** | 1-2 | 10-20 | May have dependencies between stories | +| **Large** | 2-3 | 20-35 | Review if exceeding 3 cycles | + +**Note:** The cycle ranges are guidelines derived from team velocity, not prescriptive targets. Actual duration depends on unknowns discovered during implementation. + ### User Story Template All user stories must follow this standard template format (see GHO-21 for reference): From bbb982b794cacb911d6d2965791684750b0b9a90 Mon Sep 17 00:00:00 2001 From: Noah White Date: Wed, 18 Feb 2026 06:27:43 +0000 Subject: [PATCH 2/2] docs: use comprehensive epic sizing framework Updates t-shirt sizing guide with: - Small (S): 1-2 sprints, well-understood, low risk - Medium (M): 3-4 sprints, moderate unknowns - Large (L): 1 quarter, complex, significant risk - Extra Large (XL): multiple quarters, needs breakdown --- CLAUDE.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b71023f..701fc15 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,23 +105,17 @@ All epics must follow this standard template format (see `[EPIC] Secure Remote M Sizes represent **complexity and uncertainty**, not duration. Higher complexity tends to correlate with longer duration, but the size itself measures "how hard is this to figure out and implement" rather than "how many days/weeks." -**Complexity Indicators:** - -| Size | Characteristics | -|------|-----------------| -| **Small** | Well-understood work, single focus area, minimal dependencies, few unknowns | -| **Medium** | Some unknowns, 2-3 focus areas, moderate dependencies, may require research | -| **Large** | Significant unknowns, multiple phases, external integrations, new vendors/technologies | - -**Planning Guidelines** (derived from historical velocity): - -| Size | Typical Cycles | Story Points (approx) | Notes | -|------|----------------|----------------------|-------| -| **Small** | 1 | 5-10 | Single-phase, well-defined | -| **Medium** | 1-2 | 10-20 | May have dependencies between stories | -| **Large** | 2-3 | 20-35 | Review if exceeding 3 cycles | - -**Note:** The cycle ranges are guidelines derived from team velocity, not prescriptive targets. Actual duration depends on unknowns discovered during implementation. +| Size | Complexity / Effort Description | Typical Time Mapping | +|------|--------------------------------|----------------------| +| **Small (S)** | Well-understood, minor dependencies, low risk | 1-2 sprints (2-4 weeks) | +| **Medium (M)** | Standard feature, some integration, moderate unknowns | 3-4 sprints (1.5-2 months) | +| **Large (L)** | Complex logic, multiple team touchpoints, significant risk | 1 full quarter (~3 months) | +| **Extra Large (XL)** | Cross-departmental, massive architectural shifts | Multiple quarters (needs breakdown) | + +**Notes:** +- Time mappings are guidelines derived from historical velocity, not prescriptive targets +- XL epics should be broken down into smaller epics before starting +- Actual duration depends on unknowns discovered during implementation ### User Story Template