---
name: product-planner
description: Work with Product Planner through its MCP server — build and refine Opportunity Solution Trees (OST) and User Story Maps (USM) — and turn a Product Planner work item into Azure DevOps work items with the Azure DevOps MCP server, linking them back. Use when the user mentions Product Planner, an OST, opportunities, solutions, assumptions, experiments, outcomes, strategy, a story map, personas, or wants to map, break down, hand off or push a Product Planner item to Azure DevOps.
---

# Product Planner + Azure DevOps

Two MCP servers work together:

- **Product Planner MCP** (`@product-planner/mcp`): the discovery side — why we build something (OST) and how users experience it (USM).
- **Azure DevOps MCP** (`@azure-devops/mcp`): the delivery side — the backlog engineering works from.

Product Planner owns the *why*; Azure DevOps owns the *how and when*. Don't copy discovery work (opportunity scores, assumptions, experiments) into Azure DevOps — link to it.

## Ground rules

1. **Start with context, not writes.** Call `list_workspaces`, then `get_ost_context` and/or `get_usm_context` for the workspace before creating anything. Re-use existing items instead of creating near-duplicates (`search_work_items`).
2. **Read the type docs before setting fields.** `list_work_item_types` with `type` explains every type-specific field and the meaning of each rating step. Pass type-specific values via `fields` on `create_work_item` / `update_work_item` (validated) rather than `patch_work_item`.
3. **Respect the hierarchy.** Create children with `parentId`. To move an item, `delete_link` with `linkType: "Hierarchy"`, then `create_link` (`sourceId` = new parent).
4. **Propose, then write.** For anything more than a couple of items, show the user the planned tree first and create it after they agree. Never delete without explicit confirmation.
5. **Report back** with the titles and links of everything created or changed. `get_work_item` and `create_work_item` return an **Open in Product Planner** link for OST and USM items; it opens the item in the app and can be shared.

## Opportunity Solution Tree

```
vision (optional, root)
└─ businessOutcome ── metric
   └─ strategy (optional) ── strategicAssumption
      └─ productOutcome (has a `bet`) ── metric
         └─ opportunity
            └─ solution
               └─ assumption
                  └─ experiment
```

| Type | What makes a good one |
|------|-----------------------|
| `businessOutcome` | A business result (revenue, retention) with at least one `metric` child |
| `strategy` | The choices: target customer, problem, why us, direction, what we say *not now* to |
| `strategicAssumption` | A belief the strategy depends on; rate importance and evidence |
| `productOutcome` | A change in customer behaviour the team can influence; state the `bet` |
| `opportunity` | A customer need, pain or desire in the customer's words — **not** a feature. Set its persona with `set_work_item_persona` and the metrics it should move with `set_opportunity_metrics` |
| `solution` | One way to address the opportunity. Give it ICE scores. Aim for several solutions per opportunity to compare |
| `assumption` | What must be true for the solution to work (desirability, viability, feasibility, usability); rate importance and evidence |
| `experiment` | The cheapest test of the riskiest assumption, with success criteria. Its state is the result: Running, Validated, Invalidated, Inconclusive. Record learnings in its fields |

Typical tasks:

- **Coach a tree:** read `get_ost_context`, then point out outcomes without metrics, opportunities phrased as solutions, opportunities with a single solution, solutions with no assumptions, and important assumptions with weak evidence and no experiment.
- **From interview notes:** extract opportunities (customer language), dedupe against the tree, and place each under the right product outcome.
- **Before building a solution:** check its assumptions and experiments with `get_work_item_tree`; flag untested high-importance assumptions before it is handed to delivery.

## User Story Map

```
persona
└─ activity        (a big step in the user's journey, left → right)
   └─ userTask     (what the user does within the activity)
      └─ userStory (a releasable slice, top = most important)
```

- Set the persona on activities and stories with `personaId` on `create_work_item`, or later with `set_work_item_persona`.
- Write stories as *As a … I want … so that …* with acceptance criteria in the description.
- **Connect USM to OST:** link the stories (or a whole activity) that deliver a solution to it with `create_link` and `linkType: "Related"`. The Story Map can then be filtered to that solution.
- **From a solution to a map slice:** read the solution with `get_work_item`, read `get_usm_context`, add the missing tasks and stories under existing activities where possible, and relate them to the solution.

## From a Product Planner item to Azure DevOps

Use this when the user wants to hand off a solution, an activity or a set of stories to engineering.

### 1. Gather

- `get_work_item` on the item (description, fields, comments via `get_comments`, and any existing **Linked work items** in Azure DevOps — don't create duplicates).
- `get_work_item_tree` for its children; for a solution also find its related user stories in `get_usm_context`.
- In Azure DevOps: confirm the project, the process' work item types (Agile: Epic/Feature/User Story/Task; Scrum: Epic/Feature/Product Backlog Item/Task; Basic: Epic/Issue/Task), and the area/iteration path to use. Ask the user when unsure.

### 2. Propose a mapping

Pick the mapping that fits the item's size, and show it to the user before writing:

| Product Planner | Azure DevOps (Agile) |
|-----------------|----------------------|
| productOutcome / large solution | Epic |
| solution | Feature |
| activity | Feature (when the map is the source) |
| userTask | Optional grouping; usually folded into its stories |
| userStory | User Story / Product Backlog Item |
| Implementation steps | Task |
| experiment that needs build work | Spike / User Story tagged `experiment` |

Not every item maps 1:1. A small solution can become a single User Story; a large one may need a Feature with several stories. Opportunities, assumptions and strategy items normally stay in Product Planner — summarise them in the Azure DevOps description instead.

Each Azure DevOps item should carry:

- **Title**: the Product Planner title (stories in user-story form).
- **Description**: the problem it solves (the opportunity), the persona, and a "Discovery context" line with the item's **Open in Product Planner** link (from `get_work_item`), so engineers can open the discovery work behind it.
- **Acceptance criteria**: from the story, or derived from the solution's validated assumptions.
- **Tags**: e.g. `product-planner`.

### 3. Create in Azure DevOps

With the Azure DevOps MCP: create the top item first, then the children under it (e.g. "create work item" for the Feature, then "add child work items" for the stories). Tool names vary between versions of the server — use its work item create, add-children and link tools.

### 4. Link both ways

**Azure DevOps → Product Planner:** besides the link in the description, add the item's **Open in Product Planner** link as a Hyperlink on each Azure DevOps work item when the Azure DevOps MCP offers a tool for it, so it shows under the item's links.

**Product Planner → Azure DevOps:** for every Azure DevOps item that represents a Product Planner item, call **`add_external_link`** on the Product Planner item with the Azure DevOps work item URL (a REST URL is fine; it is converted to the web page). Several links per item are allowed. The link appears as an Azure DevOps icon on the card in Product Planner.

These links are references only — nothing syncs either way. If the workspace has the Azure DevOps integration enabled, items it syncs get their links automatically; don't add those again.

Optionally `add_comment` on the Product Planner item summarising what was created.

### 5. Report

List the Azure DevOps items (ID, type, title, URL) under the Product Planner item each came from, with its Product Planner link.

## Gotchas

- Type names are camelCase (`productOutcome`, `userStory`); IDs are GUIDs. Pass `resourceGroupId` (the workspace ID) when creating items.
- Ratings and numbers are stored as strings (`"4"`).
- `delete_link` without `linkType` keeps parent/child links.
- `remove_external_link` only removes hand-added links, not ones kept by the Azure DevOps sync.
- `delete_work_item` is permanent.