Add pre-cycle Feature sizing workflow

AGENTS.md

@@ -17,6 +17,7 @@ This repository contains reusable AI coding workflows that can be installed glob
 - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
 - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff)
 - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
+- **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
 - **skill-reviewer** — Meta-workflow that audits AI skill directories
 - **triage** — Bulk Jira bug triage with AI-driven categorization and HTML reports
 
@@ -52,6 +53,7 @@ workflow-name/
 ```text
 _shared/
   review-protocol.md              # Shared code review criteria, finding format, severity definitions
+  sizing-rubric.md                # Shared sizing definitions (T-shirt sizes, heuristics, team effort guidance)
   recipes/
     self-review-gate.md           # Pre-PR self-review quality gate (used by bugfix, implement, e2e, cve-fix)
 ```
@@ -88,6 +90,7 @@ See CONTRIBUTING.md for workflow structure conventions, path rules, testing, and
 ai-workflows/
 ├── _shared/                   # Cross-cutting shared resources
 │   ├── review-protocol.md     # Shared code review criteria and finding format
+│   ├── sizing-rubric.md       # Shared sizing definitions and heuristics
 │   └── recipes/
 │       └── self-review-gate.md  # Pre-PR self-review quality gate
 ├── ai-ready/                  # Workflows (auto-discovered via SKILL.md)
@@ -100,6 +103,7 @@ ai-workflows/
 ├── implement/
 ├── kcs/
 ├── prd/
+├── sizing/
 ├── skill-reviewer/
 │   ├── prompts/
 │   └── scripts/
@@ -118,5 +122,5 @@ ai-workflows/
 When a workflow invokes commands that could affect shared systems:
 - **Git operations**: Always verify with `git status` before destructive operations
 - **PR/MR creation**: Confirm branch and base before pushing
-- **Jira writes**: Only cve-fix `/close` and design `/sync` write to Jira; both require explicit approval
+- **Jira writes**: Only cve-fix `/close`, design `/sync`, and sizing `/apply` write to Jira; all require explicit approval
 - **Documentation changes**: Run Vale validation before applying changes to repository files

README.md

@@ -39,6 +39,9 @@ Reusable AI coding workflows a team member can install globally or per-project,
 - **KCS** -- KCS Solution article workflow: gather bug context from Jira, draft a KCS article in markdown, validate against the KCS Content Standard, and produce a handoff message for the support engineer.
   See [kcs/README.md](kcs/README.md).
 
+- **Sizing** -- Pre-cycle Feature sizing: ingest Features from Jira (single or batch by Fix Version), assess against a T-shirt size rubric (XS–XXL) with per-team effort breakdowns (DEV, QE, UX, UI, DOCS), and write results back to Jira.
+  See [sizing/README.md](sizing/README.md).
+
 - **Skill Reviewer** -- Meta-workflow that audits AI skill directories against eight quality dimensions.
   See [skill-reviewer/README.md](skill-reviewer/README.md).
 
@@ -115,6 +118,7 @@ Each workflow is intended for a specific project or use case:
 - **ai-ready** -- onboarding any project for AI agents by generating AGENTS.md
 - **kcs** -- teams writing KCS Solution articles for known issues with workarounds
 - **triage** -- teams that want bulk Jira triage, categorization, and HTML reports from this repo or a clone
+- **sizing** -- teams sizing Features for cycle planning using T-shirt sizes with per-team effort breakdowns
 - **skill-reviewer** -- reviewing or standardizing Cursor/agent skills and skill packs (structure, clarity, completeness)
 
 Use `--workflows` to install only the workflows relevant to a given project:

_shared/sizing-rubric.md

@@ -0,0 +1,258 @@
+# Sizing Rubric
+
+Shared sizing definitions used by the sizing workflow (for Features) and the
+design workflow (for Epics). This file is the single source of truth for how
+the AI determines T-shirt sizes. Both workflows reference it to ensure
+consistent sizing across the planning process.
+
+## Cycle Structure
+
+A release cycle is **10 weeks**:
+
+| Phase | Duration | Purpose |
+|-------|----------|---------|
+| Development | 6 weeks | Feature implementation |
+| QE | 3 weeks | Quality engineering, e2e testing, regression |
+| Release | 1 week | Release preparation, deployment |
+
+Features are sized to fit within one cycle. Epics are sized relative to the
+development portion of the cycle. Stories are not sized — they are constrained
+by definition (1 assignee, less than a week).
+
+## Hierarchy
+
+```text
+Cycle (10 weeks: 6 dev + 3 QE + 1 release)
+  └── Feature  [T-Shirt: XS/S/M/L/XL — always fits in one cycle. XXL = must split]
+        └── Epic  [T-Shirt: XS/S/M/L/XL — maps to dev-weeks. XXL = must split]
+              └── Story  [No size — 1 assignee, less than a week max]
+```
+
+## Size Definitions
+
+These definitions apply to both Features and Epics. For Features, sizes are
+relative to the full cycle. For Epics, sizes are relative to the development
+phase (6 weeks).
+
+| Size | Label | Duration | Meaning |
+|------|-------|----------|---------|
+| XS | Extra Small | Up to 2 days | Minimal scope, well-understood change |
+| S | Small | Up to 1 week | Narrow scope, low risk, few components |
+| M | Medium | ~1–2 weeks | Moderate scope, multiple can coexist in a cycle |
+| L | Large | Up to ~3 weeks | Roughly half the dev phase, significant scope |
+| XL | Extra Large | ~4–6 weeks | Most of a cycle, demands focus |
+| XXL | Must Split | — | This must be scoped down before commitment |
+
+## XXL Protocol
+
+XXL is a **temporary flag**, not a committable size. It exists only to signal
+that a Feature or Epic is too large and must be split before it can be
+committed to a cycle.
+
+When a Feature or Epic is assessed as XXL:
+
+1. **Flag it immediately.** Do not proceed as if it will fit.
+2. **Suggest split boundaries.** Split by user-value slice, not by technical
+   layer. Each slice should deliver independent value.
+3. **Re-assess each slice.** After splitting, each resulting Feature or Epic
+   should be XL or smaller.
+4. **Never commit XXL to a cycle.** If a Feature is XXL after assessment, it
+   must be scoped down or split before it enters cycle planning.
+
+## Sizing Heuristics
+
+When assessing a Feature or Epic, evaluate these dimensions. Each dimension
+contributes to the overall size. No single dimension determines the size —
+use judgment to weigh them based on the specific context.
+
+### Scope Breadth
+
+How many distinct capabilities or outcomes does this deliver?
+
+- **Low (XS–S):** Single capability, focused change
+- **Medium (M):** 2–3 related capabilities
+- **High (L–XL):** Multiple capabilities spanning different user workflows
+- **Very High (XXL signal):** Broad scope touching many unrelated outcomes
+
+### Component Surface
+
+How many codebase components (packages, services, modules) are affected?
+
+- **Low (XS–S):** 1–2 components, well-contained
+- **Medium (M):** 3–5 components with clear boundaries
+- **High (L–XL):** 5+ components, cross-cutting changes
+- **Very High (XXL signal):** Most of the codebase is affected
+
+### Integration Surface
+
+How many APIs, external systems, or cross-team touch points are involved?
+
+- **Low (XS–S):** No external integrations, internal-only
+- **Medium (M):** 1–2 integration points with well-defined interfaces
+- **High (L–XL):** Multiple integration points, some with uncertainty
+- **Very High (XXL signal):** Heavy external coordination required
+
+### Novelty
+
+Is this extending existing patterns or building something new?
+
+- **Low (XS–S):** Following established patterns exactly
+- **Medium (M):** Extending existing patterns to new use cases
+- **High (L–XL):** New patterns, new abstractions, new infrastructure
+- **Very High (XXL signal):** Unproven approach, research needed
+
+### Risk and Unknowns
+
+How much uncertainty exists about the approach or outcome?
+
+- **Low (XS–S):** Well-understood domain, clear path
+- **Medium (M):** Some unknowns that can be resolved during design
+- **High (L–XL):** Significant unknowns, unfamiliar domain, dependencies on external teams
+- **Very High (XXL signal):** Fundamental unknowns that may invalidate the approach
+
+### Testing Surface
+
+How much new test infrastructure or coverage is needed?
+
+- **Low (XS–S):** Existing test patterns apply directly
+- **Medium (M):** New test cases but existing infrastructure
+- **High (L–XL):** New test infrastructure, new e2e scenarios, complex setup
+- **Very High (XXL signal):** Entirely new testing approach needed
+
+## Team Effort Assessment
+
+For each Feature, break down the effort by team. Each team gets its own
+T-shirt size (using the same XS–XL scale) with a rationale explaining what
+drives that team's effort.
+
+### DEV (Development)
+
+Driven by:
+- Number of components to modify or create
+- Integration surface — API changes, service interactions, data model changes
+- Novelty — new patterns vs. extending existing ones
+- Volume of production code changes
+
+### QE (Quality Engineering)
+
+Driven by:
+- Number of e2e test scenarios needed
+- New test infrastructure requirements (fixtures, environments, data setup)
+- Risk surface — how much regression testing is needed
+- Complexity of user-facing workflows to validate
+
+### UX (User Experience)
+
+Driven by:
+- New user flows vs. adjustments to existing flows
+- User research needs — does this require discovery or validation?
+- Interaction complexity — new patterns, complex state management
+- If no UX work is needed, size is "—" (not applicable)
+
+### UI (User Interface)
+
+Driven by:
+- New components vs. composition of existing components
+- Responsive and accessibility requirements
+- Visual complexity — styling, animation, layout changes
+- If no UI work is needed, size is "—" (not applicable)
+
+### DOCS (Downstream Documentation)
+
+Driven by:
+- New customer-facing documentation pages vs. updates to existing pages
+- Complexity of the feature from an end-user explanation perspective
+- Number of procedures, concepts, or reference topics required
+- If no downstream docs work is needed, size is "—" (not applicable)
+
+Note: upstream (community/open-source) documentation is produced by developers
+as part of DEV effort. DOCS covers only downstream, customer-facing documentation.
+
+When a team has no involvement in a Feature, use "—" instead of a size.
+
+## Impact vs. Effort Classification
+
+After sizing determines the *effort* a Feature requires, classify each Feature
+on a 2×2 impact-vs-effort matrix to support prioritization during cycle
+planning.
+
+### Impact Score
+
+Assess impact by scoring four sub-dimensions independently. Each is rated
+on a 1–5 scale. The composite impact score is the sum (range: 4–20).
+
+#### Sub-dimensions
+
+| Sub-dimension | 1 | 2 | 3 | 4 | 5 |
+|---------------|---|---|---|---|---|
+| **User Reach** | Internal-only or single user | Narrow segment, few workflows | Moderate user base, several workflows | Most users or a critical segment | All users, core workflow |
+| **Pain Severity** | Cosmetic, no workaround needed | Minor friction, easy workaround | Noticeable pain, workaround exists but costs time | Significant pain, workaround is fragile or costly | Blocker — no viable workaround |
+| **Strategic Alignment** | No connection to current goals | Tangential to a stated goal | Supports a goal indirectly | Directly advances a key goal | Critical to a top-priority initiative |
+| **Dependency** | Nothing depends on this | Enables minor follow-on work | Unblocks one planned Feature | Unblocks multiple Features or a critical path | Gate for an entire release theme |
+
+#### Impact Bands
+
+| Band | Score Range | Meaning |
+|------|------------|---------|
+| High | 15–20 | Strong value signal across multiple sub-dimensions |
+| Medium | 9–14 | Solid value but not uniformly strong |
+| Low | 4–8 | Limited value — nice-to-have or narrow reach |
+
+### Effort Score
+
+Map the T-shirt effort size to a numeric value for ratio calculation:
+
+| Size | Effort Score |
+|------|-------------|
+| XS | 1 |
+| S | 2 |
+| M | 4 |
+| L | 7 |
+| XL | 10 |
+
+XXL Features are not scored — they must be split first.
+
+### Priority Score
+
+Priority Score = Impact Score / Effort Score (rounded to one decimal).
+
+Higher is better. This score ranks Features within the same quadrant: a
+Strategic Bet with priority 3.8 should be sequenced before one at 2.1.
+
+### Effort-Impact Quadrant
+
+Combine the effort size with the impact band to classify each Feature:
+
+| Quadrant | Effort | Impact | Guidance |
+|----------|--------|--------|----------|
+| **Quick Win** | XS–S | High | Prioritize — high value for low cost |
+| **Strategic Bet** | M–XL | High | Worth the investment — plan capacity carefully |
+| **Low-Hanging Fruit** | XS–S | Low–Medium | Fill available capacity — easy wins when bandwidth allows |
+| **Reconsider** | M–XL | Low | Challenge whether this belongs in the cycle at all |
+
+Quadrant boundaries are guidelines, not hard rules. A Medium-effort /
+Medium-impact Feature may be either a Strategic Bet or Low-Hanging Fruit
+depending on context — use judgment and note the reasoning.
+
+Within each quadrant, use the **priority score** to rank Features against
+each other. The quadrant determines the category; the priority score
+determines the sequence within that category.
+
+## Calibration
+
+This section captures after-the-fact observations from completed cycles.
+These notes improve future sizing accuracy by grounding the heuristics in
+real experience.
+
+Format: one entry per observation, with the Feature key, original size,
+actual effort, and what drove the difference.
+
+```markdown
+### {Feature-key}: {title}
+- **Assessed:** {size}
+- **Actual:** {size}
+- **Delta driver:** {what caused the difference — e.g., "unexpected API
+  complexity in integration with X," "UX scope expanded after user testing"}
+```
+
+<!-- Add calibration entries below as cycles complete -->

design/decomposition-review.md

@@ -71,7 +71,11 @@ impact:
 
 2. **Epic Structure** — Is each epic organized around user value, not
    technical layers? Does each epic deliver complete functionality
-   independently? Are T-shirt sizes assigned and reasonable? Is the epic
+   independently? Are T-shirt sizes assigned and consistent with the sizing rubric
+   (`../_shared/sizing-rubric.md`)? Does each epic's size match its scope
+   — story count, component breadth, integration surface? Are any epics
+   suspiciously uniform in size when their scope clearly varies? No epic
+   should be sized XXL — that indicates it must be split. Is the epic
    dependency order documented and logical? Could implementing the epics
    in the documented order actually work, or are there hidden
    dependencies?

design/skills/decompose.md

@@ -74,8 +74,12 @@ Before writing, plan:
    infrastructure; the dependency is on *where* tests run, not *whether*
    tests exist.
 
-5. **Size epics.** Each epic should be larger than a single sprint but fit
-   within a release. Use T-shirt sizes (XS, S, M, L, XL).
+5. **Size epics.** Read `../../_shared/sizing-rubric.md` for the size
+   definitions and heuristics. Epic sizes map to dev-weeks within the
+   cycle. Use T-shirt sizes (XS, S, M, L, XL). **XXL is not allowed
+   in the final decomposition** — if an epic sizes to XXL, it must be
+   split into smaller epics before proceeding. Split by user-value
+   slice, not technical layer.
 
 ### Step 4: Write Epics
 
@@ -337,6 +341,26 @@ to Jira, their filenames must not change. When revising a decomposition,
 append new stories with the next available number rather than inserting or
 renumbering existing ones.
 
+### Step 5b: Sizing Consistency Check
+
+After sizing all epics, verify plausibility:
+
+1. Read the Feature's Size from `.artifacts/prd/{issue-number}/01-requirements.md`
+   (the Size field captured during PRD ingest) or from
+   `.artifacts/sizing/{issue-number}/02-assessment.md` (if the sizing
+   workflow was run in single-Feature mode). If neither exists, skip this
+   check. Note: batch-mode sizing stores assessments under a version slug
+   (e.g., `.artifacts/sizing/1-3-0/`), not per-Feature — batch assessments
+   are not automatically found by this lookup.
+
+2. Verify that the epic sizes are collectively plausible given the
+   Feature's overall size.
+   For example, a Feature sized M should not decompose into three L
+   epics. Flag any mismatch to the user.
+
+3. Verify no epic is sized XXL. If any is, stop and require a split
+   before proceeding to Step 6.
+
 ### Step 6: Write Coverage Matrix
 
 Write `.artifacts/design/{issue-number}/06-coverage.md`:

design/skills/sync.md

@@ -171,7 +171,8 @@ Feature: {feature-key}
 {list of story titles for this epic}
 ```
 
-- **T-Shirt Size:** {size} (set via the appropriate Jira field)
+- **T-Shirt Size:** {size} — set via `additional_fields`:
+  `{"customfield_10795": {"value": "{size}"}}`
 
 After creating each epic, verify the created issue has `parent.key`
 equal to `{feature-key}` by reading the issue back. If the parent is
@@ -337,6 +338,7 @@ should be:
       "file": "epic-1-image-building.md",
       "jira_key": "EDM-XXXX",
       "title": "{title}",
+      "size": "{size}",
       "stories": [
         {
           "file": "story-01-scaffold-build-pipeline.md",