@chris1807/claude-kit 2.1.51 → 2.1.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.51",
+  "version": "2.1.52",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/commands/implement.md

@@ -182,21 +182,35 @@ If **more than one** open Task exists, don't guess — list them and ask which o
 
 This includes the case where child Tasks exist but every one of them is already closed — a closed Task is not somewhere to log new work.
 
-Propose the hours from the parent's Story Points (this mirrors `/plan-backlog` Step 5b — keep the two tables in sync):
+The parent's Story Points give the **band**; the complexity of the work picks the number **inside** it (this mirrors `/plan-backlog` Step 5b — keep the two tables in sync). Never take the top of the band by default.
 
-| Points | Hour budget |
-|--------|-------------|
-| 1  |  3 hrs  |
-| 2  |  6 hrs  |
-| 3  | 10 hrs  |
-| 5  | 16 hrs  |
-| 8  | 28 hrs  |
-| 13 | 48 hrs  |
-| 21 | 75 hrs  |
+| Points | Low | Medium | High | Band in days (a day = 6 hrs) |
+|--------|-----|--------|------|------------------------------|
+| 1  |   1 |  1.5 |   2 | under 2 hours |
+| 2  |   2 |  2.5 |   3 | 2 hours to half a day |
+| 3  |   3 |    6 |  12 | half a day to two days |
+| 5  |  12 |   18 |  24 | two to four days |
+| 8  |  24 |   30 |  36 | around a week |
+| 13 |  36 |   48 |  60 | one to two weeks |
+| 21 |  60 |   75 |  90 | two to three weeks |
 
-Calibrated for a **senior developer working with Claude assistance** at ~6 productive hours per day — both discounts are already in the numbers, so don't apply a second one. Boilerplate, tests for specified behavior, and mechanical refactors are assisted work; the hours that remain are the human ones (novel decisions, verification, review, UAT). Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
+The bands are **contiguous**: each starts where the one below it ends, so a 1-pointer never costs more than a 2-pointer's floor. A day is **6 productive hours**, a week is **5 days (30 hours)**.
 
-If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — using the same senior-with-Claude calibration. Say which basis you used.
+Calibrated for a **senior developer working with Claude assistance** at ~6 productive hours per day — both discounts are already in the numbers, so don't apply a second one. Boilerplate, tests for specified behavior, and mechanical refactors are assisted work; the hours that remain are the human ones (novel decisions, verification, review, UAT). Round non-Fibonacci point values up to the nearest row. Hours are rounded to the nearest half hour at 1–2 points and to a whole hour from 3 points up.
+
+**Complexity is not size.** Points already carry the size — how much work there is. Complexity is how *hard* that work is: how many decisions are still open, how novel the shape is, how costly it is to get wrong. A large-but-boring story is high points at **low** complexity. Never default to the High column just because the points are high.
+
+- **Low** — the shape is known before starting. One layer, or an existing pattern in the codebase to copy. AC is unambiguous. No new integration, no migration, no state or permission logic. Tests are mechanical.
+- **Medium** — crosses layers, or touches an area with no exact precedent. A few real decisions, some edge cases to reason through, existing tests need reworking. This is the default when nothing pushes the item either way.
+- **High** — novel design with nothing to copy; external or third-party contract; data migration or backfill; concurrency, state machines, permissions, money, or PII; ambiguous or self-contradicting AC; wide blast radius; behavior that is hard to verify.
+
+Pick **one** band and hold a one-phrase reason for it — that phrase is shown with the proposal. When an item sits between two bands, take the **lower** one unless a High signal above is actually present.
+
+Tags like `spike`, `research`, or `unknown-stack` are High-complexity signals on their own — use the High column for them rather than adding a separate percentage.
+
+By Step 4 you have the approved Step 3 plan in hand — judge complexity from that plan, not from the points. A plan that is mostly "add a field, thread it through, follow the existing pattern" is Low even at 8 points; a plan with an open design question or a migration in it is High even at 3.
+
+If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — judging size and complexity the same way. Say which basis you used.
 
 Show the proposal and **wait for the user**:
 
@@ -205,9 +219,10 @@ AB#{id} has no open child Task — one is needed to log hours against.
 
 | Task title                                   | Hours |
 |----------------------------------------------|-------|
-| {PREFIX} - Implement: {short summary}        |  16   |
+| {PREFIX} - Implement: {short summary}        |  18   |
 
-Basis: {n} story points → {n}h  (or: no points — estimated from the approved plan)
+Basis: {n} story points ({low}/{mid}/{high} band), {complexity} complexity — {one-phrase reason} → {n}h
+       (or: no points — estimated from the approved plan, {complexity} complexity)
 
 Create it? (yes / edit / skip)
 ```
@@ -475,10 +490,10 @@ For each wave in ascending order:
      ```
      Stories in this wave with no open child Task:
 
-     | Story    | Task title                              | Hours | Basis   |
-     |----------|-----------------------------------------|-------|---------|
-     | AB#1235  | COM - Implement: export endpoint        |  10   | 3 pts   |
-     | AB#1236  | COM - Implement: export screen          |  16   | 5 pts   |
+     | Story    | Task title                              | Hours | Basis                  |
+     |----------|-----------------------------------------|-------|------------------------|
+     | AB#1235  | COM - Implement: export endpoint        |   3   | 3 pts, low cx          |
+     | AB#1236  | COM - Implement: export screen          |  18   | 5 pts, medium cx       |
 
      Create these? (yes / edit N / skip N / skip all)
      ```

package/templates/commands/plan-backlog.md

@@ -93,7 +93,7 @@ Continue? (yes / cancel)
 
 Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 5a–5c is independent per story, so pre-compute all proposals in parallel with the `Workflow` tool instead of analyzing one story at a time.
 
-- Fan out **one agent per story** that does 5a–5c — re-read the story, map points → budget, draft the single task — and returns a structured proposal (story id, points, budget, and one `{title, hours}` task). Use a `schema` so each agent returns validated JSON.
+- Fan out **one agent per story** that does 5a–5c — re-read the story, map points → band, judge complexity, pick within the band, draft the single task — and returns a structured proposal (story id, points, complexity, one-phrase complexity reason, band, and one `{title, hours}` task). Use a `schema` so each agent returns validated JSON, with `complexity` constrained to `low | medium | high`.
 - Then run Step 5's loop **using the pre-computed proposals** — but keep 5d (approval) and 5e (creation) exactly as written: present each proposal, wait for `yes / edit / skip / cancel-all`, and create the task only after approval. **Never fan out the approval or the work-item creation** — those stay sequential and interactive.
 
 If ultracode is off, ignore this and run Step 5 the normal sequential way. The output is identical either way; ultracode only makes the analysis faster for large backlogs.
@@ -106,45 +106,62 @@ For each remaining story, in order:
 
 Fetch the work item again (Description and Acceptance Criteria fields) if not already cached. You need the AC text to write an accurate task title.
 
-### 5b. Map Story Points → total hour budget
+### 5b. Map Story Points → hour band, then pick within it by complexity
 
-> **Assume a senior developer working with Claude assistance is the implementer.** The hour budget below already discounts for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
+> **Assume a senior developer working with Claude assistance is the implementer.** The hour bands below already discount for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
 >
 > The hours that survive the assist are the human ones: understanding the requirement, the genuinely novel decisions, verification, review turnaround, and UAT. If a budget looks large only because the story touches many files, it's too large.
 
-Use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
+**Points give the band. Complexity picks the number inside it.** Never take the top of the band by default — that is what makes every estimate max out. Low complexity → the low end, medium → the middle, high → the high end.
 
-| Points | Hour budget | Notes |
-|--------|-------------|-------|
-| 1  |  3 hrs  | trivial change |
-| 2  |  6 hrs  | small, one-layer change |
-| 3  | 10 hrs  | one feature slice, modest tests |
-| 5  | 16 hrs  | cross-layer or new component (routine for an assisted senior) |
-| 8  | 28 hrs  | multi-area, real unknowns the assist doesn’t remove |
-| 13 | 48 hrs  | large feature — should probably be split |
-| 21 | 75 hrs  | very large — almost certainly split |
+Bands (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
-If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the story has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where neither seniority nor the assist helps.
+| Points | Low | Medium | High | Band in days (a day = 6 hrs) |
+|--------|-----|--------|------|------------------------------|
+| 1  |   1 |  1.5 |   2 | under 2 hours |
+| 2  |   2 |  2.5 |   3 | 2 hours to half a day |
+| 3  |   3 |    6 |  12 | half a day to two days |
+| 5  |  12 |   18 |  24 | two to four days |
+| 8  |  24 |   30 |  36 | around a week |
+| 13 |  36 |   48 |  60 | one to two weeks — likely needs splitting |
+| 21 |  60 |   75 |  90 | two to three weeks — almost certainly split |
+
+The bands are **contiguous**: each one starts where the one below it ends, so a 1-pointer never costs more than a 2-pointer's floor. A day is **6 productive hours** and a week is **5 days (30 hours)** — every row above is a whole number of days once you leave the 1–2 point rows.
+
+If the points value isn't on the Fibonacci scale, round to the nearest row above. Hours are rounded to the nearest half hour at 1–2 points and to a whole hour from 3 points up.
+
+**Complexity is not size.** Points already carry the size — how much work there is. Complexity is how *hard* that work is: how many decisions are still open, how novel the shape is, how costly it is to get wrong. A large-but-boring story is high points at **low** complexity. Never default to the High column just because the points are high.
+
+- **Low** — the shape is known before starting. One layer, or an existing pattern in the codebase to copy. AC is unambiguous. No new integration, no migration, no state or permission logic. Tests are mechanical.
+- **Medium** — crosses layers, or touches an area with no exact precedent. A few real decisions, some edge cases to reason through, existing tests need reworking. This is the default when nothing pushes the item either way.
+- **High** — novel design with nothing to copy; external or third-party contract; data migration or backfill; concurrency, state machines, permissions, money, or PII; ambiguous or self-contradicting AC; wide blast radius; behavior that is hard to verify.
+
+Pick **one** band and hold a one-phrase reason for it — that phrase is shown with the proposal. When an item sits between two bands, take the **lower** one unless a High signal above is actually present.
+
+Tags like `spike`, `research`, or `unknown-stack` are High-complexity signals on their own — use the High column for them rather than adding a separate percentage.
 
 ### 5c. Draft the single task
 
 Create **exactly one task** covering all the work for the story — implementation, tests, code review revisions, and UAT support are all rolled into it. Do not split the story into design/backend/frontend/test tasks.
 
 - **Title**: `{Prefix} - Implement: {short summary of the story}` — use the same product prefix as the parent (e.g. `COM`, `PAY`, `CDA`), extracted from the parent's title.
-- **Hours**: the full hour budget from 5b, rounded to a whole hour.
+- **Hours**: the number picked in 5b — band from points, position in the band from complexity — rounded to a whole hour.
 
 ### 5d. Show the proposal
 
 ```
 ─────────────────────────────────────────────────────────────
-AB#{id}: {title}      ({points} pts → {budget} hrs)
+AB#{id}: {title}      ({points} pts, {complexity} complexity → {budget} hrs)
 ─────────────────────────────────────────────────────────────
 
 Proposed child task:
 
 | Task title                                     | Hours |
 |------------------------------------------------|-------|
-| {Prefix} - Implement: payments CSV export      |  24   |
+| {Prefix} - Implement: payments CSV export      |  18   |
+
+Complexity: medium — crosses API and client, follows the existing export pattern
+Band for 5 pts: 12 / 18 / 24  (two to four days)
 
 Approve? (yes / edit / skip / cancel-all)
 ```

package/templates/commands/plan-sprint.md

@@ -1,6 +1,6 @@
 Sweep the **current sprint** for user stories and bugs without child tasks and propose a single implementation task per item with an hour estimate. Usage: `/plan-sprint [project]`
 
-This command finds every **User Story** and **Bug** in the current sprint of a chosen Azure DevOps project that **has no child tasks yet**, and — item by item — proposes **one child Task** with an hour estimate for the user to approve before any work items are created. Exactly one task per work item — never a multi-task breakdown.
+This command finds every **User Story** and **Bug** in the current sprint of a chosen Azure DevOps project that **has no child tasks yet**, and — item by item — proposes **one child Task** with an hour estimate (points set the band, complexity sets where in the band it lands) for the user to approve before any work items are created. Exactly one task per work item — never a multi-task breakdown.
 
 This is the sprint-planning counterpart of `/plan-backlog`. Use `/plan-backlog` to groom the unscheduled backlog; use `/plan-sprint` after items are pulled into the sprint to make sure each has its implementation task and hours.
 
@@ -110,7 +110,7 @@ Continue? (yes / cancel)
 
 Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 6a–6c is independent per item, so pre-compute all proposals in parallel with the `Workflow` tool instead of analyzing one item at a time.
 
-- Fan out **one agent per item** that does 6a–6c — re-read the item, derive the hour budget, draft the single task — and returns a structured proposal (item id, points, budget, and one `{title, hours}` task). Use a `schema` so each agent returns validated JSON.
+- Fan out **one agent per item** that does 6a–6c — re-read the item, map points → band, judge complexity, pick within the band, draft the single task — and returns a structured proposal (item id, points, complexity, one-phrase complexity reason, band, and one `{title, hours}` task). Use a `schema` so each agent returns validated JSON, with `complexity` constrained to `low | medium | high`.
 - Then run Step 6's loop **using the pre-computed proposals** — but keep 6d (approval) and 6e (creation) exactly as written: present each proposal, wait for `yes / edit / skip / cancel-all`, and create the task only after approval. **Never fan out the approval or the work-item creation** — those stay sequential and interactive.
 
 If ultracode is off, ignore this and run Step 6 the normal sequential way. The output is identical either way; ultracode only makes the analysis faster for large sprints.
@@ -125,50 +125,67 @@ Fetch the work item again (Description and Acceptance Criteria fields — Repro
 
 ### 6b. Derive the hour budget
 
-> **Assume a senior developer working with Claude assistance is the implementer.** The hour budget below already discounts for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
+> **Assume a senior developer working with Claude assistance is the implementer.** The hour bands below already discount for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
 >
 > The hours that survive the assist are the human ones: understanding the requirement, the genuinely novel decisions, verification, review turnaround, and UAT. If a budget looks large only because the story touches many files, it's too large.
 
-**If the item has Story Points**, use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
+**Points give the band. Complexity picks the number inside it.** Never take the top of the band by default — that is what makes every estimate max out. Low complexity → the low end, medium → the middle, high → the high end.
 
-| Points | Hour budget | Notes |
-|--------|-------------|-------|
-| 1  |  3 hrs  | trivial change |
-| 2  |  6 hrs  | small, one-layer change |
-| 3  | 10 hrs  | one feature slice, modest tests |
-| 5  | 16 hrs  | cross-layer or new component (routine for an assisted senior) |
-| 8  | 28 hrs  | multi-area, real unknowns the assist doesn’t remove |
-| 13 | 48 hrs  | large feature — should probably be split |
-| 21 | 75 hrs  | very large — almost certainly split |
+**If the item has Story Points**, use these bands (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
-If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the item has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where neither seniority nor the assist helps.
+| Points | Low | Medium | High | Band in days (a day = 6 hrs) |
+|--------|-----|--------|------|------------------------------|
+| 1  |   1 |  1.5 |   2 | under 2 hours |
+| 2  |   2 |  2.5 |   3 | 2 hours to half a day |
+| 3  |   3 |    6 |  12 | half a day to two days |
+| 5  |  12 |   18 |  24 | two to four days |
+| 8  |  24 |   30 |  36 | around a week |
+| 13 |  36 |   48 |  60 | one to two weeks — likely needs splitting |
+| 21 |  60 |   75 |  90 | two to three weeks — almost certainly split |
 
-**If the item has no Story Points**, estimate the hours directly from the description, acceptance criteria, and repro steps — judge which row of the table the work most resembles and use that hour budget. Mark the proposal `(no points — estimated from description)` and suggest `/quote AB#{id}` in the final summary. Do **not** set Story Points on the item — that's the user's call.
+The bands are **contiguous**: each one starts where the one below it ends, so a 1-pointer never costs more than a 2-pointer's floor. A day is **6 productive hours** and a week is **5 days (30 hours)** — every row above is a whole number of days once you leave the 1–2 point rows.
+
+If the points value isn't on the Fibonacci scale, round to the nearest row above. Hours are rounded to the nearest half hour at 1–2 points and to a whole hour from 3 points up.
+
+**Complexity is not size.** Points already carry the size — how much work there is. Complexity is how *hard* that work is: how many decisions are still open, how novel the shape is, how costly it is to get wrong. A large-but-boring story is high points at **low** complexity. Never default to the High column just because the points are high.
+
+- **Low** — the shape is known before starting. One layer, or an existing pattern in the codebase to copy. AC is unambiguous. No new integration, no migration, no state or permission logic. Tests are mechanical.
+- **Medium** — crosses layers, or touches an area with no exact precedent. A few real decisions, some edge cases to reason through, existing tests need reworking. This is the default when nothing pushes the item either way.
+- **High** — novel design with nothing to copy; external or third-party contract; data migration or backfill; concurrency, state machines, permissions, money, or PII; ambiguous or self-contradicting AC; wide blast radius; behavior that is hard to verify.
+
+Pick **one** band and hold a one-phrase reason for it — that phrase is shown with the proposal. When an item sits between two bands, take the **lower** one unless a High signal above is actually present.
+
+Tags like `spike`, `research`, or `unknown-stack` are High-complexity signals on their own — use the High column for them rather than adding a separate percentage.
+
+**If the item has no Story Points**, judge both axes from the description, acceptance criteria, and repro steps: which row the *size* of the work most resembles, then which column its *complexity* falls in. Mark the proposal `(no points — estimated from description)` and suggest `/quote AB#{id}` in the final summary. Do **not** set Story Points on the item — that's the user's call.
 
 ### 6c. Draft the single task
 
 Create **exactly one task** covering all the work for the item — implementation, tests, code review revisions, and UAT support are all rolled into it. Do not split the item into design/backend/frontend/test tasks.
 
 - **Title**: `{Prefix} - Implement: {short summary of the item}` — use the same product prefix as the parent (e.g. `COM`, `PAY`, `CDA`), extracted from the parent's title. For Bugs, `{Prefix} - Fix: {short summary}` reads better.
-- **Hours**: the full hour budget from 6b, rounded to a whole hour.
+- **Hours**: the number picked in 6b — band from points, position in the band from complexity — rounded to a whole hour.
 
 ### 6d. Show the proposal
 
 ```
 ─────────────────────────────────────────────────────────────
-AB#{id}: {title}      ({points} pts → {budget} hrs)
+AB#{id}: {title}      ({points} pts, {complexity} complexity → {budget} hrs)
 ─────────────────────────────────────────────────────────────
 
 Proposed child task:
 
 | Task title                                     | Hours |
 |------------------------------------------------|-------|
-| {Prefix} - Implement: payments CSV export      |  24   |
+| {Prefix} - Implement: payments CSV export      |  18   |
+
+Complexity: medium — crosses API and client, follows the existing export pattern
+Band for 5 pts: 12 / 18 / 24  (two to four days)
 
 Approve? (yes / edit / skip / cancel-all)
 ```
 
-For unpointed items, the header line reads `(no points — estimated from description → {budget} hrs)`.
+For unpointed items, the header line reads `(no points — estimated from description, {complexity} complexity → {budget} hrs)`.
 
 **Wait for the user.**
 

package/templates/commands/quote-backlog.md

@@ -188,15 +188,17 @@ Use the **modified Fibonacci scale**: `1, 2, 3, 5, 8, 13, 21`. Anything larger t
 
 **Not assisted — never discount:** thin or missing AC, novel design with no precedent, third-party integrations, cross-team dependencies, production data migrations, security/compliance review, hand-verified infra or pipeline work, and human wall-time for review/UAT/deploy gates. These are what justify 8 points and above.
 
-| Points | Looks like |
-|--------|-----------|
-| **1** | Trivial change — copy tweak, single config value, one-line fix |
-| **2** | Small, well-understood change in one file or one layer |
-| **3** | A couple of files / one feature slice, some new tests |
-| **5** | Crosses layers, or a new component/endpoint following existing patterns |
-| **8** | Multi-area change with real new logic, migrations, or non-trivial edge cases |
-| **13** | Large feature, several moving parts — likely benefits from being split |
-| **21** | Very large / high uncertainty — should almost certainly be split |
+| Points | Effort (a day = 6 hrs) | Looks like |
+|--------|----------------------|-----------|
+| **1** | under 2 hours | Trivial change — copy tweak, single config value, one-line fix |
+| **2** | 2 hours to half a day | Small, well-understood change in one file or one layer |
+| **3** | half a day to two days | A couple of files / one feature slice, some new tests |
+| **5** | two to four days | Crosses layers, or a new component/endpoint following existing patterns |
+| **8** | around a week | Multi-area change with real new logic, migrations, or non-trivial edge cases |
+| **13** | one to two weeks | Large feature, several moving parts — likely benefits from being split |
+| **21** | two to three weeks | Very large / high uncertainty — should almost certainly be split |
+
+The **effort column is a sanity check on the number, not the way to pick it** — a point value that implies four days for something a senior finishes before lunch is wrong regardless of how the description reads. A day is **6 productive hours**; a week is 5 days (30 hours). `/plan-backlog` Step 5b turns the point value back into a Task hour band, so these two scales have to agree.
 
 Fold in what 3d found — code reconnaissance that shrinks or grows the work changes the number. For items classified **Blocking gaps** or **appears already implemented**, propose **no points** — the comment is the deliverable for those.
 

package/templates/commands/quote.md

@@ -41,15 +41,17 @@ These are what dominate an estimate at 8 points and above. If a big number is dr
 
 Rough sizing rubric (calibrated for a senior developer, assisted by Claude, working in a codebase they know):
 
-| Points | Looks like |
-|--------|-----------|
-| **1** | Trivial change — copy tweak, single config value, one-line fix. No new tests needed. |
-| **2** | Small, well-understood change in one file or one layer. Existing patterns cover it. |
-| **3** | Touches a couple of files / one feature slice. Some new tests. No architectural questions. |
-| **5** | Crosses layers (e.g. API + UI), or introduces a new component/endpoint following existing patterns. Real test coverage needed. |
-| **8** | Multi-area change with meaningful new logic, migrations, or non-trivial edge cases. Unknowns a senior can resolve but that still take real wall-time. |
-| **13** | Large feature, several moving parts, or significant unknowns even for a senior. Likely benefits from being split. |
-| **21** | Very large / high uncertainty. Should almost certainly be split into multiple stories. |
+| Points | Effort (a day = 6 hrs) | How much is known | Looks like |
+|--------|----------------------|-------------------|-----------|
+| **1** | under 2 hours | everything | Trivial change — copy tweak, single config value, one-line fix. No new tests needed. |
+| **2** | 2 hours to half a day | almost everything | Small, well-understood change in one file or one layer. Existing patterns cover it. |
+| **3** | half a day to two days | most of it | Touches a couple of files / one feature slice. Some new tests. No architectural questions. |
+| **5** | two to four days | some open questions | Crosses layers (e.g. API + UI), or introduces a new component/endpoint following existing patterns. Real test coverage needed. |
+| **8** | around a week | little — real unknowns | Multi-area change with meaningful new logic, migrations, or non-trivial edge cases. Unknowns a senior can resolve but that still take real wall-time. |
+| **13** | one to two weeks | not much | Large feature, several moving parts, or significant unknowns even for a senior. Likely benefits from being split. |
+| **21** | two to three weeks | almost nothing | Very large / high uncertainty. Should almost certainly be split into multiple stories. |
+
+The **effort column is a sanity check on the number, not the way to pick it** — a point value that implies four days for something a senior finishes before lunch is wrong regardless of how the description reads. A day is **6 productive hours**; a week is 5 days (30 hours). `/plan-backlog` Step 5b turns the point value back into a Task hour band, so these two scales have to agree.
 
 Adjust upward for: unclear acceptance criteria, missing UX, data migrations, cross-team coordination, security/compliance review, or anything tagged `spike`/`research`.
 

package/templates/commands/rework.md

@@ -162,19 +162,21 @@ Every rework round gets its own Task work item, parented under the original User
 
 ### Suggest hours
 
-Estimate the rework effort from the approved plan. Use this rubric — calibrate against scope, not abstract complexity:
+Estimate the rework effort from the approved plan. The rows below are **scope** — how much there is to change. Where you land between two adjacent rows is **complexity** — how settled the change is:
+
+A day is **6 productive hours**; a week is 5 days (30 hours).
 
 | Hours | Looks like |
 |-------|-----------|
 | **0.5** | Trivial — copy tweak, single config value, one-line fix. No new tests. |
 | **1**   | One file, well-understood change. Maybe one new/updated test. |
 | **2**   | 2–3 files, one layer, follows existing patterns. Some new tests. |
-| **4**   | Multiple files across layers, or new logic in one area. Real test coverage. |
-| **8**   | Most of a day — meaningful new logic, several files, edge cases. |
-| **16**  | Two days — significant rework, multiple unknowns to resolve. |
-| **24+** | Three days or more — flag that this rework probably should have been a fresh story. |
+| **3**   | Half a day — multiple files across layers, or new logic in one area. Real test coverage. |
+| **6**   | A full day — meaningful new logic, several files, edge cases. |
+| **12**  | Two days — significant rework, multiple unknowns to resolve. |
+| **18+** | Three days or more — flag that this rework probably should have been a fresh story. |
 
-Adjust upward for: ambiguous feedback, missing UX, data migrations, regression risk in unrelated areas. Adjust downward for: pure config changes or mechanical fixes.
+Take the **lower** of two adjacent rows for low-complexity rework — mechanical fixes, pure config, a pattern already used elsewhere in the file. Take the **higher** for high-complexity rework — ambiguous feedback, missing UX, data migrations, or regression risk in unrelated areas. Don't reach for the top of the ladder just because the round touches several files.
 
 ### Prompt the user
 

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -111,14 +111,15 @@ These rules apply to **every** command or flow that creates or estimates work it
 
 1. **Every work item Claude creates gets a proposed story point estimate** — User Stories and Bugs are never created unpointed by default. Estimates use the modified Fibonacci scale (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** — no ramp-up padding; pad only for what seniority + Claude can't shortcut (novel work, missing AC, cross-team coordination, external dependencies).
 2. **The user must agree before points are written.** Claude proposes the number with a one-line rationale; the user confirms, adjusts (their number wins), or skips. Points are never set silently.
-3. **Setting points moves the item to Dev Ready.** Any time story points are written to a **User Story**, **Bug**, or **Hot Fix**, `System.State` is set to `Dev Ready` in the same update. Never for Features or Tasks (a Feature's state is never touched; Tasks carry hour estimates, not points), and never backward — an item already past Dev Ready keeps its state, with a note.
-4. **An item that can't be quoted drops out of the estimating queue — by a mechanism that depends on its type.** When `/quote` or `/quote-backlog` can't produce a number because information is missing — no acceptance criteria (or, on a bug, no repro steps), contradictory description, unbounded scope, or a possible duplicate the creator has to confirm — the item drops out of the sweep along with the feedback comment, so the next run isn't re-analyzing items still waiting on their creator:
+3. **Task hours come from complexity, not from the top of the points band.** Story points give a Task an hour *band* (low / medium / high). Which end of that band the estimate lands on is decided by the complexity of the work, judged separately from its size: low complexity → the low end, medium → the middle, high → the high end. Points already carry size, so a big-but-routine story is a high-points, low-complexity Task and gets low-end hours. The bands are contiguous and anchored to a **6-hour day** (1 pt = under 2 hrs, 2 pts = up to half a day, 3 pts = half a day to 2 days, 5 pts = 2–4 days, 8 pts = about a week, and up) — a 1-pointer can never cost more than a 2-pointer's floor. Every hour proposal states the band and the complexity call that picked within it. See `/plan-backlog` Step 5b for the table and the complexity rubric.
+4. **Setting points moves the item to Dev Ready.** Any time story points are written to a **User Story**, **Bug**, or **Hot Fix**, `System.State` is set to `Dev Ready` in the same update. Never for Features or Tasks (a Feature's state is never touched; Tasks carry hour estimates, not points), and never backward — an item already past Dev Ready keeps its state, with a note.
+5. **An item that can't be quoted drops out of the estimating queue — by a mechanism that depends on its type.** When `/quote` or `/quote-backlog` can't produce a number because information is missing — no acceptance criteria (or, on a bug, no repro steps), contradictory description, unbounded scope, or a possible duplicate the creator has to confirm — the item drops out of the sweep along with the feedback comment, so the next run isn't re-analyzing items still waiting on their creator:
    - **User Story** → moves from `Design Approved` back to `Design Review`. Only from `Design Approved`; an item at `Dev Ready` or anything `Active` or later keeps its state.
    - **Bug / Hot Fix** → gets a **`needs-info` tag**, state left at `New`. **These types have no design states** in the CSI Development template — no `Design Review` and no `Design Approved` — so there is no earlier state to send them back to. Append to `System.Tags`; never overwrite the field. Removing the tag re-queues the bug.
    - **Feature / Task** → neither; report the gap and stop.
 
    An item that merely **needs to be split** keeps its state and gets no tag — the work is understood, nothing is missing.
-5. **Never assume two work item types share a state list.** WIQL doesn't validate state names, so a query filtering on a state the type doesn't have returns **zero rows instead of an error** — the classic symptom is a backlog sweep that silently never surfaces a single bug. Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) before writing a state name into a query or an update. In CSI Development: `User Story` has `New → Dev Ready → In Design → Design Review → Design Approved → Active → …`; `Bug` and `Hot Fix` have `New → Dev Ready → Active → …`.
+6. **Never assume two work item types share a state list.** WIQL doesn't validate state names, so a query filtering on a state the type doesn't have returns **zero rows instead of an error** — the classic symptom is a backlog sweep that silently never surfaces a single bug. Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) before writing a state name into a query or an update. In CSI Development: `User Story` has `New → Dev Ready → In Design → Design Review → Design Approved → Active → …`; `Bug` and `Hot Fix` have `New → Dev Ready → Active → …`.
 
 ### Branching Strategy
 
@@ -240,7 +241,7 @@ Running `/implement` on a **Feature** implements its child User Stories in **wav
 
 **Work item states:** `/implement` moves the work item to `Active` when implementation starts — for a single work item (User Story, Bug, Hot Fix) right after the branch is created; for a Feature, each child story goes `Active` as its wave begins. When the PR is created, each implemented child **User Story** moves to `Code Review` — the **Feature's state is never changed**. The Feature is a parent container; it advances only as its child stories are verified/closed. Only child **Tasks** are ever closed — never the stories or the Feature.
 
-**Hours live on the Task.** `/implement` will not implement a story that has no open child Task: if there isn't one, it proposes a title and an hour estimate (from the story's points, same mapping `/plan-backlog` uses) and creates it once the user agrees — exactly one per story, inheriting the parent's assignee, area, and iteration. When the PR is created, that Task is closed with the hours worked logged to `CompletedWork` and `RemainingWork` zeroed. Closing happens at **PR creation**, not at merge, so hours are recorded while they're still known. Never enable Azure DevOps's "Complete associated work items" when merging — it transitions the parent too.
+**Hours live on the Task.** `/implement` will not implement a story that has no open child Task: if there isn't one, it proposes a title and an hour estimate (from the story's points, same mapping `/plan-backlog` uses — points set the hour band, complexity picks where in the band it lands) and creates it once the user agrees — exactly one per story, inheriting the parent's assignee, area, and iteration. When the PR is created, that Task is closed with the hours worked logged to `CompletedWork` and `RemainingWork` zeroed. Closing happens at **PR creation**, not at merge, so hours are recorded while they're still known. Never enable Azure DevOps's "Complete associated work items" when merging — it transitions the parent too.
 
 #### Slash Commands Reference