@chris1807/claude-kit 2.1.49 → 2.1.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.49",
+  "version": "2.1.51",
   "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/create-work-item.md

@@ -195,6 +195,8 @@ For a **Bug**, **User Story**, or **Hot Fix**, every work item this command crea
 
 Estimate using the same rubric as `/quote`: the **modified Fibonacci scale** (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** in a codebase they know. Don't pad for ramp-up, routine architectural decisions, or stack familiarity — only for things a senior cannot shortcut: genuinely novel work, unresolved open questions, cross-team coordination, external dependencies. If the work looks larger than 21 points, recommend splitting the item instead of proposing a number.
 
+Repetition and boilerplate are assisted work — price them near the bottom of the range and size the item by its hardest distinct problem, not by how many files it touches. The full assisted / not-assisted breakdown lives in `/quote` Step 2; that file is the authority if the two ever drift.
+
 Present the estimate:
 
 ```
@@ -328,19 +330,43 @@ Apply this pass to every section (Description, Acceptance Criteria, Steps to Rep
 
 The Step 3 draft is **one document for the user to read**, not the shape of one field. Before rendering, split it section by section and route each section to its own Azure DevOps field:
 
-| Draft section | Goes to | Notes |
-|---|---|---|
-| `### Description` | `System.Description` | Plus the mockup `<img>`, user-supplied images, `Production Impact` (Hot Fix), `Out of Scope`, and `Open Questions` |
-| `### Acceptance Criteria` | `Microsoft.VSTS.Common.AcceptanceCriteria` | **Never** also in the description |
-| `### Steps to Reproduce` | `Microsoft.VSTS.TCM.ReproSteps` (Bug / Hot Fix) | Falls back to the description only if the type doesn't expose the field |
-| `### Expected Behavior`, `### Actual Behavior` | `Microsoft.VSTS.TCM.ReproSteps` | Rendered beneath the repro steps |
-| `### Out of Scope`, `### Environment / Scope`, `### Open Questions` | `System.Description` | These keep their `<h3>` headings — they have no field of their own |
+**Routing depends on the work item type, and the types do not carry the same fields.** This matters more than it looks: **Azure DevOps accepts a write to a field a type does not have.** The value persists and reads back over the API while no form ever renders it — nothing raises, nothing logs. So a wrong field here is invisible in exactly the way a bug report should never be.
+
+Verify with `mcp__azure-devops__wit_work_item` (`action: get_type`) rather than assuming. In the CSI Development process:
+
+**User Story** — Description and Acceptance Criteria, as you would expect:
+
+| Draft section | Goes to |
+|---|---|
+| `### Description` | `System.Description` — plus the mockup `<img>`, user-supplied images, `Out of Scope`, `Open Questions` |
+| `### Acceptance Criteria` | `Microsoft.VSTS.Common.AcceptanceCriteria` — **never** also in the description |
+
+**Bug** — its form renders only **Repro Steps** and **System Info**. It has **no Acceptance Criteria field**, and `System.Description` has **no control on the Bug form**, so anything routed there is invisible to a human reader:
+
+| Draft section | Goes to |
+|---|---|
+| `### Description`, `### Steps to Reproduce`, `### Expected Behavior`, `### Actual Behavior`, `### Acceptance Criteria`, `### Open Questions` | `Microsoft.VSTS.TCM.ReproSteps` — composed into one document, each under its own `<h3>`, in that order |
+| `### Environment / Scope` | `Microsoft.VSTS.TCM.SystemInfo` |
+| (the same composed body) | `System.Description` — a labelled **duplicate**, for tools that read it without checking the type. Never unique content. |
+
+Do **not** send `Microsoft.VSTS.Common.AcceptanceCriteria` on a Bug. Still *write* acceptance criteria — they go into the composed body, so the item is still estimable — just not into a field the type does not have.
+
+**Hot Fix** — its form renders **Description** and **Repro Steps**. It has neither an Acceptance Criteria field nor a System Info field:
+
+| Draft section | Goes to |
+|---|---|
+| `### Description`, `### Production Impact`, `### Open Questions` | `System.Description` |
+| `### Steps to Reproduce`, `### Expected Behavior`, `### Actual Behavior`, `### Environment / Scope` | `Microsoft.VSTS.TCM.ReproSteps` |
+
+**Omit an empty section entirely** — never emit a bare `<h3>` with nothing under it. A heading with no body reads as content that went missing.
 
 **The rendered `System.Description` must not contain an "Acceptance Criteria" heading or its criteria** — not as `<h3>`, not as `<strong>`, not as a bolded line, not "for readability", not "so it reads as a complete document". Azure DevOps renders the AC field as its own section on the work item form, so a copy in the description gives the reader two lists that drift apart while leaving the real field empty. It also breaks estimation: an empty AC field is exactly what `/quote`, `/quote-backlog`, and `/plan-backlog` read to decide an item can't be sized, so criteria in the wrong field make a fully-specified story look unestimable and bounce it back to its creator.
 
 **Drop the section's own heading when it becomes a field.** `Microsoft.VSTS.Common.AcceptanceCriteria` holds the criteria list alone — an `<ol>` or `<ul>`, not `<h3>Acceptance Criteria</h3>` followed by the list. Same for `ReproSteps`. The field label is already on the form.
 
-**Always write the AC field explicitly — never leave the placeholder.** Some process templates seed a new item's `Microsoft.VSTS.Common.AcceptanceCriteria` with tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. That is a **placeholder, not content**, and it reads as non-empty to every downstream sweep — an item carrying it looks like it has acceptance criteria when it has none. Include the field in the create call for every Bug, Hot Fix, and User Story; writing it is what clears the placeholder.
+**On a type that HAS the AC field, always write it explicitly — never leave the placeholder.** Some process templates seed a new item's `Microsoft.VSTS.Common.AcceptanceCriteria` with tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. That is a **placeholder, not content**, and it reads as non-empty to every downstream sweep — an item carrying it looks like it has acceptance criteria when it has none. Writing the field is what clears the placeholder.
+
+This applies to **User Story**. It does **not** apply to Bug or Hot Fix: neither type carries the field, so there is no placeholder to clear and the write would go into a hole. For those two, the criteria live in `ReproSteps` per the routing above — which is also what `/quote` and `/quote-backlog` read to decide a bug is estimable.
 
 ### Call the create API
 
@@ -350,20 +376,24 @@ Call `mcp__azure-devops__wit_create_work_item` with:
 - **workItemType**: `Feature`, `Bug`, `User Story`, or `Hot Fix` (two words, exact casing)
 - **title**: the approved title (with prefix)
 - **fields**: a JSON Patch document setting:
-  - `System.Description` — the rendered HTML description (with embedded mockup `<img>` and any user-supplied images)
-  - `Microsoft.VSTS.Common.AcceptanceCriteria` — the rendered criteria list and **only** the criteria (no `<h3>Acceptance Criteria</h3>` wrapper, and no copy of it in `System.Description`). Always include this field for a Bug, Hot Fix, or User Story — writing it is what clears the process template's placeholder tip
+  - `System.Description` — the rendered HTML description (with embedded mockup `<img>` and any user-supplied images). On a **Bug** this is the labelled duplicate of the composed body, not the description alone
+  - `Microsoft.VSTS.Common.AcceptanceCriteria` — **User Story only.** The rendered criteria list and **only** the criteria (no `<h3>Acceptance Criteria</h3>` wrapper, and no copy of it in `System.Description`); writing it is what clears the process template's placeholder tip. **Do not send this field on a Bug or a Hot Fix** — neither type has it
   - `Microsoft.VSTS.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped, and **always** for a Feature)
   - For Features:
     - Render `Business Value`, `Scope`, `Out of Scope`, and `Success Criteria` into the description. Put `Success Criteria` in `Microsoft.VSTS.Common.AcceptanceCriteria` **only if** the process template exposes that field on Feature — if the create call rejects it, fold the block into the description and retry rather than dropping it.
     - `Microsoft.VSTS.Common.BusinessValue` — only if the user supplied a number. Never invent one.
     - Omit `Microsoft.VSTS.Scheduling.StoryPoints` entirely.
-  - For Bugs and Hot Fixes:
-    - `Microsoft.VSTS.TCM.ReproSteps` — the rendered HTML repro steps (Azure DevOps puts repro steps in this field for the Bug template; if the project uses the Agile template instead, fold repro steps into Description). If the `Hot Fix` type in this process template doesn't expose `ReproSteps`, fold the repro steps into `System.Description` rather than dropping them.
-    - For Hot Fixes, render the `Production Impact` section into the description as an `<h3>` block above the repro steps.
+  - For Bugs:
+    - `Microsoft.VSTS.TCM.ReproSteps` — the **whole composed body**: description, steps, expected behavior, actual behavior, acceptance criteria and open questions, each under its own `<h3>`. This is the Bug's field of record; its form shows no Description control.
+    - `Microsoft.VSTS.TCM.SystemInfo` — the `Environment / Scope` section. Omit the field entirely when there is no environment to record, rather than writing an empty value that leaves a blank box on the form.
     - `Microsoft.VSTS.Common.Priority` — the chosen Priority (1–4)
     - `Microsoft.VSTS.Common.Severity` — the chosen Severity (`1 - Critical`, `2 - High`, `3 - Medium`, `4 - Low`)
+  - For Hot Fixes:
+    - `Microsoft.VSTS.TCM.ReproSteps` — steps, expected behavior, actual behavior and `Environment / Scope` (this type has no System Info field). If the `Hot Fix` type in this process template doesn't expose `ReproSteps`, fold them into `System.Description` rather than dropping them.
+    - Render the `Production Impact` section into `System.Description` as an `<h3>` block above the description body.
+    - No Priority/Severity — a Hot Fix is urgent by definition.
 
-If the `Open Questions` section is non-empty, append it to the description as a clearly-labeled HTML block (`<h3>Open Questions</h3><ul>...</ul>`) so the assignee can address it later.
+If the `Open Questions` section is non-empty, append it as a clearly-labeled HTML block (`<h3>Open Questions</h3><ul>...</ul>`) **to the field that work item type displays** — the composed `ReproSteps` body on a **Bug**, `System.Description` on a **User Story**, **Hot Fix**, or **Feature**. Putting it in the description of a Bug hides it from every reader.
 
 ### Move to Dev Ready (pointed items only)
 
@@ -410,12 +440,22 @@ If a story fails to create or link, report which ones succeeded and which didn't
 
 ## Step 10: Confirm
 
-**Read the item back first.** Fetch it with `mcp__azure-devops__wit_work_item` (`action: get`, fields `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria`) and check two things:
+**Read the item back first**, and check the fields that type actually renders — a write to a field the type lacks *succeeds*, so reading back the wrong field proves nothing.
+
+For a **User Story**, fetch `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria`:
 
 1. The criteria are in `Microsoft.VSTS.Common.AcceptanceCriteria` — not the placeholder tip, not empty.
 2. `System.Description` contains no "Acceptance Criteria" heading and none of the criteria.
 
-If either check fails the write didn't take — fix it with `wit_update_work_item` before reporting success. Don't report a created item you haven't read back.
+For a **Bug**, fetch `Microsoft.VSTS.TCM.ReproSteps` and `Microsoft.VSTS.TCM.SystemInfo`:
+
+1. `ReproSteps` carries every section — description, steps, expected, actual, acceptance criteria — each under its own heading.
+2. The environment is in `SystemInfo`.
+3. No section appears **only** in `System.Description`, which the Bug form does not display.
+
+For a **Hot Fix**, fetch `System.Description` and `Microsoft.VSTS.TCM.ReproSteps`, and confirm the narrative is in the former and the reproduction detail in the latter.
+
+If a check fails the write didn't take — fix it with `wit_update_work_item` before reporting success. Don't report a created item you haven't read back.
 
 After creation, report:
 

package/templates/commands/edit-work-item.md

@@ -15,6 +15,7 @@ Read the work item with `expand: Relations` so links and children come back. Col
 - `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`
 - `Microsoft.VSTS.Scheduling.StoryPoints`, `Custom.Order`
 - For Bugs / Hot Fixes: `Microsoft.VSTS.TCM.ReproSteps`, `Microsoft.VSTS.Common.Priority`, `Microsoft.VSTS.Common.Severity`
+- For Bugs: `Microsoft.VSTS.TCM.SystemInfo` — the Bug form's second rendered field, where the environment belongs
 - Parent, children, and **linked pull requests** (`ArtifactLink` relations)
 - Comments — recent discussion often explains why a field says what it says
 
@@ -200,14 +201,20 @@ Default the comment question to **yes** for any item past `New`, and **no** for
 
 Render every Markdown section to HTML first — Azure DevOps description and acceptance criteria fields do not render Markdown. Use the conversion table and the **emphasis and code spans** rules from `/create-work-item` Step 8: bold the noun phrase carrying each claim, wrap identifiers in `<code>`, use lists for 2+ parallel items, keep `### Headings` as `<h3>`. Preserve existing `<img>` tags exactly.
 
-**Route each section to its own field**, per the field-routing table in `/create-work-item` Step 8. The rule that matters most here: **acceptance criteria go in `Microsoft.VSTS.Common.AcceptanceCriteria`, never in `System.Description`.** When you rewrite AC, write the criteria list alone into that field — no `<h3>Acceptance Criteria</h3>` wrapper — and make sure the description you write back carries no copy of them. Editing an item is the moment this gets silently undone: it is easy to render the whole reviewed document into the description and leave the AC field as it was.
+**Route each section to its own field, per work item type** — use the routing tables in `/create-work-item` Step 8. Editing is the moment routing gets silently undone: it is easy to render the whole reviewed document into the description and leave the real fields as they were. And a wrong field does not announce itself — **Azure DevOps accepts a write to a field a type does not carry**, so the value persists, reads back over the API, and renders nowhere.
 
-**Repair misfiled criteria when you find them.** If Step 2 found the criteria living in the description (or the AC field holding only placeholder tip text), fix it as part of this edit even when the user didn't ask — it is the same content, moved to the field Azure DevOps and every kit sweep actually read:
+**On a User Story:** acceptance criteria go in `Microsoft.VSTS.Common.AcceptanceCriteria`, never in `System.Description`. Write the criteria list alone into that field — no `<h3>Acceptance Criteria</h3>` wrapper — and make sure the description carries no copy of them.
 
-- Write the criteria into `Microsoft.VSTS.Common.AcceptanceCriteria`, overwriting the placeholder.
-- Strip the "Acceptance Criteria" heading and its list out of `System.Description` in the same call, so the two fields don't both hold a copy.
-- Say so in the change set and in the Step 8 confirmation: `Acceptance criteria: moved from Description → AC field (3 criteria)`. Never move criteria silently; the user needs to see that the description shrank.
-- This is a **move, not a rewrite** — the criteria text is unchanged unless the user separately approved a reword.
+**On a Bug:** there is no Acceptance Criteria field and no Description control on the form. The whole write-up — description, steps, expected, actual, criteria — belongs in `Microsoft.VSTS.TCM.ReproSteps`, the environment in `Microsoft.VSTS.TCM.SystemInfo`, and `System.Description` holds only a labelled duplicate of the body.
+
+**On a Hot Fix:** the narrative stays in `System.Description`; steps, expected, actual and environment go to `Microsoft.VSTS.TCM.ReproSteps`. There is no System Info field on this type.
+
+**Repair misfiled content when you find it.** If Step 2 found content in a field its type does not render, fix it as part of this edit even when the user didn't ask — it is the same content, moved to where a reader will actually see it:
+
+- **User Story** — criteria living in the description (or an AC field holding only placeholder tip text): write them into `Microsoft.VSTS.Common.AcceptanceCriteria` and strip the heading and list out of `System.Description` in the same call.
+- **Bug** — criteria sitting in `Microsoft.VSTS.Common.AcceptanceCriteria` (a field the type does not have, so nothing displays them) or a description that never appears on the form: fold both into the composed `ReproSteps` body. Leave the phantom AC value where it is rather than patching it — clearing a field the type lacks is one more write into a hole.
+- Say so in the change set and in the Step 8 confirmation: `Acceptance criteria: moved from the AC field → Repro Steps (3 criteria)`. Never move content silently; the user needs to see which field shrank.
+- This is a **move, not a rewrite** — the text is unchanged unless the user separately approved a reword.
 
 Apply writes in this order, so a failure partway through leaves the most useful state behind:
 

package/templates/commands/implement.md

@@ -194,9 +194,9 @@ Propose the hours from the parent's Story Points (this mirrors `/plan-backlog` S
 | 13 | 48 hrs  |
 | 21 | 75 hrs  |
 
-Calibrated for a **senior developer** at ~6 productive hours per day — the discount is already in the numbers, so don't apply a second one. Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
+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.
 
-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 calibration. Say which basis you used.
+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.
 
 Show the proposal and **wait for the user**:
 

package/templates/commands/plan-backlog.md

@@ -108,21 +108,23 @@ Fetch the work item again (Description and Acceptance Criteria fields) if not al
 
 ### 5b. Map Story Points → total hour budget
 
-> **Assume a senior developer is the implementer.** The hour budget below already discounts for senior-level speed — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast. Do not add a separate "experience" discount on top of these numbers.
+> **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.
+>
+> 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 at ~6 productive hours per day):
+Use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
 | 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 a senior) |
-| 8  | 28 hrs  | multi-area, real unknowns even for a senior |
+| 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 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 seniority doesn't help.
+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.
 
 ### 5c. Draft the single task
 

package/templates/commands/plan-sprint.md

@@ -125,21 +125,23 @@ Fetch the work item again (Description and Acceptance Criteria fields — Repro
 
 ### 6b. Derive the hour budget
 
-> **Assume a senior developer is the implementer.** The hour budget below already discounts for senior-level speed — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast. Do not add a separate "experience" discount on top of these numbers.
+> **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.
+>
+> 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 at ~6 productive hours per day):
+**If the item has Story Points**, use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
 | 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 a senior) |
-| 8  | 28 hrs  | multi-area, real unknowns even for a senior |
+| 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 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 seniority doesn't help.
+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.
 
 **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.
 

package/templates/commands/quote-backlog.md

@@ -182,7 +182,11 @@ This is read-only reconnaissance. Skip it for non-technical items or when the co
 
 Use the **modified Fibonacci scale**: `1, 2, 3, 5, 8, 13, 21`. Anything larger than 21 is flagged as "needs to be split" rather than given a number.
 
-> **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack — that's already priced into the rubric. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies. Do not apply a second seniority discount on top of the rubric.
+> **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack — that's already priced into the rubric. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies. Do not apply a second seniority discount, or a second Claude-assistance discount, on top of the rubric.
+
+**Assisted work — price near the bottom of the range:** boilerplate and scaffolding, tests for already-specified behavior, mechanical refactors, applying a known pattern across many files, CRUD/forms/screens that mirror something already in the repo. Repetition is cheap — size the item by its hardest distinct problem, not by how many files it touches.
+
+**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 |
 |--------|-----------|

package/templates/commands/quote.md

@@ -16,6 +16,29 @@ Use the **modified Fibonacci scale** for story points: `1, 2, 3, 5, 8, 13, 21`.
 
 > **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack. A senior is expected to read the codebase, find existing patterns, and resolve ordinary unknowns without help — that effort is already priced into the rubric below. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies.
 
+**Claude assistance is part of the baseline, so price these near the bottom of their range** — the rubric already assumes them, don't discount a second time:
+
+- Boilerplate and scaffolding — DTOs, mappers, interfaces, request/response models, registrations.
+- Writing tests for behavior that's already specified.
+- Mechanical refactors, renames, and applying a known pattern across many files.
+- CRUD endpoints, forms, tables, and screens that mirror something already in the repo.
+- Migrations and scripts with an obvious shape.
+
+**Volume of similar code is cheap.** A story whose size comes mostly from repetition — six more fields, four more columns, another slice of an existing pattern — should not earn points for its file count. Size it by the hardest distinct problem in it, not by how much typing it implies.
+
+**Claude assistance does not compress these — never discount them:**
+
+- Ambiguous, thin, or missing acceptance criteria (see the *not estimable* rule below).
+- Genuinely novel design decisions with no precedent in the codebase.
+- Third-party integrations, external APIs, and anything gated on another system's behavior.
+- Cross-team coordination, sign-off, or a dependency on someone else's work landing first.
+- Data migrations against production data, and anything needing a rollback plan.
+- Security, compliance, or privacy review.
+- Infrastructure, pipeline, and environment work that has to be verified by hand.
+- Human wall-time: code review turnaround, UAT, and deploy gates.
+
+These are what dominate an estimate at 8 points and above. If a big number is driven purely by code volume rather than by items on this list, the estimate is probably too high.
+
 Rough sizing rubric (calibrated for a senior developer, assisted by Claude, working in a codebase they know):
 
 | Points | Looks like |
@@ -30,7 +53,9 @@ Rough sizing rubric (calibrated for a senior developer, assisted by Claude, work
 
 Adjust upward for: unclear acceptance criteria, missing UX, data migrations, cross-team coordination, security/compliance review, or anything tagged `spike`/`research`.
 
-Adjust downward for: pure config changes, mechanical refactors with good test coverage, work that mirrors an existing implementation, or anything where the senior will recognize the pattern immediately.
+Adjust downward for: pure config changes, mechanical refactors with good test coverage, work that mirrors an existing implementation, repetition of an established pattern, or anything where the senior will recognize the pattern immediately.
+
+State the assist in the reasoning when it moved the number — e.g. "5 rather than 8: the three new endpoints follow `PaymentsController` exactly, so the volume is assisted work; the only real unknown is the reconciliation rule." That makes the estimate reviewable instead of asserted.
 
 If the item has child items, size each child as well and present the parent's total as the sum (rounded to the nearest Fibonacci number).