@chris1807/claude-kit 2.3.3 → 2.3.5

package/README.md

@@ -692,7 +692,7 @@ Claude reviews for:
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, bugs in `New` (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Also audits the drop-out queue — tagged bugs and stories bounced to Design Review — for items whose creator answered but which nobody returned to the sweep |
 | `/quote` | `/quote AB#1234` | Estimate a work item in story points (senior-calibrated Fibonacci rubric) |
 | `/explain` | `/explain AB#1234` | Summarize and explain a work item in plain language |
-| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, User Story, or Hot Fix — proposes story points (user must agree), creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves. Runs automatically for any plain-language request to create a work item |
+| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, User Story, or Hot Fix — opens each with a plain-English Summary for the PM, then code-grounded Technical Details for the developer, proposes story points (user must agree), creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves. Runs automatically for any plain-language request to create a work item |
 | `/edit-work-item` | `/edit-work-item AB#1234 [what to change]` | Revise an existing work item field-by-field. On a Feature, cascades into its child stories — updates, adds, retires, and re-sequences `Custom.Order` waves — with a safety gate on anything already past Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged feature/work branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks --dry-run` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "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

@@ -51,7 +51,7 @@ You can paste as much detail as you want — I'll structure it.
 Scan the user's response for:
 
 - Direct image URLs (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`)
-- Azure DevOps attachment URLs (e.g. `https://dev.azure.com/.../_apis/wit/attachments/...`)
+- Azure DevOps attachment URLs (e.g. `https://dev.azure.com/.../_apis/wit/attachments/...`) — to look at one before drafting, fetch it with `mcp__azure-devops__wit_work_item_attachment` (the attachment GUID and file name come out of that URL)
 - Markdown image syntax (`![alt](url)`)
 - Pasted screenshot blob paths or local file paths to images
 
@@ -77,7 +77,34 @@ If you find nothing, say so in one line rather than omitting the section — "no
 
 ## Step 3: Develop the Plan
 
-Translate the user's free-form requirements into a structured work item draft. The shape depends on the type:
+Translate the user's free-form requirements into a structured work item draft. The shape depends on the type, but every type serves **two readers**:
+
+- **The PM** reads the **Summary** at the top: plain English, no code.
+- **The developer and Claude Code** read everything below it: **technical**, specific, and grounded in the actual codebase. It should be enough to plan and implement the change without rediscovering where it lives.
+
+Neither part substitutes for the other. A plain-English item is unimplementable, and an item that is only technical leaves the PM guessing.
+
+### The Summary — every type, always first
+
+Every work item starts with a **plain-English Summary** written for someone who has never seen the code: a PM, a stakeholder, a support lead. It is the first section of the draft and the first thing on the work item form (Step 8 routes it).
+
+- **2–4 sentences** covering what is changing (or what is broken), who notices, and why it matters. On a Bug or Hot Fix, say what people see go wrong, who is affected, and what "fixed" looks like to them.
+- **No technical vocabulary.** That means no code identifiers, file, field, or endpoint names, framework or database names, status codes, or unexplained acronyms. Name things the way a user sees them: the screen, the button, the report, the email. Write "The **Export** button on the Payments page shows an error instead of downloading the file," not "`GET /api/payments/export` returns 500."
+- **No code spans.** If a sentence seems to need one, rewrite the sentence. Bold the one key outcome if it helps; the rest is plain prose.
+- **Not a copy of the Technical Details.** The Summary is what a PM could repeat in a meeting. The sections below it carry the detail the team needs.
+
+Check it before showing the draft: could a PM understand every word without asking a developer? If not, rewrite it.
+
+### Technical Details — everything below the Summary
+
+The **Technical Details** section replaces a plain-language description. It and the sections after it (acceptance criteria, repro steps, prior art) are written for the developer and for Claude Code running `/implement`. Use the real vocabulary:
+
+- **Ground it in the code.** Start from what Step 2's codebase search found, then read enough of the relevant code to name what changes. Use real file paths, components, classes, services, endpoints and routes, collections or tables, fields, enums, and config keys, all in code spans. Never invent a path or a name. If you couldn't confirm something, mark it **(unverified)**.
+- **Say what changes and where, layer by layer.** Cover the UI (screens, components, routes), the API (endpoints, request and response shape, validation), services and business rules, data (new or changed fields, indexes, migrations or backfills), permissions and roles, and integrations or background jobs. Skip a layer the work doesn't touch.
+- **Name the rules and constraints.** Include business rules, edge cases, error handling, backward compatibility, and performance or security concerns, plus anything the implementer must not break.
+- **It is not the implementation plan.** Name what changes, where, and under which rules. Leave step-by-step code to `/implement`, which plans from this section.
+- **No working codebase in the session?** Then say **"Not verified against the code"** at the top of the section and write only what the user told you. Never fill the gap with guessed paths.
+- **Sensitive data policy applies.** Never put a PII value or a credential in a work item. Refer to a sensitive field by its purpose ("the tax ID field").
 
 ### For a Feature:
 
@@ -86,16 +113,21 @@ Translate the user's free-form requirements into a structured work item draft. T
 
 **Type:** Feature
 
-### Description
-{2–4 sentences describing the capability being delivered and who it serves.
-A Feature is a container — describe the outcome, not the implementation.}
+### Summary
+{2–4 plain-English sentences for a non-technical reader — see "The Summary" above.}
+
+### Technical Details
+{The feature-level technical shape. Cover the architecture or approach, the layers and
+existing components it touches (real paths), data-model changes, integrations, and the
+shared foundation the child stories build on. Note any sequencing constraint: what must
+land first sets `Custom.Order` in Step 3F. Leave per-story detail to the stories.}
 
 ### Business Value
 {Why this is worth building — the problem it removes or the opportunity it opens.}
 
 ### Scope
 - {each coherent, independently shippable chunk of work — these become the
-  child User Stories in Step 9}
+  child User Stories in Step 3F}
 - ...
 
 ### Out of Scope
@@ -123,9 +155,15 @@ A Feature carries **no story points** and **never moves to `Dev Ready`** — siz
 
 **Type:** User Story
 
-### Description
-{2–4 sentences in plain language. Explain the user-facing behavior and the
-business or user value. Avoid implementation detail — that lives in tasks.}
+### Summary
+{2–4 plain-English sentences for a non-technical reader — see "The Summary" above.}
+
+### Technical Details
+{What changes and where, layer by layer: the UI components and routes, API endpoints
+(with request/response shape and validation), services and business rules, data fields
+and migrations, and permissions. Use real paths and names from the code. Include the
+rules, edge cases, and constraints the implementer must respect. This is what
+`/implement` plans from, and it never moves to the Task.}
 
 ### Acceptance Criteria
 1. {Given/When/Then or numbered behavior — must be testable}
@@ -153,8 +191,15 @@ business or user value. Avoid implementation detail — that lives in tasks.}
 **Priority:** {1 | 2 | 3 | 4}
 **Severity:** {1 - Critical | 2 - High | 3 - Medium | 4 - Low}
 
-### Description
-{1–2 sentences describing the observed problem in plain language.}
+### Summary
+{2–4 plain-English sentences for a non-technical reader — see "The Summary" above.}
+
+### Technical Details
+{The failing code path: the screen or component, the endpoint and the request that
+fails, and the exact error message, status, log line, or stack trace if known. Name
+the likely root cause and where it lives (real file and method), marked
+**(suspected)** unless you confirmed it in the code. Include the data condition that
+triggers it.}
 
 ### Steps to Reproduce
 1. ...
@@ -187,7 +232,7 @@ business or user value. Avoid implementation detail — that lives in tasks.}
 A Hot Fix uses the same draft shape as a Bug. Two differences:
 
 - **Severity and Priority are constrained.** A Hot Fix is by definition urgent — propose Priority `1` (or `2` at the loosest) and Severity `1 - Critical` or `2 - High`. If the requirements don't support that, the item is probably a Bug; say so before drafting.
-- **Add a `### Production Impact` section** naming what is broken right now, which environment, and roughly who is affected. This is the section the reviewer reads first on an out-of-band change.
+- **Add a `### Production Impact` section** directly after `### Summary`, naming what is broken right now, which environment, and roughly who is affected. On an out-of-band change, this is the section the reviewer reads right after the Summary. It does not replace the Summary or the Technical Details — the Summary stays plain English for the PM, the Technical Details stay the developer's.
 
 **Inferring Priority and Severity for Bugs and Hot Fixes:**
 
@@ -209,10 +254,83 @@ Propose initial values based on the requirements, then let the user override dur
 
 Severity describes user impact; Priority describes scheduling urgency. They are independent — a Sev 2 can be Priority 3 if a workaround exists.
 
+### Investment Category and Impact (every type)
+
+Every User Story, Bug and Hot Fix gets an **Investment Category** (`Custom.InvestmentCategory`) and an **Impact** (`Custom.Impact`). Both are restricted picklists on the `Agile - CSI` process, and Serena's Monthly Executive and Backlog Grooming reports rank work by them. Propose both from the requirements, show them directly under the draft title with a one-line reason, and let the user change either. A Feature gets one pair that every child story inherits — the Feature type itself has neither field, so never write them to the Feature.
+
+| Investment Category | Choose it when |
+|---------------------|----------------|
+| **Strategic Initiative** | part of a named initiative, launch, or client commitment (e.g. C2Q, the AI Assistant, Rotary) |
+| **Quick Win** | small (about 3 points or fewer) with value out of proportion to that |
+| **Risk Mitigation** | mainly reduces compliance, security, PII, data-integrity, or payment/financial risk |
+| **Maintenance** | anything else that keeps the product working or improves it. The default |
+
+| Impact | Choose it when |
+|--------|----------------|
+| **Strategic** | advances a company-level goal or a client commitment |
+| **Large** | materially changes outcomes for many users or for a client |
+| **Medium** | meaningfully improves a recurring workflow |
+| **Small** | a minor improvement for a limited audience |
+| **Tiny/One-off** | cosmetic, an edge case, or a one-time fix |
+
+Impact is the difference the item makes, not its size. Spell the values exactly as above (`Tiny/One-off` included): Azure DevOps rejects anything else. Serena's Teams wizard chooses from the same tables, so an item reads the same whichever way it was created.
+
+**Only where the process has the fields.** Every project on the `Agile - CSI` process has them (CSI Development, CST Development and the rest). Confirm once per session with `mcp__azure-devops__wit_work_item` (`action: get_type`) for the type being created; if `Custom.InvestmentCategory` and `Custom.Impact` aren't in its `fields`, leave both out of the draft, the confirmation, and the create call — writing a field the process doesn't define fails the create.
+
 ### Title Prefix
 
 The title MUST start with one of the product prefixes from the project's CLAUDE.md (e.g. `COM`, `CDA`, `PAY`, `AUD`, `SER`, `PSSF`, `TPS`, `MTG`). If the project CLAUDE.md does not define a prefix table, ask the user which prefix to use before drafting. Format is `PREFIX - Title Here`.
 
+### Step 3F: Decompose the Feature into child stories (Features only)
+
+Directly under the Feature draft, in the same message, present the decomposition as a table — one row per proposed child User Story:
+
+```
+### Decomposition Plan — {n} child stories
+
+| # | Order | Proposed title | Summary (one line) | Points | Mockup |
+|---|-------|----------------|--------------------|--------|--------|
+| 1 |   1   | {Prefix} - …   | …                  |   3    | yes    |
+| 2 |   1   | {Prefix} - …   | …                  |   2    | no     |
+| 3 |   2   | {Prefix} - …   | …                  |   5    | yes    |
+
+**Sequencing:** Order 1 (#1, #2) ships first and the two are independent.
+Order 2 (#3) needs #1's endpoint before it can render.
+
+Total: {sum} points across {n} stories.
+```
+
+The Order column comes first on purpose — it matches the wave table `/implement` prints for a Feature (`implement.md`, "Execution Waves (Custom.Order)"), so the two commands produce visually identical artifacts.
+
+**Each child is a full User Story draft.** Start from the Feature's **Scope** bullets — each one is a candidate child; if a bullet is really two stories, split it. Draft every child with the User Story shape above: its own plain-English Summary, Technical Details specific to that story (drawn from the Feature's Technical Details and the code), and testable acceptance criteria. The table's Summary column is a one-line version of that child's plain-English Summary — the same no-code rule applies, and it is the text that opens the child's description.
+
+**Every child carries the same prefix as its parent Feature.** Validate all titles up front: an unprefixed child fails at create time, after the Feature already exists.
+
+**Sizing baseline (state it in the draft, above or below the table):**
+
+```
+Story points assume a **senior developer working with Claude** — override any
+value you disagree with.
+```
+
+> **Assume a senior developer working with Claude is the implementer.** Discount for what Claude removes — boilerplate, test scaffolding, mechanical wiring, codebase search. Do NOT discount for ambiguous AC, product decisions, data migrations, cross-team coordination, or verification needing a running environment.
+
+That is the same baseline `/quote`, `/quote-backlog` and `/plan-backlog` estimate against, so a `/quote` run against a story created here should land on the same number. If the two disagree, one of them is wrong — reconcile it rather than explaining the gap away.
+
+Use the modified Fibonacci scale `1, 2, 3, 5, 8`. **No child story may be larger than 8** — a 13 means the decomposition is wrong and that child must be split again.
+
+**Count limits.** Between 2 and 10 child stories. Fewer than 2 means this should have been a User Story — say so and offer to switch the type instead of creating a one-child Feature. More than 10 means the Feature is too big — do NOT silently truncate; offer to (i) merge the smallest related stories or (ii) split this into two Features.
+
+**Order validation — run it as a check, not a vibe:**
+
+1. Orders are positive integers starting at 1, contiguous, no gaps.
+2. For every dependency "story A needs story B", require `order(B) < order(A)`. **Equal orders with a dependency between them is an error**, and so is a dependency pointing at a *higher* order.
+3. Every story at order N must be buildable against the merged state of orders 1..N-1 only — that is what "stories sharing an order are mutually independent" means.
+4. If a check fails, do not present the plan: bump the dependent story's order, renumber, and re-validate first.
+5. Render the result as the plain-language **Sequencing** paragraph shown above.
+
+**Mockups are decided per child, not per Feature.** The Feature itself never gets a mockup. Use the same UI heuristic as Step 5 (a screen, a form, a button, a workflow) to set the Mockup column. Non-UI children are marked `No mockup — non-UI work`.
+
 ### Approval
 
 After presenting the draft, ask:
@@ -223,9 +341,19 @@ Approve this draft? (yes / suggest changes / cancel)
 
 **Wait for the user.** If they suggest changes, revise the draft and present it again — repeat until they approve or cancel. Do NOT proceed to story points, mockup, or project selection until approved.
 
+For a **Feature**, that one gate approves the ENTIRE plan — the Feature and every child. Alongside ordinary wording changes, `suggest changes` covers these child-level edits:
+
+- `edit 3: <what to change>` — retitle, re-summarize, re-point, or flip the mockup flag on child 3
+- `add: <description>` — append a child, give it an order, and re-validate
+- `remove 2` — drop a child; re-check that nothing depended on it and renumber the orders to close any gap
+- `reorder 3 -> 1` — move a child between waves and re-run every ordering rule
+- `split 4` / `merge 2,3` — the two most common reactions to a decomposition
+
+After ANY of these: re-run the order validation, re-render the whole table, and re-ask the gate. Never accept approval of part of the plan.
+
 ## Step 4: Propose Story Points
 
-**Skip this step entirely for a Feature.** A Feature's size is the sum of its child stories — the Feature itself gets no `StoryPoints` value and stays in `New`. Its stories are pointed in Step 9. Go to Step 5.
+**Skip this step entirely for a Feature.** A Feature's size is the sum of its child stories — the Feature itself gets no `StoryPoints` value and stays in `New`. Its stories were pointed in Step 3F. Go to Step 5.
 
 For a **Bug**, **User Story**, or **Hot Fix**, every work item this command creates gets a story point estimate — proposed automatically, applied only with the user's agreement.
 
@@ -307,6 +435,7 @@ Before creating anything in Azure DevOps, present a final summary and ask for on
 **Title:**     {Prefix} - {title}
 **Type:**      {Feature | Bug | User Story | Hot Fix}
 **Project:**   {project}
+**Summary:**   {the plain-English Summary, in full}
 {for Bugs and Hot Fixes:}
 **Priority:**  {n}
 **Severity:**  {n - Label}
@@ -315,8 +444,9 @@ Before creating anything in Azure DevOps, present a final summary and ask for on
 **Production Impact:** {one line}
 {end for Hot Fixes}
 {for Features:}
-**Scope items:** {count} — offered as child stories after creation
+**Child stories:** {n} ({sum} points) — created with the Feature, per the approved Decomposition Plan
 {end for Features}
+**Investment Category · Impact:** {category} · {impact}{for Features: — on every child story}
 **Story Points:** {n (agreed) | skipped | n/a — Features aren't pointed}
 **Initial State:** {Dev Ready (pointed) | New (no points) | New (Feature)}
 **Mockup:**    {Embedded | Not requested | Skipped (non-UI)}
@@ -328,7 +458,7 @@ Create this work item now? (yes / edit / cancel)
 
 **Wait for the user.**
 - `yes` → proceed to Step 8
-- `edit` → ask which field to revise (title, description, AC, priority, severity, story points, project, mockup), revise it, then re-show this summary
+- `edit` → ask which field to revise (title, summary, technical details, AC, priority, severity, production impact, investment category, impact, story points, project, mockup), revise it, then re-show this summary
 - `cancel` → abort with no work item created and confirm "Cancelled — no work item created."
 
 ## Step 8: Render to HTML and Create
@@ -360,7 +490,7 @@ A description that is one long paragraph of plain prose is not acceptable — ev
 - **Lists** are used instead of comma-separated prose whenever the draft contains 2+ parallel items (steps, files, references, acceptance criteria).
 - **Section headings** *inside a field's own content* are kept — they become `<h3>` and structure the rendered output. The draft's **top-level** section headings are different: they are routing labels, not content, and the heading is dropped when its section becomes its own field (see below).
 
-Apply this pass to every section (Description, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Open Questions). Apply it equally to Bugs, Hot Fixes, and User Stories.
+Apply this pass to every section (Technical Details, Production Impact, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Prior Art, Open Questions). Apply it equally to Bugs, Hot Fixes, User Stories, Features, and every child story. **The Summary is the exception:** it gets no code spans and no identifiers (Step 3), only an optional bolded outcome.
 
 ### Split the draft into fields — acceptance criteria never go in the description
 
@@ -374,14 +504,15 @@ Verify with `mcp__azure-devops__wit_work_item` (`action: get_type`) rather than
 
 | Draft section | Goes to |
 |---|---|
-| `### Description` | `System.Description` — plus the mockup `<img>`, user-supplied images, `Out of Scope`, `Prior Art`, `Open Questions` |
+| `### Summary` | `System.Description` — the **first** block, under its own `<h3>Summary</h3>` |
+| `### Technical Details` | `System.Description`, after the Summary, followed by the mockup `<img>`, user-supplied images, `Out of Scope`, `Prior Art`, and `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`, `### Prior Art`, `### Open Questions` | `Microsoft.VSTS.TCM.ReproSteps` — composed into one document, each under its own `<h3>`, in that order |
+| `### Summary`, `### Technical Details`, `### Steps to Reproduce`, `### Expected Behavior`, `### Actual Behavior`, `### Acceptance Criteria`, `### Prior Art`, `### 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. |
 
@@ -391,9 +522,13 @@ Do **not** send `Microsoft.VSTS.Common.AcceptanceCriteria` on a Bug. Still *writ
 
 | Draft section | Goes to |
 |---|---|
-| `### Description`, `### Production Impact`, `### Prior Art`, `### Open Questions` | `System.Description` |
+| `### Summary`, `### Production Impact`, `### Technical Details`, `### Prior Art`, `### Open Questions` | `System.Description`, in that order |
 | `### Steps to Reproduce`, `### Expected Behavior`, `### Actual Behavior`, `### Environment / Scope` | `Microsoft.VSTS.TCM.ReproSteps` |
 
+**Feature** — everything renders into `System.Description`, with `### Summary` first (see the Features bullet under *Call the create API*, and Phase 1 below for where the Decomposition block goes).
+
+**The Summary always leads** the field the form displays and keeps its `<h3>Summary</h3>` heading, because it shares that field with other sections. It is never omitted.
+
 **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.
@@ -406,75 +541,117 @@ This applies to **User Story**. It does **not** apply to Bug or Hot Fix: neither
 
 ### Call the create API
 
-Call `mcp__azure-devops__wit_work_item_write` (action `create`) with:
+Call `mcp__azure-devops__wit_work_item_write` with `action: "create"`:
 
 - **project**: the chosen project
 - **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). On a **Bug** this is the labelled duplicate of the composed body, not the description alone
+- **fields**: an **array of `{name, value, format}` objects** — *not* a JSON Patch document. The title is one of them (`System.Title`), not a separate parameter. Every large-text field needs `format: "Html"` or Azure DevOps may interpret it as Markdown. Every `value` is a **string**, so numerics are stringified (`"2"`, `"3"`, `"1"`).
+
+```
+mcp__azure-devops__wit_work_item_write
+  action:       "create"
+  project:      "{project}"
+  workItemType: "User Story"
+  fields: [
+    { name: "System.Title",                             value: "{Prefix} - {title}" },
+    { name: "System.Description",                       value: "<h3>Summary</h3><p>…</p><h3>Technical Details</h3>…", format: "Html" },
+    { name: "Microsoft.VSTS.Common.AcceptanceCriteria", value: "<ol>…</ol>", format: "Html" }
+  ]
+```
+
+The example above is a **User Story**. Other types carry different fields, and getting this wrong is invisible: **Azure DevOps accepts a write to a field a work item type does not have.** The value persists and reads back over the API while no form ever renders it — nothing raises, nothing logs. Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) rather than assuming.
+
+The fields to set:
+  - `System.Title` — the approved title, with its prefix
+  - `System.Description` — the rendered HTML: the `<h3>Summary</h3>` block first, then the Technical Details, the embedded mockup `<img>` and any user-supplied images, then the remaining sections per the routing tables above. On a **Bug** this is the labelled duplicate of the composed body, not unique content
   - `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)
+  - `Custom.InvestmentCategory` and `Custom.Impact` — the approved values, on a User Story, Bug or Hot Fix. **Never on a Feature**; its pair goes on each child story instead. If a project's process rejects them, retry without them and say so in the confirmation
   - 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.
+    - Render `Summary` first, then `Technical Details`, `Business Value`, `Scope`, `Out of Scope`, `Success Criteria`, and `Prior Art`, 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:
-    - `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.ReproSteps` — the **whole composed body**: summary, technical details, steps, expected behavior, actual behavior, acceptance criteria, prior art and open questions, each under its own `<h3>`. This is the Bug's field of record; its form shows no Description control. The acceptance criteria are folded in here because the Bug type has no Acceptance Criteria field.
     - `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.
+    - Render the `Production Impact` section into `System.Description` as an `<h3>` block between the Summary and the Technical Details.
     - No Priority/Severity — a Hot Fix is urgent by definition.
 
 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)
+### Call the create API (Feature — three phases)
 
-If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_work_item_write` (action `update`) **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
+A Feature and its children are created in one run, in this order. Nothing is created until the Step 3F plan was approved.
 
-**Features are never moved.** A Feature stays in `New` and advances only as its child stories are verified and closed — the same rule `/implement` follows.
+**Phase 1 — the Feature, first.** One `mcp__azure-devops__wit_work_item_write` `action: "create"` with `workItemType: "Feature"` and the `fields[]` shape above. Capture the returned id as `{fid}`.
+
+The Feature's description is assembled in this order: the `<h3>Summary</h3>` block, then `<h3>Technical Details</h3>`, `<h3>Business Value</h3>`, and the other sections from the Features bullet above, then a `<h3>Decomposition</h3>` block, then any open questions. The Decomposition block carries the Step 3F plan **onto the work item** — an HTML `<table>` with one row per child (Order, Story, Points, Depends on, Mockup) followed by the **Sequencing** paragraph rendered as HTML. Without it the ordering rationale exists only in this chat; `/implement` re-derives the waves from `Custom.Order`, but the reviewer reading the Feature in Azure DevOps needs to see *why* the waves are ordered the way they are. (Child AB# ids do not exist yet in Phase 1 — the table names children by title.)
+
+**If Phase 1 fails, stop — create nothing else.** Creating the Feature first is precisely what makes this failure harmless.
+
+**Phase 2 — the children, in ascending execution order.** One `create` per child (`workItemType: "User Story"`), so the AB# sequence matches the wave sequence:
+
+```
+mcp__azure-devops__wit_work_item_write
+  action:       "create"
+  project:      "{project}"
+  workItemType: "User Story"
+  fields: [
+    { name: "System.Title",                             value: "{Prefix} - …" },
+    { name: "System.Description",                       value: "<h3>Summary</h3><p>…</p><h3>Technical Details</h3>…", format: "Html" },
+    { name: "Microsoft.VSTS.Common.AcceptanceCriteria", value: "<ol>…</ol>", format: "Html" },
+    { name: "Microsoft.VSTS.Scheduling.StoryPoints",    value: "3" },
+    { name: "Custom.Order",                             value: "1" },
+    { name: "Custom.InvestmentCategory",                value: "Strategic Initiative" },
+    { name: "Custom.Impact",                            value: "Large" }
+  ]
+```
 
-## Step 9: Offer Child User Stories (Features only)
+Each child is rendered and routed exactly like a standalone User Story: its own `<h3>Summary</h3>` block first, then its Technical Details, then either the mockup `<img>` from Step 5 or the `No mockup — non-UI work` note, with its criteria in `Microsoft.VSTS.Common.AcceptanceCriteria` only.
 
-Skip this step for Bugs and User Stories.
+**`Custom.Order` rejection fallback.** `Custom.Order` comes from an inherited process and may be absent from the User Story form in some projects; `Microsoft.VSTS.Scheduling.StoryPoints` is absent from some templates. If the `create` is rejected because of either, retry that child once *without* both fields, then set them with a follow-up `action: "update"`:
 
-A Feature is a container — `/implement AB#{id}` on a Feature implements its **child User Stories in `Custom.Order` waves**, so a Feature with no children can't be worked. After the Feature is created, ask:
+```
+mcp__azure-devops__wit_work_item_write
+  action:  "update"
+  project: "{project}"
+  id:      {childId}
+  updates: [ { op: "add", path: "/fields/Custom.Order", value: "1" } ]
+```
+
+If that also fails, report the child as created *without* an execution order — do not leave it silently unordered. `/implement` treats a child with no `Custom.Order` as a final catch-all wave, so **every** child must end up with a value.
+
+**Phase 3 — link every child to the Feature in ONE call.** `updates` is an array, so this is a single call, not one per child:
 
 ```
-Draft child user stories for this feature now? (yes / no — I'll add them later)
+mcp__azure-devops__wit_work_item_link_write
+  action:  "link"
+  project: "{project}"
+  updates: [
+    { id: {fid}, linkToId: {story1Id}, type: "child" },
+    { id: {fid}, linkToId: {story2Id}, type: "child" }
+  ]
 ```
 
-**Wait for the user.** On `no`, skip to Step 10 and point them at `/plan-backlog` for later.
+`type: "child"` from the Feature is what produces `System.LinkTypes.Hierarchy-Forward` — the link type parameter is a closed enum of friendly names and the literal `System.LinkTypes.Hierarchy-Forward` string is **not** accepted.
 
-On `yes`:
+**Do NOT use `mcp__azure-devops__wit_work_item_write` `action: "add_child"`.** Its `items[]` accepts only `{title, description, format, areaPath, iterationPath}` — there is no slot for AcceptanceCriteria, StoryPoints, or `Custom.Order`, so children created that way cannot satisfy the field requirements above.
 
-1. Turn each bullet from the Feature's **Scope** section into a candidate User Story using the User Story draft shape from Step 3 — plain-language description plus testable acceptance criteria. Keep each one independently shippable; if a bullet is really two stories, split it.
-2. Assign each story a **`Custom.Order`** value. Stories that can be built in parallel share the same number; a story that depends on an earlier one gets a higher number. Start at `1` and increment per wave. This field drives the wave ordering in `/implement` — a story with no value lands in a catch-all wave, so set it on every story.
-3. Propose story points for each using the Step 4 rubric.
-4. Present the whole set for approval at once:
+**Partial-failure policy.** Never leave orphans and never roll back — this command has no delete path and must not grow one. If a child create fails mid-run: report which items already exist by AB#, then ask whether to retry the failed child or stop and leave the rest for manual creation. If Phase 3 fails after the children exist, report the ids and the exact link call to retry.
 
-   | # | Order | Proposed Title | Points | Summary |
-   |---|-------|----------------|--------|---------|
+### Move to Dev Ready (pointed items only)
 
-   ```
-   Approve these child stories? (yes / change N / drop N / cancel)
-   ```
+If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_work_item_write` with `action: "update"` (`id` plus `updates: [ { op: "add", path: "/fields/System.State", value: "Dev Ready" } ]`) **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
 
-   **Wait for the user.** Revise and re-present until approved. Do not create anything before approval.
-5. On approval, create each story with `mcp__azure-devops__wit_work_item_write` (action `create`) in the same project, setting:
-   - `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria` — rendered to HTML per the Step 8 rules
-   - `Custom.Order` — the wave number
-   - `Microsoft.VSTS.Scheduling.StoryPoints` — the agreed points
-   - `System.AssignedTo` — copied from the Feature if the Feature has an assignee; otherwise leave unset
-6. Link each story to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse` from the story to the Feature).
-7. Move each pointed story to `Dev Ready` in a follow-up update, per the Step 8 rule. **The Feature's state is never changed.**
+The same applies to each child story of a Feature: every child was pointed in Step 3F, so each one gets the same `update` once Phase 3 has linked it.
 
-If a story fails to create or link, report which ones succeeded and which didn't — don't roll back the Feature.
+**Features are never moved.** A Feature stays in `New` and advances only as its child stories are verified and closed — the same rule `/implement` follows.
 
-## Step 10: Confirm
+## Step 9: Confirm
 
 **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.
 
@@ -485,13 +662,15 @@ For a **User Story**, fetch `System.Description` and `Microsoft.VSTS.Common.Acce
 
 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.
+1. `ReproSteps` carries every section — summary, technical details, 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.
+For a **Hot Fix**, fetch `System.Description` and `Microsoft.VSTS.TCM.ReproSteps`, and confirm the narrative — Summary, then Production Impact, then Technical Details — is in the former and the reproduction detail in the latter.
 
-If a check fails the write didn't take — fix it with `wit_work_item_write` (action `update`) before reporting success. Don't report a created item you haven't read back.
+On **every** type, the displayed field (`System.Description`, or `ReproSteps` on a Bug) opens with the `<h3>Summary</h3>` block, and that block contains no `<code>`. A `Technical Details` block follows it. For a **Feature**, also confirm its description carries the `<h3>Decomposition</h3>` block, and check every child story created in Phase 2 the same way as a User Story, plus its `Custom.Order`.
+
+If a check fails the write didn't take — fix it with `mcp__azure-devops__wit_work_item_write` `action: "update"` before reporting success. Don't report a created item you haven't read back.
 
 After creation, report:
 
@@ -517,13 +696,15 @@ Next steps:
   /implement AB#{id}   — start working on it
 ```
 
-For a **Feature**, use these next steps instead:
+For a **Feature**, use these next steps instead — `{fid}` is the Feature's id, not a child's:
 
 ```
 Next steps:
-  /explain AB#{id}     — re-read the feature in plain language
-  /plan-backlog        — propose child Tasks for the Dev Ready stories
-  /implement AB#{id}   — implement the child stories in Custom.Order waves
+  /explain AB#{fid}     — re-read the feature in plain language
+  /plan-backlog         — propose child Tasks for the Dev Ready stories
+  /implement AB#{fid}   — implement the child stories in Custom.Order waves
 ```
 
+`/quote` is not offered for a Feature: its size is the sum of its children, which are already pointed.
+
 Do not assign the work item, set an iteration, or add tags unless the user explicitly asks — those are downstream decisions.

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

@@ -1,6 +1,6 @@
 Edit an existing Azure DevOps work item. Usage: `/edit-work-item <work-item-id> [what to change]`
 
-This command revises a work item that already exists — title, description, acceptance criteria, points, priority/severity, order. On a **Feature** it treats the Feature and its child User Stories as **one unit**: a change to the Feature's scope cascades into the children, new stories are drafted for new scope, stories that fell out of scope are retired, and `Custom.Order` is re-sequenced so the implementation waves still make sense.
+This command revises a work item that already exists — title, description, acceptance criteria, points, priority/severity, Investment Category / Impact, order. On a **Feature** it treats the Feature and its child User Stories as **one unit**: a change to the Feature's scope cascades into the children, new stories are drafted for new scope, stories that fell out of scope are retired, and `Custom.Order` is re-sequenced so the implementation waves still make sense.
 
 Parse `$ARGUMENTS`:
 - **Work item ID** — accept `AB#1234`, `#1234`, or `1234`. Required. If missing, ask for it and stop.
@@ -14,6 +14,7 @@ Read the work item with `expand: Relations` so links and children come back. Col
 - `System.Title`, `System.WorkItemType`, `System.State`, `System.AssignedTo`, `System.Tags`
 - `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`
 - `Microsoft.VSTS.Scheduling.StoryPoints`, `Custom.Order`
+- For User Stories, Bugs and Hot Fixes: `Custom.InvestmentCategory` and `Custom.Impact` — the classification `/create-work-item` Step 3 defines (skip both if the process doesn't have them)
 - 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)
@@ -23,7 +24,7 @@ If the work item is not found, report the error and stop.
 
 ### If the item is a Feature
 
-Also fetch every child via `wit_work_item` `get_batch` with fields `System.Id`, `System.Title`, `System.WorkItemType`, `System.State`, `System.AssignedTo`, `Custom.Order`, `Microsoft.VSTS.Scheduling.StoryPoints`, `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`. Children are the `System.LinkTypes.Hierarchy-Forward` relations. You need their full text — you cannot judge whether a story still fits the revised scope from its title alone.
+Also fetch every child via `wit_work_item` `get_batch` with fields `System.Id`, `System.Title`, `System.WorkItemType`, `System.State`, `System.AssignedTo`, `Custom.Order`, `Microsoft.VSTS.Scheduling.StoryPoints`, `Custom.InvestmentCategory`, `Custom.Impact`, `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`. Children are the `System.LinkTypes.Hierarchy-Forward` relations. You need their full text — you cannot judge whether a story still fits the revised scope from its title alone.
 
 ## Step 2: Show the Current Item
 
@@ -33,6 +34,7 @@ Present what exists today, so the user is editing against reality and not memory
 ## AB#{id}: {title}
 
 **Type:** {type}   **State:** {state}   **Points:** {n | not set}   **Assigned:** {name | unassigned}
+**Investment Category:** {value | not set}   **Impact:** {value | not set}   (User Story, Bug, Hot Fix)
 **Linked PRs:** {#id (status), ... | none}
 
 ### Description
@@ -110,6 +112,7 @@ Produce a **field-level diff**, not a rewritten item. For every field you propos
   + 4. {added criterion}
 
 **Story Points:** {n} → {m}   ({one-line rationale})
+**Investment Category / Impact:** {old} → {new}   ({one-line reason})
 **Priority / Severity:** {n} → {m}   (Bugs only)
 
 **Unchanged:** {list the fields you deliberately left alone}
@@ -118,9 +121,11 @@ Produce a **field-level diff**, not a rewritten item. For every field you propos
 Rules for the draft:
 
 - **Preserve, don't regenerate.** Keep existing wording that the change request doesn't touch. Never drop existing `<img>` tags, attachment URLs, or reference links.
+- **Keep both halves true.** Every item has two readers (rules in `/create-work-item` Step 3). The PM reads the plain-English **Summary** at the top. The developer and Claude Code read the **Technical Details** below it, grounded in real paths and names from the code. If the change moves what the item does, revise both in this change set: the Summary in plain English, and the Technical Details against the code. If the item lacks either one, propose it here. Either way it shows in the diff like any other field change.
 - **Points follow the `/quote` rubric** — modified Fibonacci (`1, 2, 3, 5, 8, 13, 21`), calibrated for a senior developer working with Claude assistance. Only propose a change if the scope actually moved. If the revised item now looks bigger than 21 points, recommend splitting it into a Feature instead of writing the number.
 - **Prior art moves the number too, and it can move it *down*.** Added scope normally raises points, but scope that turns out to be a second or third consumer of something already built often costs less than the first one did — sometimes less than the raise it would otherwise earn. If the Step 3 search found precedent, say so in the points rationale rather than pricing the addition as new work.
-- **Never point a Feature** and never change a Feature's `System.State`.
+- **Keep the classification true.** If the change moves *why* the item exists or *how much it matters* — new scope that makes it part of an initiative, a fix that turns out to protect payment data, scope cut down to a one-off — propose new `Investment Category` / `Impact` values from the tables in `/create-work-item` Step 3, with a one-line reason. If either field is unset, propose it. A value a person already chose changes only when the edit gives a reason to; a wording tweak never does.
+- **Never point a Feature** and never change a Feature's `System.State`. A Feature carries no Investment Category or Impact either — they live on its child stories.
 - **Prefix rule holds** — if the title changes, it keeps its `PREFIX - ` prefix from the project's CLAUDE.md table.
 
 ### If the item is a Feature — cascade to the children
@@ -131,7 +136,7 @@ This is the point of the command. After drafting the Feature's own changes, eval
 |---------|---------|--------|
 | **Unchanged** | Still correct under the new scope | Leave it entirely alone |
 | **Update** | Still belongs, but its title / description / AC / points no longer match | Draft a field-level diff for it |
-| **Add** | The revised scope introduces work no existing story covers | Draft a new User Story (`/create-work-item` Step 3 shape) with proposed points |
+| **Add** | The revised scope introduces work no existing story covers | Draft a new User Story (`/create-work-item` Step 3 shape) with proposed points, Investment Category and Impact — normally the same pair as its sibling stories |
 | **Retire** | The revised scope no longer includes this work | Propose `System.State` = `Removed`, or unlinking from the Feature — user picks |
 | **Split** | The story now carries two independently shippable slices | Propose narrowing the existing story and adding a sibling |
 
@@ -211,7 +216,7 @@ Default the comment question to **yes** for any item past `New`, and **no** for
 
 ## Step 7: Apply
 
-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.
+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>` (never in the Summary, which has none), use lists for 2+ parallel items, keep `### Headings` as `<h3>`. The Summary stays the first block of the field the form displays. Preserve existing `<img>` tags exactly.
 
 **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.
 
@@ -231,8 +236,8 @@ Render every Markdown section to HTML first — Azure DevOps description and acc
 Apply writes in this order, so a failure partway through leaves the most useful state behind:
 
 1. **Update the parent item** — one `mcp__azure-devops__wit_work_item_write` (action `update`) call with every changed field. Never include `System.State` for a Feature.
-2. **Update existing children** (verdict `Update`) — one call per story, points and `Custom.Order` in the same call as the text changes. If points were set on a story still at or before `Dev Ready`, set `System.State` = `Dev Ready` in that same call.
-3. **Create added children** — `mcp__azure-devops__wit_work_item_write` (action `create`) with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
+2. **Update existing children** (verdict `Update`) — one call per story, points, `Custom.Order` and any classification change in the same call as the text changes. If points were set on a story still at or before `Dev Ready`, set `System.State` = `Dev Ready` in that same call.
+3. **Create added children** — `mcp__azure-devops__wit_work_item_write` (action `create`) with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, the approved `Custom.InvestmentCategory` and `Custom.Impact`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
 4. **Re-order** any story whose only change is `Custom.Order` — one call each, touching that field alone.
 5. **Retire** stories the user approved — set `System.State` = `Removed`, or remove the parent link, whichever the user chose. **Never delete a work item.**
 6. **Post comments** (if the user said yes) via `mcp__azure-devops__wit_work_item_comment_write` — one short comment per edited item saying what changed and why, and naming the Feature edit that drove it (e.g. `Scope updated via edit of AB#6240: acceptance criteria 2 reworded to cover SSO; re-ordered from wave 3 to wave 2.`).
@@ -248,6 +253,7 @@ Updated AB#{id}: {title}
   Type: {type}
   Fields changed: {list}
   Points: {n → m | unchanged}
+  Classification: {Investment Category · Impact} {(was … → now …) | (unchanged)}
   State: {state} {(unchanged — Features are never moved) | (→ Dev Ready)}
   URL: {work item URL}
 

package/templates/commands/plan-backlog.md

@@ -187,7 +187,18 @@ Create the approved task with `mcp__azure-devops__wit_work_item_write` (action `
   - `System.AreaPath` — copy from the parent
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if its `System.AssignedTo` value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
 
-Then link the new task as a child of the parent with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or fall back to `wit_work_item_link_write` (action `link`) with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
+Then link the new task to its parent story — `updates` is an array, so a whole batch of stories can be linked in one call:
+
+```
+mcp__azure-devops__wit_work_item_link_write
+  action:  "link"
+  project: "{project}"
+  updates: [ { id: {storyId}, linkToId: {taskId}, type: "child" } ]
+```
+
+`type: "child"` from the story is what produces `System.LinkTypes.Hierarchy-Forward`. The parameter is a closed enum of friendly names — the literal `System.LinkTypes.Hierarchy-Forward` string is **not** accepted.
+
+**Do not create the Task with `mcp__azure-devops__wit_work_item_write` `action: "add_child"`.** Its `items[]` accepts only `{title, description, format, areaPath, iterationPath}` — there is no slot for `OriginalEstimate`, `RemainingWork`, or `System.AssignedTo`, so a Task created that way silently loses the hour estimate this command exists to set. Create the Task with `action: "create"`, then link it.
 
 If the create or link call fails, report the failure and ask the user whether to continue with the next story or abort the loop.
 

package/templates/commands/quote-backlog.md

@@ -15,8 +15,9 @@ For each qualifying item:
 2. **Checks whether the work is already implemented** — in the codebase, in commits, or under another ticket.
 3. **Looks at the code when it makes sense** — to validate the described approach and suggest changes.
 4. **Proposes a story point estimate** — using the same senior-calibrated rubric as `/quote`.
-5. **Drafts a comment for the item's creator** when issues are found.
-6. **Suggests a rewrite of the description, and of existing acceptance criteria,** when they need work — offered to the creator in the comment, or applied directly if the user chooses.
+5. **Proposes an Investment Category and Impact** when the item has none — the classification `/create-work-item` Step 3 defines.
+6. **Drafts a comment for the item's creator** when issues are found.
+7. **Suggests a rewrite of the description, and of existing acceptance criteria,** when they need work — offered to the creator in the comment, or applied directly if the user chooses.
 
 **Never author acceptance criteria from nothing.** The rewrite improves AC that are *already there* — it never fills an empty AC field. If the item has no acceptance criteria, the deliverable is a comment telling the creator the AC are missing and the item can't be estimated without them. Rewriting someone's AC is editing their intent; writing AC for a blank field is inventing it.
 
@@ -24,7 +25,7 @@ For each qualifying item:
 
 **Nothing is written to Azure DevOps — no points, no comments — until the user has seen the full batch and approved.** This command never modifies code and never reassigns items. It makes exactly three kinds of change, all in Step 5:
 
-- an item that **gets points** moves to **Dev Ready**;
+- an item that **gets points** moves to **Dev Ready**, and gets an Investment Category and Impact if it had none;
 - a **User Story** that **can't be quoted** because information is missing moves back to **Design Review**, so the next sweep doesn't pick it up again while the creator is still working on it;
 - a **Bug** that can't be quoted gets a **`needs-info` tag** instead — its state stays `New`. `New` is the bottom of the Bug workflow, so there is no earlier state to send it back to; the tag is what drops it out of the next sweep. The Step 2 query excludes tagged items, and removing the tag re-queues the bug.
 
@@ -59,6 +60,7 @@ Numbers refer to the `#` column of the summary table, not to AB# ids — so `1,2
 
 **What approval writes:**
 - **Story Points** on items that got a number — each also moves to **Dev Ready**
+- **Investment Category and Impact** on pointed items that had neither set — a value someone already chose is never overwritten
 - **Design Review** on **User Stories** that couldn't be quoted — anything blocked on missing information goes back to the creator's queue so the next sweep skips it
 - A **`needs-info` tag** on **Bugs** that couldn't be quoted — a Bug has no design state to return to, so the tag is what keeps the next sweep off it. Existing tags are preserved; the state stays `New`
 - **Comments** to the creators of items where something was found
@@ -203,7 +205,7 @@ For each item in the batch, do all of 3a–3e before presenting anything. Collec
 
 ### 3a. Fetch the full work item
 
-Fetch with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
+Fetch with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `Custom.InvestmentCategory` and `Custom.Impact`, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
 
 ### 3b. Completeness review
 
@@ -282,6 +284,14 @@ Two cases are the exception — no state change and no tag, because nothing is m
 - **Needs to be split** (the work is understood, it's just too big) — the item keeps its current state; the deliverable is the split proposal.
 - The user chooses to leave it alone at the Step 4 gate.
 
+### 3e2. Propose the classification (pointed items with it unset)
+
+For every item that gets a number in 3e, check `Custom.InvestmentCategory` and `Custom.Impact`. Where **either is unset**, propose a value from the tables in `/create-work-item` Step 3, with a one-line reason from what 3a–3d established. Impact is the difference the item makes, not its size.
+
+- **Never overwrite a value someone set.** A set value is shown as-is; if it looks clearly wrong, note it in the item's detail block for the user — don't propose writing over it.
+- Items that get **no points** (blocking gaps, duplicates, split candidates) get no classification either — nothing about them is written except the drop-out and the comment.
+- **Only where the process has the fields.** Check `get_type` once per sweep; if the types don't carry `Custom.InvestmentCategory` / `Custom.Impact`, skip this step and leave the column out of Step 4.
+
 ### 3f. Draft the creator comment (only if issues were found)
 
 If 3b–3d surfaced anything — gaps, a duplicate, a suggested approach change — draft a comment addressed to the item's creator (`System.CreatedBy`). Format:
@@ -321,7 +331,7 @@ The rewrite is a *suggestion*: by default it travels inside the creator comment
 
 ### Ultracode mode (optional fan-out)
 
-Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 3a–3g is independent per item, so fan out **one agent per item** with the `Workflow` tool. Each agent does the full 3a–3g pass and returns a structured result (item id, creator, completeness verdict, duplicate findings, code notes, proposed points, draft comment, suggested rewrite) — use a `schema` so each agent returns validated JSON.
+Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 3a–3g is independent per item, so fan out **one agent per item** with the `Workflow` tool. Each agent does the full 3a–3g pass and returns a structured result (item id, creator, completeness verdict, duplicate findings, code notes, proposed points, proposed classification, draft comment, suggested rewrite) — use a `schema` so each agent returns validated JSON.
 
 **Never fan out Step 4 or Step 5** — presentation, approval, and every write stay sequential in the main loop. If ultracode is off, analyze the batch one item at a time; the output is identical either way.
 
@@ -333,16 +343,18 @@ Show the whole batch **before writing anything**. Start with the summary table:
 Quote sweep — {project} backlog, unpointed (Stories: Design Approved · Bugs: New)
 Batch: {n} of {total} qualifying items{ — run /quote-backlog again for the next 10}
 
-| #  | ID       | Type  | Title                              | Completeness  | Points | Outcome          | Comment | Rewrite |
-|----|----------|-------|------------------------------------|---------------|--------|------------------|---------|---------|
-| 1  | AB#4611  | Story | COM - Payment reminder emails      | Complete      |   5    | → Dev Ready      | —       | —       |
-| 2  | AB#4614  | Story | COM - Bulk close inactive accounts | Minor gaps    |   8    | → Dev Ready      | yes     | —       |
-| 3  | AB#4617  | Story | PAY - Refund webhook handling      | Blocking gaps |   —    | → Design Review  | yes     | yes     |
-| 4  | AB#4619  | Bug   | PAY - Duplicate refund email       | Complete      |   3    | → Dev Ready      | —       | —       |
-| 5  | AB#4620  | Bug   | COM - Audit log export 500s        | Blocking gaps |   —    | + needs-info tag | yes     | —       |
-| 6  | AB#4623  | Story | COM - Rebuild the reporting module | Too large     |  split | unchanged        | yes     | —       |
+| #  | ID       | Type  | Title                              | Completeness  | Points | Category · Impact          | Outcome          | Comment | Rewrite |
+|----|----------|-------|------------------------------------|---------------|--------|----------------------------|------------------|---------|---------|
+| 1  | AB#4611  | Story | COM - Payment reminder emails      | Complete      |   5    | Quick Win · Large          | → Dev Ready      | —       | —       |
+| 2  | AB#4614  | Story | COM - Bulk close inactive accounts | Minor gaps    |   8    | Maintenance · Medium (set) | → Dev Ready      | yes     | —       |
+| 3  | AB#4617  | Story | PAY - Refund webhook handling      | Blocking gaps |   —    | —                          | → Design Review  | yes     | yes     |
+| 4  | AB#4619  | Bug   | PAY - Duplicate refund email       | Complete      |   3    | Risk Mitigation · Small    | → Dev Ready      | —       | —       |
+| 5  | AB#4620  | Bug   | COM - Audit log export 500s        | Blocking gaps |   —    | —                          | + needs-info tag | yes     | —       |
+| 6  | AB#4623  | Story | COM - Rebuild the reporting module | Too large     |  split | —                          | unchanged        | yes     | —       |
 ```
 
+**Category · Impact** shows the proposal for pointed items that had none, and `(set)` where the item already carried a value that will be left alone.
+
 The **Type** column matters — it decides the outcome, so show it. The **Outcome** column is what will actually be written: `→ Dev Ready` for pointed items of either type, `→ Design Review` for **User Stories** that can't be quoted until the creator supplies something, `+ needs-info tag` for **Bugs** in the same situation (state stays `New` — a Bug has no design state to return to), and `unchanged` for anything else (a split proposal, or an item already past Dev Ready).
 
 Then a detail block per item — estimate reasoning (2–3 bullets), completeness findings, duplicate evidence with links/IDs, code notes, the **full text of any draft comment**, and the **full text of any suggested rewrite**. The user must be able to read every word that would be posted.
@@ -359,7 +371,7 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cance
 
 - `all` → apply every proposed write (points, state changes, tags, and comments) in Step 5; rewrites stay inside the comments as suggestions
 - `1,2,4` → apply only those items; the rest are recorded as skipped
-- `edit N` → ask what to change on item N (points value, comment text, or rewrite text), revise, re-show that item, ask again
+- `edit N` → ask what to change on item N (points value, Investment Category / Impact, comment text, or rewrite text), revise, re-show that item, ask again
 - `apply rewrite N` → write item N's rewrite directly onto the work item in Step 5 (instead of only suggesting it in the comment). This covers the description, the title if the rewrite included one, and rewritten AC **only where the item already had AC** — an empty AC field is never populated, under this or any other option
 - `skip N` → drop item N, re-ask for the rest. A skipped item gets **nothing** written — no comment, no state change, no tag — so it keeps its current state (`Design Approved` for a Story, `New` for a Bug) and will reappear in the next sweep. Say that out loud when confirming a skip, so the user isn't surprised to see it again
 - `cancel` → stop with **zero changes** to Azure DevOps
@@ -368,7 +380,7 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cance
 
 Only for approved items, in batch order:
 
-1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_work_item_write` (action `update`) call, set `Microsoft.VSTS.Scheduling.StoryPoints` **and** `System.State` = `Dev Ready`. The state change applies only to `User Story`, `Bug`, and `Hot Fix` types, and never moves an item backward — if an item is somehow already past Dev Ready, set the points only and note it. Touch no other field — assignee, iteration, and tags stay as they are.
+1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_work_item_write` (action `update`) call, set `Microsoft.VSTS.Scheduling.StoryPoints` **and** `System.State` = `Dev Ready` — plus the proposed `Custom.InvestmentCategory` / `Custom.Impact`, only for the ones that were unset. The state change applies only to `User Story`, `Bug`, and `Hot Fix` types, and never moves an item backward — if an item is somehow already past Dev Ready, set the points only and note it. Touch no other field — assignee, iteration, and tags stay as they are.
 2. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_work_item_write` (action `update`). Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
 
    - **`User Story` only.** Do not attempt this on a `Bug` or a `Hot Fix` — those types have no `Design Review` state, so the update fails at runtime in the middle of the batch. They take step 3 instead.
@@ -402,6 +414,7 @@ If a write fails, report the failure and ask whether to continue with the remain
 Items analyzed:    {n} (of {total} qualifying — {remaining} left for the next run)
                    {n_stories} stories (Design Approved) · {n_bugs} bugs (New)
   ✓ Points set:    {n_pointed}  (total {sum} pts — each moved to Dev Ready)
+  ✓ Classified:    {n_classified} given an Investment Category and Impact
   ↩ Design Review: {n_design_review} stories not quoted — moved back to the creator, out of the next sweep
   ⚑ needs-info:    {n_tagged} bugs not quoted — tagged, state left at New, out of the next sweep
   ✓ Comments:      {n_comments} posted to creators
@@ -411,8 +424,8 @@ Items analyzed:    {n} (of {total} qualifying — {remaining} left for the next
   ⚑ Stale drop-outs: {n_stale} answered since leaving the sweep — still excluded ({n_stale_bugs} tagged bugs, {n_stale_stories} bounced stories)
 
 Pointed items:
-- AB#4611: 5 pts
-- AB#4614: 8 pts (comment posted)
+- AB#4611: 5 pts · Quick Win · Large
+- AB#4614: 8 pts (comment posted) · classification already set
 - ...
 
 Moved back to Design Review (stories, no points — waiting on the creator):
@@ -437,4 +450,4 @@ Next steps:
   /quote AB#{id}             — re-estimate a single item after the creator responds
 ```
 
-Do not create tasks or assign items — those are downstream decisions. Pointed items are now Dev Ready, so `/plan-backlog` picks them up on its next run. Stories moved to Design Review and bugs tagged `needs-info` are both out of the Step 2 query, so the next `/quote-backlog` run reaches genuinely new items instead of re-reviewing the ones still waiting on their creator — re-quote one with `/quote AB#{id}` once they respond, or let them move the story back to Design Approved / drop the bug's tag themselves. Make no change other than the three described in Step 5 — **Step 2b's audit is read-only**, and it never clears a tag on the creator's behalf.
+Do not create tasks or assign items — those are downstream decisions. Pointed items are now Dev Ready, so `/plan-backlog` picks them up on its next run. Stories moved to Design Review and bugs tagged `needs-info` are both out of the Step 2 query, so the next `/quote-backlog` run reaches genuinely new items instead of re-reviewing the ones still waiting on their creator — re-quote one with `/quote AB#{id}` once they respond, or let them move the story back to Design Approved / drop the bug's tag themselves. Make no change other than the ones described in Step 5 — **Step 2b's audit is read-only**, and it never clears a tag on the creator's behalf.

package/templates/commands/quote.md

@@ -8,7 +8,7 @@ Read the work item from Azure DevOps using the project from the current repo's C
 
 If the work item is not found, report the error and stop.
 
-Capture: title, type, description, acceptance criteria, repro steps (on a Bug), attached child items, any existing `Story Points` / `Effort` field value, and the item's **full current tag list** — both the tags that hint at scope (e.g. `spike`, `research`, `infra`) and the rest, because Step 5b appends to that list and must not clobber it.
+Capture: title, type, description, acceptance criteria, repro steps (on a Bug), attached child items, any existing `Story Points` / `Effort` field value, the current `Custom.InvestmentCategory` and `Custom.Impact` (User Story, Bug, Hot Fix), and the item's **full current tag list** — both the tags that hint at scope (e.g. `spike`, `research`, `infra`) and the rest, because Step 5b appends to that list and must not clobber it.
 
 ## Step 2: Size the Work
 
@@ -63,6 +63,14 @@ If the item has child items, size each child as well and present the parent's to
 
 **If the item can't be estimated at all, don't guess a number.** An item is *not estimable* when the gap is information only its creator can close — no acceptance criteria (or, on a Bug, no repro steps), a description that contradicts itself, scope you can't bound, or work that looks like it may already be done under another ticket. Report it as **needs more information**, list exactly what's missing, and go to Step 5 instead of Step 4. This is different from **needs to be split**: a split candidate is understood work that's simply too big, and it keeps its current state.
 
+### Classify it too, when nobody has
+
+User Stories, Bugs and Hot Fixes carry an **Investment Category** (`Custom.InvestmentCategory`) and an **Impact** (`Custom.Impact`) — restricted picklists that Serena's reports rank work by. When the item you're sizing has **either one unset**, propose a value for it from the tables in `/create-work-item` Step 3, with a one-line reason drawn from the same reading you just did. Impact is the difference the item makes, not its size: a 2-point item can be Strategic.
+
+- **Never overwrite a value a person set.** If both are already set, show them as they are. If one looks clearly wrong in light of what you read, say so in a line, but don't propose writing it — that's an `/edit-work-item` change.
+- **Not for a Feature or a Task** — neither type has the fields.
+- **Only where the process has them.** If `get_type` for the item's type doesn't list `Custom.InvestmentCategory` / `Custom.Impact`, skip this section entirely.
+
 ## Step 3: Display the Estimate
 
 Output a compact estimate — not a quote block. Format:
@@ -77,6 +85,8 @@ Output a compact estimate — not a quote block. Format:
 - {bullet on test/doc burden}
 
 **Comparable to:** {one-line analogy to a similar past story, or "no obvious comparable in recent work"}
+
+**Classification:** {Investment Category} · {Impact} — {proposed: one-line reason | already set}
 ```
 
 If child items were sized, append:
@@ -107,14 +117,15 @@ If the item isn't estimable, report that instead of a number:
 
 This step applies when you produced a **number**. If the item was reported as *needs more information*, skip to Step 5.
 
-After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}? (This will also move it to Dev Ready.)"*
+After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}? (This will also move it to Dev Ready.)"* When you proposed a classification, name it in the same question — *"…and Investment Category = {category}, Impact = {impact}?"* — and accept a changed value or "points only" as the answer.
 
 Only update the work item if the user explicitly says yes. Do not modify anything otherwise.
 
 When the user agrees, in the **same** `wit_work_item_write` (action `update`) call:
 
 1. Set `Microsoft.VSTS.Scheduling.StoryPoints` to the agreed value (the user's number wins if they adjusted it).
-2. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Testing`, `Staging`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
+2. Set `Custom.InvestmentCategory` / `Custom.Impact` to the agreed values — only the ones you proposed because they were unset, and only if the user didn't decline them.
+3. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Testing`, `Staging`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
 
 **Never change the state of a Feature or a Task** — if the sized item is a Feature, persist points only (or per-child points on the children, each of which does get Dev Ready if it qualifies).
 

package/templates/commands/rework.md

@@ -358,7 +358,7 @@ If the user provided hours (suggested or overridden):
 
        ```html
        <h3>Summary</h3>
-       <p>{1–2 sentences describing the problem the rework addresses. Bold key terms, values, and outcomes with <strong>...</strong>.}</p>
+       <p>{1–2 plain-English sentences a PM could follow: what the tester found and what will change, named the way a user sees it. No code identifiers (those go under Fix). Bold the key outcome with <strong>...</strong>.}</p>
        <h3>Fix</h3>
        <ul>
          <li>{What changes. Wrap code identifiers, method names, fields, file paths, and literal values in <code>...</code>.}</li>
@@ -370,7 +370,7 @@ If the user provided hours (suggested or overridden):
        </ul>
        ```
 
-       Render any code identifiers (method names, fields, file paths, hashes, literal values) inside `<code>` spans, and emphasize the key claim/value in each sentence with `<strong>`. Do not submit a wall of plain prose — every rework task must have at least the `Summary` and `Fix` sections in this shape.
+       In Fix and Reference, render any code identifiers (method names, fields, file paths, hashes, literal values) inside `<code>` spans, and emphasize the key claim/value in each sentence with `<strong>`. Do not submit a wall of plain prose — every rework task must have at least the `Summary` and `Fix` sections in this shape.
      - `Microsoft.VSTS.Scheduling.OriginalEstimate` — the agreed hours
      - `Microsoft.VSTS.Scheduling.RemainingWork` — the agreed hours
      - `System.AreaPath` — same as the parent

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -114,6 +114,13 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 
 Every Feature, User Story, Bug, or Hot Fix Claude creates goes through `/create-work-item`, whether or not the user typed the command. "Log a bug that the export 500s", "make a story for bulk assign", "open a ticket for this" all mean: invoke `create-work-item` with the Skill tool, passing the request text as the arguments. Never create one with a direct `wit_work_item_write` call. That skips the prior-art and duplicate checks, the title prefix, the AC field, the proposed points, and the user's approval of the draft. The `work-item-intent.sh` hook adds a reminder to any prompt that reads like a creation request.
 
+**Every work item serves two readers.**
+
+- **The PM reads the Summary.** It is the first section: 2–4 plain-English sentences on what is changing or broken, who notices, and why it matters. It names screens and buttons the way users see them, with no code identifiers, endpoints, field names, or jargon.
+- **The developer and Claude Code read everything below it.** That starts with **Technical Details**, grounded in the actual codebase: real file paths, components, endpoints, data fields, business rules, and constraints, layer by layer. It must be enough for `/implement` to plan from without rediscovering where the change lives. Nothing is guessed: an unconfirmed name is marked *(unverified)*, and a session without the code says so.
+
+`/create-work-item` writes both on every type, including a Feature's child stories. `/edit-work-item` keeps both current and proposes either one when it's missing.
+
 This includes items Claude decides to raise itself, such as a defect found mid-task or out-of-scope work. Propose it, and if the user agrees, run `/create-work-item` with what you found.
 
 Work items a command creates as one of its own steps keep that command's flow: child Tasks from `/implement`, `/rework`, `/plan-backlog`, and `/plan-sprint`, and child stories from `/create-work-item` and `/edit-work-item`. A new Bug or Story requested in the middle of one of those commands still goes through `/create-work-item`.
@@ -136,6 +143,22 @@ These rules apply to **every** command or flow that creates or estimates work it
    **The drop-out mechanism has no expiry, so every sweep must audit it.** Removing the `needs-info` tag is the *only* thing that re-queues a bug, and moving a story back to `Design Approved` is the only thing that re-queues a story. A creator who supplies the missing information but leaves the tag on — or answers in a comment instead of editing the field — makes the item invisible to every future sweep, permanently. That failure looks exactly like a clean backlog. `/quote-backlog` Step 2b therefore audits tagged items for activity after the tag was applied and reports the stale ones; it never clears a tag on the creator's behalf. Two traps when writing such a check: automation bots bump a revision after nearly every human write, so the *latest* revision author is unreliable — scan the whole range after the tag revision; and a `System.CommentCount` increase counts as a creator response.
 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 (verified 2026-09-06): `User Story` has `New → Dev Ready → In Design → Design Review → Design Approved → Active → Code Review → Ready for Testing → Testing → Ready for Staging → Staging → Ready to Deploy → Deployed → Closed`; `Bug` and `Hot Fix` have the same list minus the three design states (`New → Dev Ready → Active → Code Review → …`). `Ready for Staging` and `Staging` were added on 2026-09-06 so every environment has a state — see **Work Item States ↔ Environments** below.
 
+### Work Item Classification — Investment Category and Impact
+
+User Stories, Bugs and Hot Fixes carry two restricted picklists (added 2026-10-05 on the `Agile - CSI` process, so every project on it has them). Serena's Monthly Executive and Backlog Grooming reports rank and summarize work by them:
+
+| Field | Reference name | Values |
+|---|---|---|
+| Investment Category | `Custom.InvestmentCategory` | Strategic Initiative, Quick Win, Risk Mitigation, Maintenance |
+| Impact | `Custom.Impact` | Strategic, Large, Medium, Small, Tiny/One-off |
+
+1. **Every User Story, Bug and Hot Fix Claude creates gets both, proposed and agreed like points.** `/create-work-item` proposes them with a one-line reason; the user confirms or changes them. A Feature gets one pair that each of its child stories inherits — **the Feature itself never carries them**, and neither does a Task.
+2. **Estimating fills the gaps.** `/quote` and `/quote-backlog` propose both for an item that has neither set and write them in the same update as its points.
+3. **A value a person chose is never overwritten silently.** Only `/edit-work-item` changes a set value, and only when the edit gives a reason to — shown in the change set like any other field.
+4. **Impact is the difference an item makes, not its size.** Choose from the definitions in `/create-work-item` Step 3, and spell values exactly — `Tiny/One-off` included. Azure DevOps rejects anything else.
+5. **Priority is not impact.** Most delivered items carry Priority 1 or 2 (2 is the default), so it says nothing about which work mattered. Never derive or backfill Impact from it.
+6. **Only where the process has the fields.** Confirm with `get_type` on an unfamiliar project; if the type doesn't list them, leave them out — writing an undefined field fails the whole create or update.
+
 ### Branching Strategy
 
 #### Target Branch-to-Environment Mapping
@@ -372,9 +395,9 @@ All deployment and release operations are available as slash commands:
 | `/qa` | `/qa AB#1234 [env]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in as a test account → full regression of the screens the story touched → pass/fail comment (never a state change) |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose child tasks with hours |
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
-| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, **bugs in `New`** (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Pointed items move to Dev Ready; stories that can't be quoted move back to **Design Review**, bugs that can't be quoted get a **`needs-info`** tag, so the next sweep skips them. Every run also audits the drop-out queue (tagged bugs **and** stories bounced to Design Review) and reports any whose creator answered but which nobody returned to the sweep — neither mechanism expires, so those are otherwise invisible forever |
-| `/quote` | `/quote AB#1234` | Estimate story points for one work item; on approval, sets the points and moves the item to Dev Ready. If it can't be estimated, offers to send a story back to **Design Review** or tag a bug **`needs-info`** |
-| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, User Story, or Hot Fix — proposes story points (user must agree) and creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves. Runs automatically for any plain-language request to create a work item |
+| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, **bugs in `New`** (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points (+ Investment Category / Impact where unset) + creator comments (10 at a time, approval-gated). Pointed items move to Dev Ready; stories that can't be quoted move back to **Design Review**, bugs that can't be quoted get a **`needs-info`** tag, so the next sweep skips them. Every run also audits the drop-out queue (tagged bugs **and** stories bounced to Design Review) and reports any whose creator answered but which nobody returned to the sweep — neither mechanism expires, so those are otherwise invisible forever |
+| `/quote` | `/quote AB#1234` | Estimate story points for one work item, and propose Investment Category / Impact if it has none; on approval, sets them and moves the item to Dev Ready. If it can't be estimated, offers to send a story back to **Design Review** or tag a bug **`needs-info`** |
+| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, User Story, or Hot Fix — opens each with a plain-English Summary for the PM, then code-grounded Technical Details for the developer, proposes story points and Investment Category / Impact (user must agree) and creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves. Runs automatically for any plain-language request to create a work item |
 | `/edit-work-item` | `/edit-work-item AB#1234 [what to change]` | Revise an existing work item field-by-field. On a Feature, cascades the change into its child stories — updates, adds, retires, and re-sequences `Custom.Order` waves — with a safety gate on anything already past Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks [scope] [--dry-run]` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |