From 04e80e390944018cded76168f98d1763046ba519 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Fri, 29 May 2026 18:56:01 +0300 Subject: [PATCH 1/2] Add pre-cycle Feature sizing workflow Introduce the sizing workflow (ingest, assess, apply) for T-shirt sizing Features with per-team effort breakdowns (DEV, QE, UX, UI, DOCS). Adds shared sizing rubric in _shared/ and integrates with design decompose (sizing consistency check) and prd ingest (Size custom field capture). Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 6 +- README.md | 4 + _shared/sizing-rubric.md | 258 +++++++++++++++++++++++++++++ design/decomposition-review.md | 6 +- design/skills/decompose.md | 28 +++- design/skills/sync.md | 4 +- prd/skills/ingest.md | 3 + sizing/README.md | 136 +++++++++++++++ sizing/SKILL.md | 29 ++++ sizing/commands/apply.md | 11 ++ sizing/commands/assess.md | 11 ++ sizing/commands/ingest.md | 11 ++ sizing/guidelines.md | 47 ++++++ sizing/skills/apply.md | 170 +++++++++++++++++++ sizing/skills/assess.md | 293 +++++++++++++++++++++++++++++++++ sizing/skills/controller.md | 119 +++++++++++++ sizing/skills/ingest.md | 191 +++++++++++++++++++++ 17 files changed, 1322 insertions(+), 5 deletions(-) create mode 100644 _shared/sizing-rubric.md create mode 100644 sizing/README.md create mode 100644 sizing/SKILL.md create mode 100644 sizing/commands/apply.md create mode 100644 sizing/commands/assess.md create mode 100644 sizing/commands/ingest.md create mode 100644 sizing/guidelines.md create mode 100644 sizing/skills/apply.md create mode 100644 sizing/skills/assess.md create mode 100644 sizing/skills/controller.md create mode 100644 sizing/skills/ingest.md diff --git a/AGENTS.md b/AGENTS.md index ad47cf6e..ea878700 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index f1f3feaa..e8256ee5 100644 --- a/README.md +++ b/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: diff --git a/_shared/sizing-rubric.md b/_shared/sizing-rubric.md new file mode 100644 index 00000000..c85f514f --- /dev/null +++ b/_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"} +``` + + diff --git a/design/decomposition-review.md b/design/decomposition-review.md index 168e272d..502fd58c 100644 --- a/design/decomposition-review.md +++ b/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? diff --git a/design/skills/decompose.md b/design/skills/decompose.md index b54d1f96..7c5cd23e 100644 --- a/design/skills/decompose.md +++ b/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`: diff --git a/design/skills/sync.md b/design/skills/sync.md index 24177347..681b4d04 100644 --- a/design/skills/sync.md +++ b/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", diff --git a/prd/skills/ingest.md b/prd/skills/ingest.md index 686a5094..29580281 100644 --- a/prd/skills/ingest.md +++ b/prd/skills/ingest.md @@ -59,6 +59,8 @@ Capture: - Description (full text, preserving any section structure) - Acceptance criteria / Definition of Done (if present) - Status, priority, labels, fix version +- Size (`customfield_10795`, if set — include this field explicitly in the + Jira fetch request since custom fields are not returned by default) - Comments (all) - Attachments (note their names and descriptions) @@ -105,6 +107,7 @@ If this is a first invocation, write - **Priority:** {priority} - **Labels:** {labels} - **Fix Version:** {version} +- **Size:** {value or "Not set"} ## Description diff --git a/sizing/README.md b/sizing/README.md new file mode 100644 index 00000000..de395658 --- /dev/null +++ b/sizing/README.md @@ -0,0 +1,136 @@ +# Sizing Workflow + +A pre-cycle Feature sizing workflow that assesses Jira Features using T-shirt sizes (XS–XXL), produces per-team effort breakdowns (DEV, QE, UX, UI, DOCS), classifies each Feature on an impact-vs-effort quadrant for prioritization, and writes results back to Jira. Supports single-Feature and batch (Fix Version) modes. + +## Prerequisites + +| Tool | Required | Purpose | +|------|----------|---------| +| Jira access (MCP or CLI) | Yes | Fetch Features, write Size field, add comments | +| Git | Yes | Codebase exploration | + +## Phases + +| Phase | Command | Purpose | Artifact(s) | +|-------|---------|---------|-------------| +| Ingest | `/ingest` | Fetch Feature(s) from Jira, explore codebase | `01-context.md` | +| Assess | `/assess` | Apply sizing rubric, produce recommendations | `02-assessment.md` | +| Apply | `/apply` | Write sizes to Jira, add team breakdown comment | — | + +## Input Modes + +### Single Feature + +```text +/ingest EDM-2324 +``` + +Sizes a single Feature. + +### Batch by Release + +```text +/ingest release:EDM:1.3.0 +``` + +Fetches all Features in the specified project and Fix Version, sizing them together for relative calibration. Format: `release:{project}:{version}`. + +## Typical Flow + +```text +/ingest EDM-2324 + → fetches Feature from Jira (description, acceptance criteria, comments) + → explores affected codebase areas + → writes .artifacts/sizing/EDM-2324/01-context.md + +/assess + → reads sizing rubric (../_shared/sizing-rubric.md) + → evaluates Feature against heuristics + → produces overall size + per-team breakdown (DEV, QE, UX, UI, DOCS) + → rates impact and classifies effort-impact quadrant + → writes .artifacts/sizing/EDM-2324/02-assessment.md + +/apply + → previews what will be written to Jira (dry run) + → sets Size field (customfield_10795) on the Feature + → adds comment with team effort breakdown and rationale +``` + +### Batch Flow + +```text +/ingest release:EDM:1.3.0 + → fetches all Features in project EDM with fixVersion = "1.3.0" + → explores codebase for each Feature + → writes .artifacts/sizing/1-3-0/01-context.md + +/assess + → sizes each Feature individually + → rates impact and classifies effort-impact quadrant per Feature + → relative calibration: compares Features against each other + → writes .artifacts/sizing/1-3-0/02-assessment.md (summary table + per-Feature detail) + +/apply + → previews all sizes + → user can exclude specific Features + → writes approved sizes to Jira +``` + +## Artifacts + +All artifacts are stored in `.artifacts/sizing/{context}/` where context is +the Feature key (single mode) or a kebab-case Fix Version slug (batch mode). + +```text +.artifacts/sizing/EDM-2324/ (single mode) + 01-context.md (Feature data + codebase impact) + 02-assessment.md (sizing recommendation + team breakdown) + +.artifacts/sizing/1-5/ (batch mode, Fix Version "1.5") + 01-context.md (all Features + codebase impact) + 02-assessment.md (summary table + per-Feature assessments) +``` + +## Size Scale + +| Size | Duration | Meaning | +|------|----------|---------| +| XS | Up to 2 days | Minimal scope, well-understood change | +| S | Up to 1 week | Narrow scope, low risk | +| M | ~1–2 weeks | Moderate scope, multiple can coexist | +| L | Up to ~3 weeks | Roughly half the dev phase | +| XL | ~4–6 weeks | Most of a cycle | +| XXL | — | Must split before committing | + +See `../_shared/sizing-rubric.md` for the full rubric including heuristics and +team effort guidance. + +## Directory Structure + +```text +sizing/ +├── SKILL.md # Workflow entry point +├── guidelines.md # Behavioral rules and guardrails +├── README.md # This file +├── skills/ +│ ├── controller.md # Phase dispatcher and transitions +│ ├── ingest.md # Fetch Features, explore codebase +│ ├── assess.md # Apply rubric, produce recommendations +│ └── apply.md # Write sizes to Jira +└── commands/ + ├── ingest.md # /ingest command + ├── assess.md # /assess command + └── apply.md # /apply command +``` + +## Getting Started + +```bash +# Install the workflow +./install.sh claude --workflows sizing + +# Or install all workflows +./install.sh all +``` + +Then run the sizing workflow's `ingest` command with a Feature key or Fix Version. diff --git a/sizing/SKILL.md b/sizing/SKILL.md new file mode 100644 index 00000000..daf10288 --- /dev/null +++ b/sizing/SKILL.md @@ -0,0 +1,29 @@ +--- +name: sizing +description: >- + Pre-cycle Feature sizing workflow that assesses Features from Jira using + T-shirt sizes (XS–XXL), produces per-team effort breakdowns (DEV, QE, UX, UI, DOCS), + and writes results back to Jira. Accepts a single Feature or all Features + in a Fix Version for batch sizing. + Use when sizing Features for cycle planning, prioritizing a release backlog, + or evaluating whether a Feature fits in a cycle. + Activated by commands: /ingest, /assess, /apply. +--- +# Sizing Workflow Orchestrator + +## Quick Start + +1. If the user invoked a specific command (e.g., `/assess`, `/apply`), read + `commands/{command}.md` and follow it. +2. Otherwise, read `skills/controller.md` to load the workflow controller: + - If the user provided a Jira issue key or URL, execute the `/ingest` phase + in single-Feature mode + - If the user provided a release identifier (e.g., `release:EDM:1.3.0`), + execute the `/ingest` phase in batch mode + - Otherwise, ask the user for a Feature key or release identifier + +If a step fails or produces unexpected output (e.g., Jira MCP errors, network +failures, invalid issue keys), stop and report the error to the user. Do not +advance to the next phase. Offer to retry the failed step or escalate. + +For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/sizing/commands/apply.md b/sizing/commands/apply.md new file mode 100644 index 00000000..0f51e2af --- /dev/null +++ b/sizing/commands/apply.md @@ -0,0 +1,11 @@ +--- +name: sizing:apply +description: "Write assessed sizes to Jira with team effort breakdown" +--- +# /apply + +Read `../skills/controller.md` and follow it. + +Dispatch the **apply** phase. Context: + +$ARGUMENTS diff --git a/sizing/commands/assess.md b/sizing/commands/assess.md new file mode 100644 index 00000000..e73708aa --- /dev/null +++ b/sizing/commands/assess.md @@ -0,0 +1,11 @@ +--- +name: sizing:assess +description: "Apply sizing rubric and produce Feature sizing recommendations" +--- +# /assess + +Read `../skills/controller.md` and follow it. + +Dispatch the **assess** phase. Context: + +$ARGUMENTS diff --git a/sizing/commands/ingest.md b/sizing/commands/ingest.md new file mode 100644 index 00000000..e6aaf822 --- /dev/null +++ b/sizing/commands/ingest.md @@ -0,0 +1,11 @@ +--- +name: sizing:ingest +description: "Fetch Features from Jira and explore codebase for sizing" +--- +# /ingest + +Read `../skills/controller.md` and follow it. + +Dispatch the **ingest** phase. Context: + +$ARGUMENTS diff --git a/sizing/guidelines.md b/sizing/guidelines.md new file mode 100644 index 00000000..f6eea611 --- /dev/null +++ b/sizing/guidelines.md @@ -0,0 +1,47 @@ +# Sizing Workflow Guidelines + +## Principles + +- **Appetite over estimates.** We enforce fixed time and variable scope. Features are sized to fit available time — we don't extend the timeline. +- **Consistency via the rubric.** Every sizing assessment references `../_shared/sizing-rubric.md`. The rubric's heuristics ensure different sessions produce comparable results. +- **Sizing is advisory.** The AI produces a recommendation with rationale. Humans make the final call during cycle planning. +- **Relative calibration.** In batch mode, compare Features against each other. A Feature's size is more meaningful when evaluated alongside its peers in the same release. +- **Team breakdown is required.** Every Feature assessment includes per-team effort (DEV, QE, UX, UI, DOCS) so capacity planning accounts for team-level constraints, not just aggregate effort. + +## Hard Limits + +- No fabricated sizes. Every size must be justified by the rubric's heuristics applied to the Feature's actual content and codebase impact. +- No auto-advancing between phases. Always wait for the user. +- No Jira writes without explicit user approval and a dry-run preview first. +- **XXL is never committed.** If a Feature is assessed as XXL, it must be split. Do not write XXL to Jira — recommend the user split first. +- No scope reduction. If a Feature doesn't fit, flag it as XXL and recommend splitting — don't silently reduce its scope to make it fit a smaller size. + +## Safety + +- Present the full assessment before applying to Jira. The user must see and approve every size before it is written. +- Flag low-confidence assessments. If the Feature description is vague or the codebase impact is uncertain, say so explicitly and explain what additional information would improve confidence. +- Compare with existing Jira Size. If the Feature already has a Size in Jira, note whether the assessment agrees or differs, and why. + +## Quality + +- Reference the rubric for every assessment. Do not size from intuition alone — cite which heuristics drove the size. +- Team breakdown rationale must be specific. "DEV: M because 3 components affected and new API surface" is good. "DEV: M" alone is not. +- Use "—" (not applicable) for teams with no involvement, not XS. + +## Escalation + +Stop and request human guidance when: + +- The Feature description is too vague to produce a meaningful size +- Conflicting signals produce ambiguous sizing (e.g., narrow scope but high risk) +- The user disagrees with the assessment and the rationale doesn't resolve the disagreement +- A batch contains Features with unclear or missing Fix Version assignments +- Codebase exploration reveals the Feature's scope is fundamentally different from what the Jira description suggests + +## Working With the Project + +This workflow gets deployed into different projects. Respect the target project: + +- Read and follow the project's own `AGENTS.md` or `CLAUDE.md` files +- Use the project's codebase context to inform component surface and novelty assessments +- Adopt the project's terminology for components, services, and architectural concepts diff --git a/sizing/skills/apply.md b/sizing/skills/apply.md new file mode 100644 index 00000000..3f82e3c6 --- /dev/null +++ b/sizing/skills/apply.md @@ -0,0 +1,170 @@ +--- +name: apply +description: Write assessed Feature sizes to Jira and add team effort breakdown as a comment. +--- + +# Apply Sizing Skill + +You are a project coordinator. Your job is to write the assessed Feature sizes +to Jira and add a comment with the team effort breakdown, so the sizing is +visible where cycle planning happens. + +## Your Role + +Read the sizing assessment, present a dry-run preview, get explicit user +approval, then update each Feature in Jira with its size and a structured +comment containing the team breakdown. + +## Critical Rules + +- **Dry-run first.** Always show what would be written before writing anything. +- **Explicit approval required.** Never write to Jira without the user saying "yes." +- **User can exclude Features.** In batch mode, the user may approve some and exclude others. +- **Never write XXL.** If a Feature is assessed as XXL, do not write it to Jira. Warn the user that the Feature must be split first. +- **Stop on failure.** If a Jira update fails, stop immediately, report the error, and offer to retry or skip. + +## Process + +### Step 1: Read Assessment + +Read `.artifacts/sizing/{context}/02-assessment.md`. + +If the assessment file doesn't exist, tell the user that `/assess` should +be run first. + +### Step 2: Dry Run + +Present a preview of what will be written to Jira: + +```markdown +## Apply Preview + +| # | Feature | Size to Set | Comment | +|---|---------|------------|---------| +| 1 | {key}: {title} | {size} | Team breakdown: DEV {size}, QE {size}, UX {size}, UI {size}, DOCS {size} | +``` + +For any Feature assessed as XXL, show it separately: + +```markdown +## Excluded — XXL (Must Split) + +| Feature | Recommended Action | +|---------|-------------------| +| {key}: {title} | Split before committing — see split recommendations in assessment | +``` + +**Wait for explicit user approval before proceeding.** + +The user may: +- Approve all +- Exclude specific Features (by number) +- Override a size (the user has the final say) +- Cancel entirely + +If the user overrides any size, update `02-assessment.md` to reflect the +override (e.g., "M (overridden from L by user)") so the artifact stays +consistent with what is written to Jira. + +### Step 3: Apply to Jira + +For each approved Feature: + +#### 3a: Update the Size Field + +Update the Feature issue to set the Size field: + +``` +jira_update_issue( + issue_key: "{feature-key}", + fields: {"customfield_10795": {"value": "{size}"}} +) +``` + +If the update fails, stop and report the error. Offer to: (a) retry, or +(b) skip this Feature and continue with the rest. + +#### 3b: Add Team Breakdown Comment + +Add a comment to the Feature issue with the team effort breakdown and +impact scoring. Use Jira wiki markup (not Markdown) so tables render +correctly on Jira Cloud. + +``` +jira_add_comment( + issue_key: "{feature-key}", + comment: "{comment in Jira wiki markup — see template below}" +) +``` + +The comment must use Jira wiki markup. Headers use `||`, rows use `|`: + +```text +h2. Sizing Assessment + +*Overall Size: {size}* + +||Team||Effort||Rationale|| +|DEV|{size}|{rationale}| +|QE|{size}|{rationale}| +|UX|{size or —}|{rationale or "No UX work identified"}| +|UI|{size or —}|{rationale or "No UI work identified"}| +|DOCS|{size or —}|{rationale or "No downstream docs work identified"}| + +*Impact vs. Effort:* + +||Sub-dimension||Score||Rationale|| +|User Reach|{1–5}|{brief justification}| +|Pain Severity|{1–5}|{brief justification}| +|Strategic Alignment|{1–5}|{brief justification}| +|Dependency|{1–5}|{brief justification}| + +*Impact:* {sum}/20 ({High/Medium/Low}) | *Effort:* {effort score} ({size}) +*Priority:* {priority score} | *Quadrant:* {quadrant} + +*Key sizing drivers:* +- {driver 1} +- {driver 2} +- {driver 3} + +_Generated by AI sizing workflow_ +``` + +If the comment fails, log the error but continue — a missing comment is +less critical than a missing size. Report it to the user at the end. + +### Step 4: Report to User + +Summarize what was written: + +```markdown +## Apply Results + +### Updated + +| Feature | Size Set | Comment Added | +|---------|---------|---------------| +| {key}: {title} | {size} | Yes / Failed | + +### Skipped + +| Feature | Reason | +|---------|--------| +| {key}: {title} | {User excluded / XXL — must split / Error: {msg}} | +``` + +Provide direct links to each updated Feature in Jira so the user can +verify the results. + +## Output + +- Jira Feature issues updated with Size field and team breakdown comment + +## When This Phase Is Done + +Report your results: +- How many Features were updated +- Any Features skipped and why +- Links to updated Features in Jira + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/sizing/skills/assess.md b/sizing/skills/assess.md new file mode 100644 index 00000000..0e400276 --- /dev/null +++ b/sizing/skills/assess.md @@ -0,0 +1,293 @@ +--- +name: assess +description: Apply the sizing rubric to produce Feature sizing recommendations with team effort breakdowns. +--- + +# Assess Sizing Skill + +You are a technical sizing analyst. Your job is to apply the sizing rubric +to each Feature, determine an overall T-shirt size, and produce a per-team +effort breakdown that supports cycle planning. + +## Your Role + +Read the ingested Feature context and the sizing rubric, then evaluate each +Feature against the rubric's heuristics. Produce sizing recommendations that +are consistent, well-reasoned, and comparable across Features. + +## Critical Rules + +- **Reference the rubric.** Every size must be justified by the heuristics in `../../_shared/sizing-rubric.md`. Do not size from intuition alone. +- **Team breakdown is mandatory.** Every Feature assessment includes DEV, QE, UX, UI, and DOCS effort sizes with rationale. Use "—" for teams with no involvement. +- **XXL triggers a split recommendation.** If a Feature is assessed as XXL, it must not be committed — provide suggested split boundaries. +- **Batch mode requires relative calibration.** After sizing Features individually, compare them against each other and adjust for consistency. +- **Compare with existing Jira sizes.** If a Feature already has a Size in Jira, note whether the assessment agrees or differs, and explain why. + +## Process + +### Step 1: Read Source Material + +Read these files: +1. `.artifacts/sizing/{context}/01-context.md` (Feature data and codebase impact) +2. `../../_shared/sizing-rubric.md` (sizing definitions and heuristics) + +If `{context}` is not known from the current session, list existing +directories under `.artifacts/sizing/` and ask the user to confirm which +one to assess. If no directories exist, tell the user that `/ingest` +should be run first. + +### Step 2: Assess Each Feature + +For each Feature in the context file, evaluate against the rubric's six +heuristic dimensions: + +1. **Scope breadth** — How many distinct capabilities or outcomes? +2. **Component surface** — How many codebase components are affected? +3. **Integration surface** — How many APIs, external systems, or cross-team touch points? +4. **Novelty** — Extending existing patterns or building something new? +5. **Risk and unknowns** — How much uncertainty about approach or outcome? +6. **Testing surface** — How much new test infrastructure or coverage? + +For each dimension, assign a level (Low/Medium/High/Very High) based on the +rubric's guidance. The overall size is a judgment that weighs all dimensions +together — no single dimension determines the size. + +### Step 3: Determine Team Effort Breakdown + +For each Feature, assess effort per team using the rubric's team-level +guidance: + +- **DEV:** Component count, integration surface, data model changes, novelty +- **QE:** Test scenario count, new infrastructure needs, risk surface, regression scope +- **UX:** New flows vs. adjustments, user research needs, interaction complexity +- **UI:** New components vs. composition, responsive/accessibility requirements +- **DOCS:** New downstream doc pages vs. updates, explanation complexity, procedure count + +Each team gets a T-shirt size (XS–XL) or "—" if the team has no involvement. +Include a rationale for each team's size — not just the size label. + +### Step 4: Score Impact and Classify Quadrant + +For each Feature, score the four impact sub-dimensions (1–5 each) using the +rubric's scoring table: + +1. **User Reach** — How many users or workflows are affected? +2. **Pain Severity** — Is this a workaround-required blocker or a minor friction? +3. **Strategic Alignment** — Does this advance a stated product or business goal? +4. **Dependency** — Does other planned work depend on this shipping first? + +Sum the sub-dimension scores to get the composite impact score (4–20), then +map to the impact band (High / Medium / Low). + +Compute the priority score: Impact Score / Effort Score (using the effort +score mapping from the rubric). This score ranks Features within the same +quadrant. + +Classify each Feature into the effort-impact quadrant (Quick Win / Strategic +Bet / Low-Hanging Fruit / Reconsider) based on the effort size and impact +band. + +### Step 5: Handle XXL Assessments + +If any Feature is assessed as XXL: + +1. **Flag it clearly.** XXL cannot be committed to a cycle. +2. **Suggest split boundaries.** Identify 2–3 user-value slices that could + become independent Features. Split by user-value, not by technical layer. +3. **Estimate each slice.** Provide a rough size for each suggested slice. + +### Step 6: Relative Calibration (Batch Mode Only) + +After assessing all Features individually: + +1. **Compare sizes.** Are the relative sizes consistent? If Feature A (narrow + scope, 2 components) is sized M and Feature B (similar scope, 2 components) + is sized L, investigate the discrepancy. +2. **Check team balance.** Are there capacity concerns? Multiple Features with + heavy QE effort in the same release may strain the QE team. +3. **Adjust if needed.** If calibration reveals inconsistencies, adjust sizes + and note the reasoning. + +Skip this step in single-Feature mode. + +### Step 7: Compare with Existing Jira Sizes + +For each Feature that already has a Size set in Jira (`customfield_10795`): + +- If the assessment **agrees**: note "Consistent with current Jira value." +- If the assessment **differs**: explain what the rubric-based evaluation + found differently. Common reasons: scope changed since the original size + was set, codebase exploration revealed more/less complexity than expected, + or the original size didn't account for a specific team's effort. + +### Step 8: Write Assessment + +Write `.artifacts/sizing/{context}/02-assessment.md`: + +```markdown +# Sizing Assessment — {context} + +## Summary + +| Feature | Current Size | Recommended Size | Change | Impact Score | Effort Score | Priority | Quadrant | DEV | QE | UX | UI | DOCS | +|---------|-------------|-----------------|--------|----------------|-------------|----------|----------|-----|----|----|-----|------| +| {key}: {title} | {current or —} | {recommended} | {↑/↓/=/new} | {band} ({score}/20) | {effort score} | {priority score} | {quadrant} | {size} | {size} | {size} | {size} | {size} | + +{Repeat for each Feature. Use the full Jira summary as the title — do not + shorten, abbreviate, or paraphrase it.} + +## Impact vs. Effort Map + +```mermaid +quadrantChart + title Impact vs. Effort + x-axis Low Effort --> High Effort + y-axis Low Impact --> High Impact + quadrant-1 Strategic Bet + quadrant-2 Quick Win + quadrant-3 Low-Hanging Fruit + quadrant-4 Reconsider + {For each Feature, add a point. Normalize effort score to 0–1 + (effort_score / 10) and impact score to 0–1 ((impact_score - 4) / 16). + Use only the issue key as the label — no title, priority score, + or other text. + Example: + EDM-2324: [0.40, 0.81] + EDM-2501: [0.70, 0.56]} +``` + +## Size Distribution + +| Size | Count | Features | +|------|-------|----------| +| {size} | {count} | {key (short name), key (short name), ...} | + +{One row per size bucket, ordered from largest to smallest. Only include + sizes that have at least one Feature. Use a short parenthetical name + for readability — e.g., "EDM-3862 (VM Management)".} + +## Key Highlights + +{Include ALL of the following subsections. Omit a subsection only if it + has zero entries.} + +**XXL Flags:** +{List any Features assessed as XXL that must be split before committing. + Or "None — all Features fit within a single cycle."} + +**Top Priority Scores** (highest impact/effort ratio): +{Numbered list of the top Features by priority score, with effort size, + impact band, and a brief note on why it ranks high. Include at least + the top 3–4.} + +**Strategic Bets** (high investment, high return): +{Bulleted list of Features in the Strategic Bet quadrant, with priority + score and what drives their value.} + +**Features in the Reconsider Quadrant:** +{Bulleted list of Features with high effort but low impact. Note whether + they could be deferred without blocking other work.} + +**Capacity Concerns:** +{Flag team-level bottlenecks — e.g., multiple Features requiring heavy + QE effort that could strain a single team if run in parallel. Suggest + sequencing if relevant.} + +**Low-Confidence Assessments:** +{Flag any Features where the description was vague, codebase impact was + uncertain, or assumptions were made that could change the size.} + +**Jira Size Comparison:** +{Summary of how many Features had existing sizes, how many agreed vs. + differed, and notable disagreements. Or "None of the Features had + existing Jira sizes to compare against."} + +## Feature: {issue-key} — {title} + +### Overall Size: {XS–XXL} + +**Heuristic Evaluation:** + +| Dimension | Level | Assessment | +|-----------|-------|------------| +| Scope breadth | {Low/Medium/High/Very High} | {brief justification} | +| Component surface | {level} | {brief justification} | +| Integration surface | {level} | {brief justification} | +| Novelty | {level} | {brief justification} | +| Risk/unknowns | {level} | {brief justification} | +| Testing surface | {level} | {brief justification} | + +**Rationale:** +{2–4 sentences synthesizing the heuristic evaluation into the overall size. + Explain which dimensions were the primary drivers.} + +### Team Effort Breakdown + +| Team | Effort | Rationale | +|------|--------|-----------| +| DEV | {size} | {specific justification — components, APIs, data model} | +| QE | {size} | {specific justification — scenarios, infrastructure, regression} | +| UX | {size or —} | {specific justification or "No UX work identified"} | +| UI | {size or —} | {specific justification or "No UI work identified"} | +| DOCS | {size or —} | {specific justification or "No downstream docs work identified"} | + +### Impact vs. Effort + +| Sub-dimension | Score | Rationale | +|---------------|-------|-----------| +| User Reach | {1–5} | {brief justification} | +| Pain Severity | {1–5} | {brief justification} | +| Strategic Alignment | {1–5} | {brief justification} | +| Dependency | {1–5} | {brief justification} | + +**Impact Score:** {sum}/20 ({High/Medium/Low}) +**Effort Score:** {effort score} ({size}) +**Priority Score:** {impact/effort, 1 decimal} +**Quadrant:** {Quick Win / Strategic Bet / Low-Hanging Fruit / Reconsider} + +### Jira Comparison + +{Agrees/differs with current Jira value, and why. Or "No existing size in Jira."} + +{If XXL:} +### Split Recommendation + +This Feature must be scoped down before committing to a cycle. Suggested +split by user-value slice: + +1. **{Slice title}:** {description} — estimated {size} +2. **{Slice title}:** {description} — estimated {size} + +{Repeat "## Feature:" block for each Feature} + +{Batch mode only:} +## Relative Calibration Notes + +{Any adjustments made after comparing Features against each other. + Or "All sizes are internally consistent — no adjustments needed."} +``` + +### Step 9: Present to User + +Present the summary table and highlight: +- Any Features assessed as XXL (with split recommendations) +- Any assessments that differ from existing Jira sizes +- Any Features in the **Reconsider** quadrant (high effort, low impact) +- Any **Quick Wins** that could be prioritized early in the cycle +- Any low-confidence assessments (due to vague descriptions or codebase uncertainty) +- In batch mode: any capacity concerns (e.g., multiple Features with heavy QE effort) + +Wait for user feedback before recommending `/apply`. + +## Output + +- `.artifacts/sizing/{context}/02-assessment.md` + +## When This Phase Is Done + +Report your results: +- Summary table of all assessments +- Highlights (XXL flags, Jira disagreements, capacity concerns) +- Confidence level for each assessment + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/sizing/skills/controller.md b/sizing/skills/controller.md new file mode 100644 index 00000000..ae261f7e --- /dev/null +++ b/sizing/skills/controller.md @@ -0,0 +1,119 @@ +--- +name: controller +description: Top-level workflow controller that manages phase transitions for Feature sizing. +--- + +# Sizing Workflow Controller + +You are the workflow controller. Your job is to manage the sizing workflow by +executing phases and handling transitions between them. + +## Phases + +1. **Ingest** (`/ingest`) — `ingest.md` + Fetch Feature(s) from Jira and explore the codebase to understand impact. + +2. **Assess** (`/assess`) — `assess.md` + Apply the sizing rubric, produce overall sizes and per-team effort breakdowns. + +3. **Apply** (`/apply`) — `apply.md` + Write assessed sizes to Jira and add team breakdown comments. + +## Workspace + +All working artifacts are stored in `.artifacts/sizing/{context}/` where +context depends on the input mode: + +- **Single Feature:** `{issue-key}` (e.g., `.artifacts/sizing/EDM-2324/`) +- **Batch (Fix Version):** kebab-case slug of the version name (e.g., `.artifacts/sizing/1-5/` for Fix Version "1.5") + +| Artifact | File | Written by | +|----------|------|------------| +| Feature context | `01-context.md` | `/ingest` | +| Sizing assessment | `02-assessment.md` | `/assess` | + +## How to Execute a Phase + +1. **Announce** the phase to the user: *"Starting /assess."* +2. **Read** the skill file from the list above (e.g., `assess.md`) +3. **Execute** the skill's steps — the user should see your progress +4. When the skill is done, it will tell you to report findings and + re-read this controller. Do that — then use "Recommending Next Steps" + below to offer options. +5. Present the skill's results and your recommendations to the user +6. **Stop and wait** for the user to tell you what to do next + +## Recommending Next Steps + +After each phase completes, present the user with **options** — not just one +next step. + +### Typical Flow + +```text +ingest → assess → apply +``` + +### What to Recommend + +- `/ingest` completed → recommend `/assess` (apply the rubric to produce sizes) +- `/assess` completed → recommend `/apply` (write sizes to Jira). If the user + disagrees with any assessment, recommend adjusting the rationale or re-running + `/assess` with additional context before applying. +- `/apply` completed → done. The workflow is complete. + +### Re-running Phases + +- If the user provides additional context after `/assess` (e.g., "this Feature + is riskier than it looks because..."), offer to re-run `/assess` to + incorporate the new information. +- If new Features were added to the Fix Version after initial ingestion, offer + to re-run `/ingest` to pick up the new Features. + +### How to Present Options + +Lead with your top recommendation, then list alternatives briefly: + +```text +Recommended next step: /assess — apply the sizing rubric to produce recommendations. + +Other options: +- /apply — if you already have sizes you want to write to Jira +- /ingest — if there are additional Features to include +``` + +## Starting the Workflow + +Before dispatching any phase, check if the project has its own `AGENTS.md` +or `CLAUDE.md`. If so, read it — it may contain project-specific conventions +that affect how the workflow operates. + +When the user provides a Jira issue key or URL: +1. Execute the **ingest** phase in single-Feature mode +2. After ingestion, present results and wait + +When the user provides a release identifier (e.g., `release:EDM:1.3.0`): +1. Execute the **ingest** phase in batch mode — map `release:{project}:{version}` + to `project = {project} AND fixVersion = "{version}"` in JQL +2. After ingestion, present results and wait + +If the user invokes a specific command (e.g., `/assess`), execute that phase +directly — don't force them through earlier phases. + +## Error Handling + +If any phase fails (Jira MCP errors, codebase exploration issues): + +1. **Stop immediately.** Do not advance to the next phase. +2. **Report the error** to the user with the specific error message. +3. **Offer options:** retry the failed step, skip the Feature (in batch mode), + or escalate. + +Do not fabricate sizes when a tool call fails. Do not silently continue +past errors. + +## Rules + +- **Never auto-advance.** Always wait for the user between phases. +- **Recommendations come from this file, not from skills.** Skills report findings; this controller decides what to recommend next. +- **Jira writes require explicit approval.** Never write to Jira without the user saying "yes" to a dry-run preview. diff --git a/sizing/skills/ingest.md b/sizing/skills/ingest.md new file mode 100644 index 00000000..010af389 --- /dev/null +++ b/sizing/skills/ingest.md @@ -0,0 +1,191 @@ +--- +name: ingest +description: Fetch Feature(s) from Jira and explore the codebase to understand sizing impact. +--- + +# Ingest Sizing Context Skill + +You are a technical researcher. Your job is to fetch Feature data from Jira +and explore the codebase to understand the scope and impact of each Feature, +producing the raw material that the assessment phase needs to determine sizes. + +## Your Role + +Gather two types of information for each Feature: (1) what the Feature +requires (from Jira) and (2) what it would take to build (from the codebase). +This is lighter than a design-level exploration — the goal is surface area +estimation, not architectural deep-dive. + +## Critical Rules + +- **Read-only for Jira.** Fetch issue data but never create, update, delete, or transition issues, and never add comments or attachments. +- **Capture, don't assess.** Record what you find — sizing decisions happen in `/assess`. +- **Follow lateral links only (one level deep).** If the Feature has linked issues from related projects, fetch them for context. Do not follow child issues (Epics, Stories) — those may not exist yet. Do not follow links-of-links. +- **Codebase exploration is scoped.** Focus on areas the Feature will affect. Target 5–10 key files per Feature that establish the scope of change, not a full codebase survey. + +## Process + +### Step 1: Determine Input Mode + +The user will provide one of: +- **A Jira issue key** (e.g., `EDM-2324`) or URL → single-Feature mode +- **A release identifier** (e.g., `release:EDM:1.3.0`) → batch mode. + Format is `release:{project}:{version}`. Map to + `project = {project} AND fixVersion = "{version}"` in JQL. + +### Step 2: Create Artifact Directory + +**Single mode:** +```bash +mkdir -p .artifacts/sizing/{issue-key} +``` + +**Batch mode:** +```bash +mkdir -p .artifacts/sizing/{fix-version-slug} +``` + +Where `{fix-version-slug}` is the Fix Version name converted to kebab-case: +lowercase all characters, replace dots and spaces with hyphens +(e.g., "1.5" → `1-5`, "1.3.0" → `1-3-0`, "Release 2.0" → `release-2-0`). + +### Step 2a: Check for Existing Context + +If `.artifacts/sizing/{context}/01-context.md` already exists, a prior ingest +has been run. Check whether `.artifacts/sizing/{context}/02-assessment.md` +also exists. If it does, warn the user: "Re-running /ingest will overwrite +the existing context. The current assessment will become stale and /assess +should be re-run afterward." Wait for the user to confirm before proceeding. + +If only `01-context.md` exists (no assessment yet), proceed without warning — +overwriting pre-assessment context is safe. + +### Step 3: Fetch Feature(s) from Jira + +**Single mode:** Fetch the issue using the provided key. After fetching, +verify the issue type is Feature. If it is not, warn the user: "Issue {key} +is a {type}, not a Feature. The sizing workflow is designed for Features. +Continue anyway?" Wait for confirmation before proceeding. + +**Batch mode:** Search for all Features in the specified project and Fix Version: +``` +JQL: project = {project} AND fixVersion = "{version}" AND issuetype = Feature +``` + +For each Feature, fetch with fields that include the Size custom field: +``` +fields: summary,description,status,priority,labels,fixVersions,customfield_10795,created,updated +``` + +Also fetch comments (all) for each Feature. + +Capture: +- Summary / title +- Description (full text, preserving any section structure) +- Acceptance criteria / Definition of Done (if present in description) +- Status, priority, labels, fix version +- Current Size value (`customfield_10795` — may be null/unset) +- Comments (substantive only — skip bot notifications and status changes) + +If the fetch fails (authentication error, invalid issue key), report the +error to the user and stop. In batch mode, if the query returns zero +Features, tell the user no Features were found for the specified project +and Fix Version — suggest verifying the project key, version name, and +issue types in Jira — and stop. + +### Step 4: Fetch Linked Issues (If Available) + +For each Feature, check for lateral linked issues (blocks, relates to, etc.). +Fetch at minimum: summary, description, status, relationship type. + +Do **not** follow child issues (Epics, Stories). Do not follow links-of-links. +Not all Features will have linked issues — this step is opportunistic. + +### Step 5: Explore the Codebase + +For each Feature, based on its description, identify which areas of the +codebase would be affected. Focus on: + +1. **Component boundaries:** Which packages, modules, or services would this + Feature touch? +2. **Integration points:** Which APIs, external systems, or cross-service + interactions are involved? +3. **Data model impact:** What existing models/schemas would need to change + or extend? +4. **Testing patterns:** What testing infrastructure exists? Would new test + types or frameworks be needed? +5. **Novelty:** Is this extending existing patterns or introducing new ones? + +Use file search (glob), content search (grep), and targeted file reading. +Target 5–10 key files per Feature. If the last 2–3 files explored introduced +no new insights, exploration is likely complete. + +If the codebase doesn't provide enough signal (e.g., the Feature describes +an entirely new subsystem with no existing code), note the uncertainty +explicitly — this increases the risk/unknowns dimension during assessment. + +### Step 6: Compile Context + +Write `.artifacts/sizing/{context}/01-context.md`: + +```markdown +# Sizing Context — {context} + +## Input + +- **Mode:** {Single Feature | Batch — Fix Version "{name}"} +- **Features:** {count} +- **Date:** {today} + +## Feature: {issue-key} — {title} + +### Jira Metadata + +- **Status:** {status} +- **Priority:** {priority} +- **Labels:** {labels} +- **Fix Version:** {version} +- **Current Size:** {value or "Not set"} + +### Description Summary + +{Condensed description preserving key requirements, user stories, and + acceptance criteria. Not a full copy — focus on what drives sizing: + scope, capabilities, constraints.} + +### Codebase Impact + +- **Affected components:** {list with paths} +- **Integration points:** {APIs, external systems, cross-service interactions} +- **Data model changes:** {expected schema impact or "None identified"} +- **Testing surface:** {existing test infrastructure, new test types needed} +- **Novelty assessment:** {extending existing patterns | new patterns required | uncertain} + +### Linked Issues + +{Brief summary of lateral linked issues, or "None."} + +{Repeat the "## Feature:" block for each Feature in batch mode} +``` + +### Step 7: Report to User + +Present a brief summary: +- How many Features were ingested +- Input mode (single or batch with Fix Version name) +- Key codebase areas explored per Feature +- Any Features with insufficient descriptions for confident sizing +- Any Features that already have a Size set in Jira + +## Output + +- `.artifacts/sizing/{context}/01-context.md` + +## When This Phase Is Done + +Report your findings: +- Features ingested and their current state +- Codebase impact highlights +- Any concerns about description quality or codebase uncertainty + +Then **re-read the controller** (`controller.md`) for next-step guidance. From aa3b7eb7cff7bc2e8d57df89cf9b94c57e874f6c Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Fri, 29 May 2026 19:33:49 +0300 Subject: [PATCH 2/2] Address CodeRabbit review feedback Promote Step 5b (Sizing Consistency Check) to Step 6 in decompose.md and renumber subsequent steps for sequential integrity. Add command syntax note to sizing README clarifying that bare phase names are tool-agnostic. Co-Authored-By: Claude Opus 4.6 (1M context) --- design/skills/decompose.md | 34 +++++++++++++++++----------------- sizing/README.md | 7 +++++++ 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/design/skills/decompose.md b/design/skills/decompose.md index 7c5cd23e..be0a62d4 100644 --- a/design/skills/decompose.md +++ b/design/skills/decompose.md @@ -109,7 +109,7 @@ Write `.artifacts/design/{issue-number}/04-epics.md`: {PRD Requirements column: list the primary requirements for quick reference. If an epic maps to more than ~8 requirements, list the most significant and add "See coverage matrix for full mapping." The coverage matrix - (Step 6) is the authoritative source for requirement-to-story traceability.} + (Step 7) is the authoritative source for requirement-to-story traceability.} ## Dependency Order @@ -341,7 +341,7 @@ 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 +### Step 6: Sizing Consistency Check After sizing all epics, verify plausibility: @@ -359,9 +359,9 @@ After sizing all epics, verify plausibility: 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. + before proceeding to Step 7. -### Step 6: Write Coverage Matrix +### Step 7: Write Coverage Matrix Write `.artifacts/design/{issue-number}/06-coverage.md`: @@ -390,7 +390,7 @@ Write `.artifacts/design/{issue-number}/06-coverage.md`: If none: "All stories trace to PRD requirements."} ``` -### Step 7: Verify Artifact Structure +### Step 8: Verify Artifact Structure Quick sanity check before invoking the decomposition review. Verify: @@ -403,7 +403,7 @@ Quick sanity check before invoking the decomposition review. Verify: If structural issues are found, fix them before proceeding. Do not invoke a review on incomplete artifacts. -### Step 8: Review Decomposition +### Step 9: Review Decomposition Review the decomposition for structural quality and requirement coverage. This review operates independently from the design document — @@ -424,7 +424,7 @@ subagent for independence. Load it with: - NOT the design document (`03-design.md`) — the reviewer evaluates the artifacts on their own merits -Retain the subagent's ID for use in Step 10 — resuming the same +Retain the subagent's ID for use in Step 11 — resuming the same reviewer gives it memory of its previous findings and concerns, producing more coherent follow-up reviews. @@ -439,9 +439,9 @@ severity definitions from the protocol. The subagent path provides stronger independence; the inline path still catches issues by forcing a perspective shift. -### Step 9: Validate and Assess Findings +### Step 10: Validate and Assess Findings -For each finding from Step 8: +For each finding from Step 9: 1. **Validate the reference.** Confirm the cited artifact file and section exist. Discard any finding that references a file or section @@ -464,13 +464,13 @@ For each finding from Step 8: Only fix findings that add real value. Do not make changes for structural preferences not grounded in the evaluation criteria. -### Step 10: Re-Review (if fixes were made) +### Step 11: Re-Review (if fixes were made) -If Step 9 produced changes to the decomposition artifacts: +If Step 10 produced changes to the decomposition artifacts: 1. Obtain a re-review of the updated artifacts: - **If a subagent was used in Step 8 and the runtime supports agent + **If a subagent was used in Step 9 and the runtime supports agent resumption:** Resume the same reviewer agent. Send it the updated artifacts and a summary of fixes applied. This gives the reviewer memory of its original findings and lets it verify they were @@ -490,13 +490,13 @@ If Step 9 produced changes to the decomposition artifacts: - Whether fixes were applied correctly - Whether fixes introduced new issues 2. If new issues are found, fix them following the same validate-and- - assess procedure from Step 9 + assess procedure from Step 10 3. Cap at 2 review-fix rounds total. Decomposition fixes are structural and less likely than code fixes to need multiple iterations. -If no fixes were needed in Step 9, the review passes immediately. +If no fixes were needed in Step 10, the review passes immediately. -### Step 11: Report Review Summary +### Step 12: Report Review Summary ```markdown ## Decomposition Review Summary @@ -511,7 +511,7 @@ If no fixes were needed in Step 9, the review passes immediately. list them with their file, section, and issue description.} ``` -### Step 12: Present to User +### Step 13: Present to User Present the decomposition and highlight: - Number of epics and stories @@ -519,7 +519,7 @@ Present the decomposition and highlight: - Any coverage gaps - Stories that might need size adjustment (too large or too small) - Any assumptions or judgment calls in the decomposition -- Decomposition review summary (from Step 11) +- Decomposition review summary (from Step 12) If the decomposition review gate reported FLAG, present the unfixed CRITICAL/HIGH findings and ask the user to decide how to handle them. diff --git a/sizing/README.md b/sizing/README.md index de395658..cc10dc7e 100644 --- a/sizing/README.md +++ b/sizing/README.md @@ -9,6 +9,13 @@ A pre-cycle Feature sizing workflow that assesses Jira Features using T-shirt si | Jira access (MCP or CLI) | Yes | Fetch Features, write Size field, add comments | | Git | Yes | Codebase exploration | +## Command Syntax + +Examples in this document use bare phase names (`/ingest`, `/assess`, `/apply`). +The actual invocation syntax depends on your AI tool — e.g., `/sizing:ingest` +in Claude Code, `/sizing-ingest` in Cursor. See your tool's documentation for +the exact command format. + ## Phases | Phase | Command | Purpose | Artifact(s) |