From bf44be3de7b39362717f47104ed7febe3da5b0f2 Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Wed, 9 Sep 2026 14:25:32 +0200
Subject: [PATCH 1/6] feat(skills): Add migrate-breadcrumb-list skill

Encodes the recipe for moving a page off the legacy `sentry/components/breadcrumbs`
component onto `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across
the TopBar `breadcrumbs` and `title` slots. Five merged migrations established the
pattern, but it only existed in those diffs, so each page re-derived it and re-hit the
same traps.

Routes depth into three references: which shape a call site is and what blocks it,
building a title whose name is richer than a string, and the spec mounting a migrated
page needs. Guards four regressions that produce neither a type error nor a failing
test: a legacy crumb spread into a typed item silently drops page filters, a badge in
`leadingGraphic` without `disableLink` puts a focusable link inside an aria-hidden
subtree, a surviving `Layout.Title` or raw `<h1>` double-renders the page name, and a
wrapper migrated in place nests the breadcrumbs slot inside the page heading.

Validated by running the skill cold against `releaseHeader.tsx` in an isolated
worktree, which surfaced the `disableLink` accessibility trap and a checklist grep that
flagged its own recommended fix. Records the four call sites that intentionally keep the
legacy component, since three need a `<nav>` landmark BreadcrumbList has no mode for.
---
 .../skills/migrate-breadcrumb-list/SKILL.md   | 194 ++++++++++++++++++
 .../skills/migrate-breadcrumb-list/SPEC.md    |  41 ++++
 .../references/call-site-inventory.md         | 111 ++++++++++
 .../references/tests.md                       | 133 ++++++++++++
 .../references/title-item.md                  | 128 ++++++++++++
 5 files changed, 607 insertions(+)
 create mode 100644 .agents/skills/migrate-breadcrumb-list/SKILL.md
 create mode 100644 .agents/skills/migrate-breadcrumb-list/SPEC.md
 create mode 100644 .agents/skills/migrate-breadcrumb-list/references/call-site-inventory.md
 create mode 100644 .agents/skills/migrate-breadcrumb-list/references/tests.md
 create mode 100644 .agents/skills/migrate-breadcrumb-list/references/title-item.md

diff --git a/.agents/skills/migrate-breadcrumb-list/SKILL.md b/.agents/skills/migrate-breadcrumb-list/SKILL.md
new file mode 100644
index 000000000000..bc566ac096a8
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: migrate-breadcrumb-list
+description: Migrates page-navigation breadcrumbs from the legacy `sentry/components/breadcrumbs` component to `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across the TopBar `breadcrumbs` and `title` slots. Use when a page still renders `<Breadcrumbs crumbs={...}/>`, when parent crumbs and the page title need separating into two TopBar slots, when `Layout.Title` double-renders the page name, or when working through the BreadcrumbList migration backlog. Trigger on "migrate breadcrumbs", "migrate to BreadcrumbList", "replace sentry/components/breadcrumbs", "split breadcrumbs into TopBar slots", "BreadcrumbList.Title", "the page title renders twice". Not for event breadcrumbs (`sentry/types/breadcrumbs`, the issue-detail timeline), and not for the route-driven SettingsBreadcrumb system.
+---
+
+# Migrate page breadcrumbs to BreadcrumbList
+
+Migrate `$0` (a file, a view directory, or the next unmigrated call site when omitted) off `sentry/components/breadcrumbs`.
+
+## The transformation
+
+Legacy passes one flat array in which the **last** crumb is the current page (the component strips its `to` automatically). The new API splits that across two TopBar slots.
+
+```tsx
+// Old — one array, leaf included
+<Breadcrumbs crumbs={[{label: t('Monitors'), to: basePath}, {label: monitor.name}]} />
+
+// New — parents in one slot, the current page in the other
+<Fragment>
+  <TopBar.Slot name="breadcrumbs">
+    <BreadcrumbList items={[{type: 'link', label: t('Monitors'), to: basePath}]} />
+  </TopBar.Slot>
+  <TopBar.Slot name="title">
+    <BreadcrumbList.Title item={{type: 'page-title', label: monitor.name}} />
+  </TopBar.Slot>
+</Fragment>
+```
+
+`BreadcrumbList.Title` renders **no heading**. The `title` outlet already wraps its children in `<Heading as="h1">` — verify with `grep -n 'Heading as="h1"' static/app/views/navigation/topBar.tsx`. Never wrap `BreadcrumbList.Title` in a `Heading`, and never nest the `breadcrumbs` slot inside the `title` slot. Both mistakes are invisible: the outlet and the title item both use `variant="inherit"`, so a nested heading looks identical and only fails an a11y audit.
+
+## ⚠️ `preservePageFilters` survives a spread
+
+The prop does not exist on `BreadcrumbItemLinkProps`. As a **direct literal** it is caught:
+
+```tsx
+// error TS2353: 'preservePageFilters' does not exist in type 'LinkBreadcrumbItem'
+items={[{type: 'link', label: 'Issues', to: '/issues/', preservePageFilters: true}]}
+```
+
+Through a **spread it compiles clean** — and spreading legacy crumbs is the migration idiom:
+
+```tsx
+// Compiles. Ships a page that silently drops project/environment/date filters on click.
+.map(crumb => ({type: 'link' as const, ...crumb}))
+```
+
+Excess-property checking only applies to fresh object literals, so a `Crumb` carrying `preservePageFilters` passes straight through to `<Link>`, which ignores it. No type error, no failing test. **Destructure explicitly instead of spreading**, and rebuild the query yourself:
+
+```tsx
+import {extractSelectionParameters} from 'sentry/components/pageFilters/parse';
+
+// Build the query once, above the items array. Override any param the destination
+// needs different — and drop `start`/`end` whenever you override `statsPeriod`, or
+// an absolute range and a relative period both travel and the destination picks.
+const query = {
+  ...extractSelectionParameters(location.query),
+  statsPeriod: '24h',
+  start: undefined,
+  end: undefined,
+};
+
+// A legacy `to` is often a bare pathname string. Restructure it into an object —
+// there is nowhere to hang a query otherwise.
+to: {
+  pathname: (makeReleasesPathname({organization, path: '/'}), query);
+}
+```
+
+A bare pass-through is the default and is exactly what `preservePageFilters` did — override a param only when the destination genuinely needs something else, as the `statsPeriod` example above does. When the crumb already has a `to` object, merge rather than replace: `{...to, query: {...query, ...to.query}}`.
+
+Six call sites still pass it: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
+
+The component's own docs still demo it (`grep -n preservePageFilters static/app/components/core/breadcrumbList/breadcrumbList.mdx`). If that grep returns nothing the docs have been fixed; trust the type, not the doc, either way.
+
+## Which API takes what
+
+|                                      | Accepts                                                                                                                     | Shape             |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `<BreadcrumbList items={...}/>`      | `'link'` (`label: string`, `to`, `leadingGraphic?`), `'select-projects'`                                                    | array             |
+| `<BreadcrumbList.Title item={...}/>` | `'page-title'` (`label: string`, `labelTooltip?`, `leadingGraphic?`, `pagination?`, `trailingActions?`), `'editable-title'` | **single object** |
+
+Title actions are a third union — one object, or an array whose absent entries are `null`:
+
+| `trailingActions`  | Required fields                                                 |
+| ------------------ | --------------------------------------------------------------- |
+| `{type: 'copy'}`   | `text`, `label`                                                 |
+| `{type: 'menu'}`   | `items`, `triggerLabel`                                         |
+| `{type: 'button'}` | `element`, typed `ReactElement<ButtonProps \| LinkButtonProps>` |
+
+Import is always `import {BreadcrumbList} from '@sentry/scraps/breadcrumbList'` — an alias onto `static/app/components/core/`. The barrel exports only `BreadcrumbList` and the type `BreadcrumbTitleItem`. `type: 'link'` requires `label: string` and a non-null `to`; `leadingGraphic` is optional.
+
+## Pick the call-site shape
+
+Classify before editing — the shapes need different amounts of work, and three of them touch more than one file.
+
+| Shape  | Pattern                                                                                                                                              | Extra work                                                                                                                                                                                                                                                                                                                                  |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **A1** | `<Breadcrumbs>` inside `TopBar.Slot name="title"`                                                                                                    | Pure split _of the slots_. A JSX leaf label may still need full decomposition — see `references/title-item.md`. Note the element is sometimes assigned to a variable first (`automations/detail.tsx`) or aliased through `styled(Breadcrumbs)` (`preprod/install/buildInstallHeader.tsx`), so `<Breadcrumbs` may not appear inside the slot |
+| **A2** | A **wrapper component** rendered inside the caller's `title` slot                                                                                    | **Two-site edit.** The wrapper returns the two-slot `Fragment`; the caller's wrapping `title` slot must be deleted, or `breadcrumbs` nests inside `title` and parent links render into the `<h1>`                                                                                                                                           |
+| **B**  | `<Breadcrumbs>` in `Layout.HeaderContent` beside `Layout.Title`                                                                                      | Fixes a live double-render. `Layout.Title` wins the title; the displaced leaf is usually a category descriptor (e.g. "Cron Monitor") that wants a real `to` not yet in the file. **Exception below**                                                                                                                                        |
+| **C**  | Exported wrapper consumed by other pages — **only** when a consumer wraps it in a `title` slot; an exported header that owns its own slots is B or E | Every consumer changes in the same PR. Per consumer: hoist any surrounding ternary above the slot, delete the wrapping slot, and place or drop every sibling node in that slot                                                                                                                                                              |
+| **E**  | `<Breadcrumbs>` beside a raw `<Heading as="h1">`                                                                                                     | Delete the local heading, or the page ships two `<h1>`s                                                                                                                                                                                                                                                                                     |
+
+`views/performance/breadcrumb.tsx` is type-only (`import type {Crumb}`, no JSX). Its work is deleting a legacy adapter, and it is blocked — see `references/call-site-inventory.md`.
+
+**Shape B has one exception with no leaf crumb at all**, where applying "`Layout.Title` wins" mechanically renders the same text twice — see `references/call-site-inventory.md`.
+
+`Layout.Title` is already a shim for `TopBar.Slot name="title"` (`grep -n 'export function Title' static/app/components/layouts/thirds.tsx`), which is why Shape B pages double-render today.
+
+## Build `items`
+
+Parents only — the leaf became the title.
+
+```tsx
+// Drop crumbs with no destination: `to` is required and non-nullable.
+const items = parents.flatMap(c =>
+  c.to ? [{type: 'link' as const, label: c.label, to: c.to}] : []
+);
+```
+
+An empty `items` renders nothing, and that is correct — the title slot still renders. **Do not invent a parent link to avoid it.** If the legacy code gated the trail on a length check, port the condition.
+
+That rule and Shape B's "give the displaced leaf a `to`" are not in conflict — they apply to different crumbs. A leaf that is the **page name** is now the title and simply disappears from `items`. A leaf that is a **category descriptor** ("Cron Monitor", "Uptime Monitor") is a real parent that was merely unlinked, and it should keep its place with a destination: look for a `make*Pathname` for that category beside the one you already import. Prefer the two-link trail when such a destination exists; drop the crumb only when there is genuinely nowhere to point.
+
+## Per-page workflow
+
+1. Read the file. Find the crumb array; note whether its last element has a `to`.
+2. Classify the shape. For **A2/C**, `grep -rn '<WrapperName'` now and list every sibling node in each consumer's title slot — consumers are part of this change, not a follow-up. Read `references/call-site-inventory.md` **only** if the file is a wrapper or appears on its hard-rows list; for a plain A1/B/E file the shape table above is enough.
+3. **Decide the title before writing anything.** In priority order: (1) `Layout.Title`'s content, (2) a raw `<Heading as="h1">` sibling, (3) the last crumb. If the header renders no heading and the last crumb has no `to`, the last crumb is the title. If the choice is gated on a boolean, hoist that boolean above both slots and give each branch its own `BreadcrumbList.Title` — never migrate one branch. Use `editable-title` if the name is user-editable, else `page-title`.
+4. Build the title item. → `references/title-item.md`
+5. Build `items` from what remains. Drop the leaf. Drop or re-point crumbs with no `to`. Replace `preservePageFilters`. Port any length guard.
+6. Render both slots, `breadcrumbs` then `title`. Wrap them in a `Fragment` when the component returns them directly. Then check what the old wrapper has left: **if a `Layout.Header` or `Layout.HeaderContent` is now left holding only `TopBar.Slot` children, delete it.** Slots render nothing in place, and `Layout.Header` is a real `<Grid as="header">` with padding and a bottom border — leaving it ships an empty bordered strip above the page body. Keep it only if it still has non-slot children, such as `Layout.HeaderTabs`.
+7. Delete only what the move orphaned — see the checklist guard below.
+8. Fix the specs. → `references/tests.md`
+9. Verify: `pnpm run typecheck` (whole project, takes no paths), `.venv/bin/prek run -q --files <files>`, `pnpm test-ci <spec>`, and re-run the count — it must have decreased and still be at or above 4.
+
+Step 3 precedes step 5 because it determines which crumbs are left. Building `items` first ships the leaf twice and forces a redo of both slots.
+
+## References
+
+| Open when you need to                                                                                           | Read                                |
+| --------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| Know what shape a file is, who consumes a wrapper, or what blocks a file                                        | `references/call-site-inventory.md` |
+| Build a title whose name is more than a plain string — a badge, tooltip, editable field, pagination, or actions | `references/title-item.md`          |
+| Write or fix a spec for a migrated page                                                                         | `references/tests.md`               |
+
+## Reference implementations
+
+Already migrated, simplest first. Each answers one question.
+
+| File                                                                   | Answers                                                                                  |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `views/detectors/components/details/common/header.tsx`                 | The minimal two-slot split                                                               |
+| `views/explore/conversations/components/conversationsBreadcrumbs.tsx`  | Replacing `preservePageFilters`; a standalone `copy` action                              |
+| `views/performance/transactionSummary/transactionBreadcrumbs.tsx`      | Mapping a shared crumb builder into typed items; `leadingGraphic`; a menu with a submenu |
+| `views/performance/newTraceDetails/traceHeader/traceBreadcrumbs.tsx`   | `pagination`; dropping unlinked crumbs with `.flatMap`                                   |
+| `views/dashboards/dashboardBreadcrumbTitle.tsx`                        | `editable-title`; one early return per page state                                        |
+| `views/explore/replays/detail/header/replayDetailsPageBreadcrumbs.tsx` | The richest title — pagination, `leadingGraphic`, and a nulled action array together     |
+| `views/issueDetails/header/issueIdBreadcrumb.tsx`                      | Building a title item outside JSX with `as const satisfies`                              |
+
+## Intentionally not migrated
+
+Four of the 26 importers keep the legacy component: the legacy component's own spec, plus three call sites that render outside the page `<h1>` and need a `<nav>` landmark `BreadcrumbList` has no mode for. **The count floors at 4 — driving it to 0 destroys a landmark.** The route-driven `SettingsBreadcrumb` system is out of scope too; it never imports the legacy component. Both lists are in `references/call-site-inventory.md`.
+
+## Rollout
+
+The count is the progress state — no scratch file to keep in sync.
+
+```bash
+grep -rl "from 'sentry/components/breadcrumbs'" static/app | wc -l
+```
+
+Migrate one view area per PR. Split at roughly 50 changed files along ownership boundaries in `@.github/CODEOWNERS`. Title as `ref(<area>): Migrate breadcrumbs to BreadcrumbList`, or `feat(<area>): ...` if page actions moved into the title menu. There is **no feature flag** — `ui-migration-breadcrumbs` and `useHasNewBreadcrumbs()` were deleted, so every page flips for all users on merge. Some older reference PRs still show a flag fork; that pattern is dead code now.
+
+## Migration checklist
+
+Each item is a grep or a compile, because every judgment-shaped check here was one an earlier draft got wrong.
+
+- [ ] No `preservePageFilters:` in the diff, **and** no spread of legacy crumbs into typed items — `grep` for `preservePageFilters:` (with the colon: a bare grep also matches the comment explaining the replacement, so it flags a correct migration) and for `...crumb` inside a `.map` that produces `type: 'link'`. A spread compiles and silently drops page filters.
+- [ ] No wrapper is left holding only `TopBar.Slot` children — slots render nothing in place, so a surviving padded/bordered `Layout.Header` becomes an empty strip above the page body.
+- [ ] The file has exactly one `TopBar.Slot name="title"`, zero `as="h1"`, zero `Layout.Title` — a survivor of any of these double-renders the page name or ships two `<h1>`s.
+- [ ] No `TopBar.Slot name="breadcrumbs"` inside a `name="title"` subtree — nesting renders parent links into the page heading, and looks correct because both use `variant="inherit"`.
+- [ ] Every `type: 'link'` has a real `to`. An empty `items` is fine and renders nothing; an invented parent link is not.
+- [ ] No `useHasNewBreadcrumbs` or `ui-migration-breadcrumbs` — both are dead repo-wide, so a flag fork can never render.
+- [ ] `label` is a plain string. Stringifying a JSX label deletes the badge, tooltip, or copy affordance instead of moving it.
+- [ ] Every `IdBadge`/`ProjectBadge` in `leadingGraphic` passes `disableLink` — the slot is `aria-hidden`, and `IdBadge`/`ProjectBadge` render a focusable `<a href>` without it, putting a tabbable link inside a hidden subtree. Typechecks, passes tests, fails an axe audit.
+- [ ] `leadingGraphic` avatars pass `avatarSize={16}` with a `<Placeholder width="16px" height="16px"/>` fallback — the slot is a fixed 16×16, so 28px clips and a missing graphic shifts the title as data arrives.
+- [ ] A title item built outside JSX ends `as const satisfies BreadcrumbTitleItem` — otherwise `type` widens to `string` and the union stops narrowing.
+- [ ] Array `trailingActions` use `null` for absent entries; a lone action is a bare object, not a one-element array.
+- [ ] Every touched spec mounts `<TopBar />` inside `<TopBar.Slot.Provider>`, or declares a `breadcrumbs` outlet — a spec stubbing only `title`/`actions`/`feedback` renders no parent crumbs and fails as if the component were broken.
+- [ ] The leaf is asserted **absent** from the trail, not just present as the heading.
+- [ ] The count decreased and is still at or above 4.
+
+Overflow collapse is deliberately absent from this list — jsdom never evaluates container queries. See `references/tests.md`.
diff --git a/.agents/skills/migrate-breadcrumb-list/SPEC.md b/.agents/skills/migrate-breadcrumb-list/SPEC.md
new file mode 100644
index 000000000000..6a4a53a45048
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/SPEC.md
@@ -0,0 +1,41 @@
+# Migrate Breadcrumb List Specification
+
+## Intent
+
+Give an agent a reliable path for moving a page off the legacy `sentry/components/breadcrumbs` component to `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across the TopBar `breadcrumbs` and `title` slots. The dominant failure mode this skill guards against is silent regression: `preservePageFilters` carried through a spread compiles and drops page filters, a surviving `Layout.Title` or raw `<h1>` double-renders the page name, and a wrapper migrated in place nests the `breadcrumbs` slot inside the page heading. None of the three produce a type error or a failing test.
+
+## Scope
+
+In scope: the 22 files importing `sentry/components/breadcrumbs` that render a page-navigation trail, including the wrapper components consumed by several pages and the type-only adapter that feeds them.
+
+Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/events/breadcrumbs/`, the issue-detail timeline — an unrelated feature that shares the word); the route-driven `SettingsBreadcrumb` system; and the three landmark call sites that render outside the page `<h1>` and need a `<nav>` that `BreadcrumbList` has no mode for. Building new capabilities on the component itself is also out of scope.
+
+## Non-negotiable Constraints
+
+- Never spread a legacy `Crumb` into a typed item. Destructure the fields you want; excess-property checking does not apply through a spread.
+- After migrating a file it must contain exactly one `TopBar.Slot name="title"`, zero `as="h1"`, and zero `Layout.Title`.
+- Never nest the `breadcrumbs` slot inside the `title` slot, and never wrap `BreadcrumbList.Title` in a `Heading`.
+- The legacy-importer count floors at 4. Driving it to 0 destroys a `<nav>` landmark.
+- Do not add a feature-flag fork. `ui-migration-breadcrumbs` and `useHasNewBreadcrumbs()` no longer exist.
+
+## Sources
+
+- `components/core/breadcrumbList/` — authoritative for the item unions and every prop. The types win over the story.
+- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination). **Stale on `preservePageFilters`**, which it demos but the type does not accept.
+- `views/navigation/topBar.tsx` — slot names, and the `<Heading as="h1">` that makes the title outlet the page heading.
+- Reference migrations: getsentry/sentry#120729 (conversations), #120794 (trace view), #123128 (transaction summary), #121282 (dashboards actions), #123569 (replay actions). #122697 removed the migration flag; the earlier PRs' flag forks are dead patterns.
+- Ten already-migrated call sites in `static/app/views/`, enumerated in `SKILL.md`.
+
+## Known Limitations
+
+- Overflow collapse is a container query and cannot be tested in jsdom; the skill routes it to a manual resize check.
+- Choosing the title on a Shape B or Shape C page is a judgement the skill can frame but not decide — it supplies a priority order and answer keys, not a rule.
+- `references/call-site-inventory.md` names specific files and is invalidated by this migration's own PRs. It leads with a regeneration command for that reason.
+- `select-projects` has no production consumer, so its guidance is untested by use.
+
+## Maintenance
+
+- Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
+- Delete the `preservePageFilters` section once `grep -n preservePageFilters static/app/components/core/breadcrumbList/breadcrumbList.mdx` returns nothing **and** no legacy importer still passes the prop.
+- Prune `references/call-site-inventory.md` as rows land. When it empties and the count reaches 4, delete this skill.
+- Update `SPEC.md` when intent, scope, the non-negotiable constraints, or the sources change.
diff --git a/.agents/skills/migrate-breadcrumb-list/references/call-site-inventory.md b/.agents/skills/migrate-breadcrumb-list/references/call-site-inventory.md
new file mode 100644
index 000000000000..58556e2ef469
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/references/call-site-inventory.md
@@ -0,0 +1,111 @@
+# Call-site inventory
+
+Regenerate the classification rather than trusting a list — this migration's own PRs invalidate any table of paths. The hard rows below are the part that cannot be regenerated.
+
+## Contents
+
+- [Classify](#classify)
+- [Hard rows](#hard-rows)
+- [Wrapper consumer map](#wrapper-consumer-map)
+
+## Classify
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+EXCLUDE='components/breadcrumbs.spec.tsx|events/eventDrawer.tsx|groupDistributionCrumbs.tsx|widgetBuilderSlideout.tsx'
+for f in $(grep -rl "from 'sentry/components/breadcrumbs'" static/app | grep -Ev "$EXCLUDE" | sort); do
+  printf '%-70s jsx=%s h1=%s LT=%s titleSlot=%s styled=%s\n' "${f#static/app/}" \
+    "$(grep -c '<Breadcrumbs' "$f")" "$(grep -c 'as="h1"' "$f")" \
+    "$(grep -c 'Layout.Title' "$f")" "$(grep -c 'TopBar.Slot name="title"' "$f")" \
+    "$(grep -c 'styled(Breadcrumbs)' "$f")"
+done
+```
+
+Read the fingerprint as:
+
+| Fingerprint                             | Shape                                                   |
+| --------------------------------------- | ------------------------------------------------------- |
+| `titleSlot>0`, `LT=0`, `h1=0`           | **A1** or **A2** — check what the slot's first child is |
+| `LT>0`                                  | **B**                                                   |
+| `h1>0`                                  | **E**                                                   |
+| `titleSlot=0`, `jsx>0`, exported symbol | **C** — count consumers below                           |
+| `jsx=0`, `styled=0`                     | the type-only adapter                                   |
+| `jsx=0`, `styled=1`                     | **A1** via a `styled(Breadcrumbs)` alias                |
+
+To separate A1 from A2, look at the element inside the slot. `<Breadcrumbs` or a JSX-valued variable is A1; a component name is A2 and the caller's slot must be deleted.
+
+```bash
+f=static/app/views/automations/new.tsx
+ln=$(grep -n 'TopBar.Slot name="title"' "$f" | head -1 | cut -d: -f1)
+sed -n "$((ln+1))p" "$f"
+```
+
+A file absent from the fingerprint output is already migrated. Do not re-add it.
+
+## Hard rows
+
+Four files cost far more than their fingerprint suggests.
+
+### `views/performance/breadcrumb.tsx` — blocked, do last
+
+Type-only, and it looks like a one-file delete. It is not. `getTabCrumbs()` returns `Crumb[]` that flows:
+
+```
+performance/breadcrumb.tsx  getTabCrumbs()
+  → performance/transactionSummary/header.tsx
+  → {...headerProps}
+  → insights/pages/{frontend,backend,mobile}/*PageHeader.tsx   (3 shims)
+  → insights/pages/domainViewHeader.tsx   additionalBreadCrumbs?: Crumb[]  ← public prop
+```
+
+Six files, three shapes. Deleting the adapter first breaks `header.tsx` and surfaces the chain at typecheck with no guidance on whether to expand scope or revert. Do these four as one PR, after everything else. Confirm the chain still holds before starting:
+
+```bash
+grep -rn 'getTabCrumbs\|additionalBreadCrumbs' static/app --include='*.tsx'
+```
+
+`getTransactionSummaryParentCrumbs` in the same file is already the new-style builder — the migration deletes `getTabCrumbs` around it, it does not rewrite both.
+
+### `views/explore/components/breadcrumb.tsx` — hardest file in the set
+
+`ExploreBreadcrumb`, four consumers: `explore/{metrics,spans,logs}/content.tsx` and `explore/replays/list.tsx`. Each one gates the _title source_ on the same boolean that gates the trail, so the title is branch-dependent and step 3 has no single answer. Each also carries sibling nodes in the title slot (a `FeatureBadge`, a tooltip) that have no home in the new API.
+
+Hoist the ternary above both slots and give each branch its own `BreadcrumbList.Title`. Migrating only the true branch nests `breadcrumbs` inside `title`.
+
+The wrapper's own crumb builder uses four independent `if`s, so an unrecognized dataset yields a single unlinked leaf. After dropping the leaf, `items` is empty and the trail renders nothing — which is correct here. Do not invent a parent.
+
+### `views/insights/pages/domainViewHeader.tsx` — the Shape B exception
+
+No leaf crumb: `crumbs[0]` is a linked parent, and `Layout.Title` is `{headerTitle || domainTitle}`. Applying "`Layout.Title` wins" mechanically produces the same string as both a parent link and the heading, where today the page renders one heading. Keep the `crumbs.length > 1` guard as a condition on the `breadcrumbs` slot. `additionalBreadCrumbs` is a public prop — retyping it is what unblocks the row above.
+
+### `views/preprod/install/buildInstallHeader.tsx` — three branches, one component
+
+Three separate `TopBar.Slot name="title"` blocks with three different crumb arrays, plus a `styled(Breadcrumbs)` alias to delete. Each branch needs its own title decision, and the pending branch's label is a row of `Placeholder`s with no representable form — see `title-item.md`. Mirror `views/dashboards/dashboardBreadcrumbTitle.tsx`'s one-early-return-per-state structure.
+
+## Wrapper consumer map
+
+Shape C wrappers and their consumers. Re-derive with `grep -rl '<SymbolName' static/app --include='*.tsx' | grep -v spec.tsx`.
+
+| Wrapper                                                   | Consumers                                                                          |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `components/profiling/profilingBreadcrumbs.tsx`           | `profileHeader.tsx`, `continuousProfileHeader.tsx`                                 |
+| `views/alerts/builder/builderBreadCrumbs.tsx`             | `views/alerts/edit.tsx`                                                            |
+| `views/detectors/components/forms/common/breadcrumbs.tsx` | `newDetectorLayout.tsx`, `editDetectorLayout.tsx`                                  |
+| `views/discover/breadcrumb.tsx`                           | `views/discover/results/resultsHeader.tsx`                                         |
+| `views/explore/components/breadcrumb.tsx`                 | `metrics/content.tsx`, `spans/content.tsx`, `logs/content.tsx`, `replays/list.tsx` |
+
+Two answer keys worth copying rather than re-deriving:
+
+- **An unlinked leaf that must become a link.** `views/detectors/components/uptime/details.tsx` has `{label: t('Uptime Monitor')}` with no `to`. The destination is not in that file, but `views/detectors/components/details/common/header.tsx` already links `getDetectorTypeLabel(detector.type)` → `makeMonitorTypePathname(organization.slug, detector.type)` for exactly this crumb.
+- **A spec that renders a wrapper with no TopBar at all.** `components/profiling/profilingBreadcrumbs.spec.tsx` cannot work as written once the wrapper owns two slots. See `tests.md`.
+
+## Never migrated
+
+| File                                                                  | Why it stays                                                  |
+| --------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `components/breadcrumbs.spec.tsx`                                     | The legacy component's own spec; goes when the component does |
+| `components/events/eventDrawer.tsx` (`NavigationCrumbs`)              | Renders outside the page `<h1>` and needs a `<nav>` landmark  |
+| `views/issueDetails/groupDistributions/groupDistributionCrumbs.tsx`   | Consumes `NavigationCrumbs`                                   |
+| `views/dashboards/widgetBuilder/components/widgetBuilderSlideout.tsx` | `<Breadcrumbs as="nav">` inside a slide-over panel            |
+
+`BreadcrumbList` renders a bare `<ol>` with no landmark mode, so those three are blocked on a component capability. `views/settings/components/settingsBreadcrumb/` is a separate route-driven system that derives crumbs from `useRoutes()` and receives titles via a context side-effect.
diff --git a/.agents/skills/migrate-breadcrumb-list/references/tests.md b/.agents/skills/migrate-breadcrumb-list/references/tests.md
new file mode 100644
index 000000000000..40ab24165478
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/references/tests.md
@@ -0,0 +1,133 @@
+# Specs for a migrated page
+
+The migration moves rendering into two TopBar slots, so a spec that does not mount the bar renders nothing and fails as though the component were broken. Fix the harness first, then the queries.
+
+## Contents
+
+- [Mount the bar](#mount-the-bar)
+- [Queries](#queries)
+- [Assert the leaf is gone](#assert-the-leaf-is-gone)
+- [Menus and pagination](#menus-and-pagination)
+- [Stores the new component reads](#stores-the-new-component-reads)
+- [What jsdom cannot test](#what-jsdom-cannot-test)
+
+## Mount the bar
+
+The provider alone is not enough — the outlets have to exist.
+
+```tsx
+// The header renders into TopBar slots, so the bar has to be mounted alongside
+// it for the breadcrumbs and title to appear.
+function renderHeader(org = organization) {
+  return render(
+    <TopBar.Slot.Provider>
+      <TopBar />
+      <MyHeader {...props} />
+    </TopBar.Slot.Provider>,
+    {organization: org}
+  );
+}
+```
+
+`import {TopBar} from 'sentry/views/navigation/topBar'`.
+
+**The trap:** a spec that stubs individual outlets instead of mounting `<TopBar />` will usually stub `title`, `actions`, and `feedback` but not `breadcrumbs` — which did not exist before this migration. Parent crumbs then render nowhere and the failure reads "unable to find role link". Either add the missing outlet or switch to `<TopBar />`. Find these before you start:
+
+```bash
+grep -rln 'TopBar.Slot.Outlet' static/app --include='*.spec.tsx'
+```
+
+A spec that renders a Shape C wrapper standalone with no provider at all cannot work once the wrapper owns two slots. Wrap it or delete it — do not leave it asserting on a component that now renders `null`.
+
+## Queries
+
+Scope to the bar, because the page body often repeats the same words.
+
+```tsx
+const topBar = screen.getByRole('banner');
+expect(await within(topBar).findByRole('link', {name: 'Monitors'})).toBeInTheDocument();
+expect(
+  within(topBar).getByRole('heading', {name: 'My Monitor', level: 1})
+).toBeInTheDocument();
+```
+
+| Target                              | Query                                                                                                                                            |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The trail                           | `getByRole('list')` — an `<ol>`. There is no `<nav>` and no `aria-label="Breadcrumbs"`                                                           |
+| A parent crumb                      | `getByRole('link', {name})`                                                                                                                      |
+| The page title, in the TopBar       | `getByRole('heading', {name, level: 1})` — the `<h1>` comes from the outlet                                                                      |
+| The page title, rendered standalone | `getByText(name)` — **not** `getByRole('heading')`                                                                                               |
+| Overflow trigger                    | `getByRole('button', {name: 'More breadcrumbs'})`                                                                                                |
+| Copy action                         | `getByRole('button', {name: <your label>})`                                                                                                      |
+| A `type: 'button'` trailing action  | `getByRole('button', ...)` **even when it is a link** — scraps `LinkButton` renders `<a role="button">`, so `getByRole('link')` will not find it |
+| Menu trigger                        | `getByRole('button', {name: <triggerLabel>})`                                                                                                    |
+| Pagination chevron                  | `getByRole('button', {name: <ariaLabel>})`; disabled has `aria-disabled="true"`                                                                  |
+| Editable title                      | `getByText(value)`, click, then `getByRole('textbox', {name: <aria-label>})`                                                                     |
+| Project picker                      | `await findByRole('button', {name: 'Selected Project: <slug>'})` — needs `findBy`                                                                |
+
+Of the legacy test ids, only `breadcrumb-link` still exists. `breadcrumb-list` and `breadcrumb-item` are gone — but they appear in no spec today, so there is nothing to sweep. Prefer roles regardless.
+
+## Assert the leaf is gone
+
+The regression this migration is most likely to reintroduce is the page name appearing twice. Assert the negative, not just the positive:
+
+```tsx
+const breadcrumbs = await screen.findByRole('list');
+expect(within(breadcrumbs).getByRole('link', {name: 'Dashboards'})).toBeInTheDocument();
+expect(
+  screen.getByRole('heading', {name: 'Custom Errors', level: 1})
+).toBeInTheDocument();
+expect(within(breadcrumbs).queryByText('Custom Errors')).not.toBeInTheDocument();
+```
+
+If the page previously rendered an action you moved into the title menu, assert its old standalone form is absent too — a `queryByRole(...).not.toBeInTheDocument()` alongside the new menu assertion.
+
+## Menus and pagination
+
+Menu items are `menuitemradio`, and submenus open on hover:
+
+```tsx
+await userEvent.click(await screen.findByRole('button', {name: 'Monitor Actions'}));
+expect(
+  await screen.findByRole('menuitemradio', {name: 'Star for Team'})
+).toBeInTheDocument();
+
+// Submenus open on hover, not on click.
+await userEvent.hover(await screen.findByRole('menuitemradio', {name: 'Star for Team'}));
+```
+
+Order is worth asserting when actions were consolidated, since that is the thing reviewers cannot see in a diff:
+
+```tsx
+expect(screen.getAllByRole('menuitemradio').map(el => el.textContent?.trim())).toEqual([
+  'Copy ID to clipboard',
+  'Share',
+  'Delete',
+]);
+```
+
+Grouped sections are `getByRole('group', {name: <section label>})`.
+
+## Stores the new component reads
+
+`leadingGraphic` badges resolve projects and teams through hooks, so a spec that passed with `initializeOrg({projects: []})` may now find nothing. Load the stores directly:
+
+import {ProjectsStore} from 'sentry/stores/projectsStore';
+import {TeamStore} from 'sentry/stores/teamStore';
+
+```tsx
+ProjectsStore.loadInitialData([project]);
+TeamStore.loadInitialData(teams, false, null);
+```
+
+If a title action fetches, mock its endpoint. To pin a loading state deliberately, `asyncDelay: new Promise<void>(() => {})` never resolves. And check the fixture actually satisfies whatever condition gates the action — `ReleaseFixture` ships `url: ''`, so an action rendered only when a URL exists is absent by default and a test asserting on it fails correctly. Override the fixture field, not the assertion.
+
+**A green existing spec can prove nothing.** Before trusting it, confirm it actually asserted on the header — a `findByText(name, {exact: false})` often matches body text and stays green through a migration that broke the trail. If the page has no header coverage at all, add a spec: the checklist's leaf-absent assertion cannot hold otherwise. `views/navigation/topBar.spec.tsx` is the canonical harness to copy; its Seer and feedback mocks are only for its own assertions and are not needed to mount the bar.
+
+## What jsdom cannot test
+
+Below 512px the trail collapses into an overflow `…` menu, driven by a container query. **jsdom never evaluates container queries**, so the collapse cannot be exercised in a page spec.
+
+The component's own spec asserts on emitted emotion rules to cover this. Do not copy that into a page spec — it couples the test to generated CSS and breaks on unrelated style edits. The collapse is covered once, in `static/app/components/core/breadcrumbList/breadcrumbList.spec.tsx`; page specs should assert the items they pass in, and leave responsive behavior to that spec and a manual resize check.
+
+That component spec also tolerates exactly one React warning: the core `Container` primitive leaks a `containertype` DOM attribute. If a page spec fails all `console.error`s, expect to allow that one until the primitive is fixed.
diff --git a/.agents/skills/migrate-breadcrumb-list/references/title-item.md b/.agents/skills/migrate-breadcrumb-list/references/title-item.md
new file mode 100644
index 000000000000..b226d48c100c
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/references/title-item.md
@@ -0,0 +1,128 @@
+# Building the title item
+
+The legacy leaf crumb allowed `label: React.ReactNode`. Both new title types require `label: string`. Everything else in that JSX has to be placed into a named slot, moved elsewhere, or consciously dropped.
+
+## Contents
+
+- [Which title type](#which-title-type)
+- [Decompose a rich label](#decompose-a-rich-label)
+- [Label content that is not one string](#label-content-that-is-not-one-string)
+- [Trailing actions](#trailing-actions)
+- [Pagination](#pagination)
+- [Building the item outside JSX](#building-the-item-outside-jsx)
+
+## Which title type
+
+| Type             | Use when                               | Notes                                                                                                                                                                    |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `page-title`     | The page name is fixed text            | Accepts `labelTooltip`, `leadingGraphic`, `pagination`, `trailingActions`                                                                                                |
+| `editable-title` | The user can rename the thing in place | Requires `value`, `onChange`, and `'aria-label'` as a quoted key. Has **no** `trailingActions` and **no** `pagination` — `EditableText` supplies its own edit affordance |
+
+`editable-title` also takes `allowEmpty`, `autoSelect`, `errorMessage`, `isDisabled`, `leadingGraphic`, `maxLength`, `placeholder`. The only exemplar in the repo is `views/dashboards/dashboardBreadcrumbTitle.tsx`.
+
+If the page is editable in one state and static in another, return a different item per state rather than toggling `isDisabled` — one early return each, as `dashboardBreadcrumbTitle.tsx` does.
+
+## Decompose a rich label
+
+| Legacy label contained                              | Goes to                                                                                                      |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `IdBadge`, `ProjectBadge`, `ProjectAvatar`, an icon | `leadingGraphic`                                                                                             |
+| An always-on tooltip explaining the name            | `labelTooltip`                                                                                               |
+| A copy-to-clipboard button                          | `trailingActions: {type: 'copy'}`                                                                            |
+| An editable text field                              | the `editable-title` type                                                                                    |
+| Prev/next chevrons                                  | `pagination`                                                                                                 |
+| A `Tooltip showOnlyOnOverflow`                      | **nothing** — the title already truncates with an ellipsis                                                   |
+| A `<Version>` element                               | `label: formatVersion(version)` — `Version` formats by default, so this preserves the rendered text          |
+| A 28px badge lifted from `Layout.Title`             | `leadingGraphic` with `avatarSize={16}` — 28px overflows the fixed slot                                      |
+| A badge rendering its own slug text                 | add `hideName`; that text belongs in `label`, not the 16×16 slot                                             |
+| An `<ExternalLink>` wrapping an icon                | `trailingActions: {type: 'button'}` with a `LinkButton` (`external`, `size="zero"`, `variant="transparent"`) |
+
+`leadingGraphic` is a fixed **16×16** slot rendered `aria-hidden`, so the label carries all the meaning. Two rules follow, and the second is the one that bites:
+
+1. Pass `avatarSize={16}` — a 28px avatar carried over from `Layout.Title` will clip.
+2. **Pass `disableLink` on every `IdBadge` and `ProjectBadge`.** They render a real focusable `<a href>` to an auto-generated project page unless you do, putting a tabbable link inside an `aria-hidden` subtree. It typechecks, passes every test, and is an `aria-hidden-focus` axe violation.
+
+Safe as a blanket rule: across every current and prospective leading graphic, **none** passes an explicit `to` or `onClick`, so `disableLink` drops no intentional destination. `ProjectAvatar` and `AppIcon` have no link path at all and need nothing.
+
+```tsx
+leadingGraphic: project ? (
+  <ProjectBadge disableLink project={project} avatarSize={16} hideName />
+) : (
+  <Placeholder width="16px" height="16px" />
+),
+```
+
+**Drop `avatarProps={{hasTooltip: true, tooltip: project.slug}}` — do not route it to `labelTooltip`.** Several legacy badges carry it, and it is dead code rather than information worth rescuing: inside `aria-hidden` with no focusable trigger the tooltip is already unreachable by keyboard and invisible to assistive tech. The content is `project.slug` in every instance, and the trail already discloses the project.
+
+**The exemplars predate this ruling.** `issueIdBreadcrumb.tsx`, `traceBreadcrumbs.tsx`, and `transactionBreadcrumbs.tsx` all still pass `avatarProps={{hasTooltip: true}}` on a `leadingGraphic`. Follow the rule, not those three lines — and do not treat them as precedent for adding it back.
+
+Keep `labelTooltip` for genuinely non-obvious content — `issueIdBreadcrumb.tsx` uses it to explain what a short-ID _is_, `conversationsBreadcrumbs.tsx` to expose a full UUID behind a truncated one. Restating a slug there competes with that. If a page really needs the project surfaced, the answer is a `type: 'link'` crumb pointing at it, not a tooltip on a decorative icon.
+
+## Label content that is not one string
+
+The table above is not exhaustive. Three shapes have **no representable form**, and each needs a decision recorded in the PR description rather than a silent workaround.
+
+**A sibling decorative badge** — `<FeatureBadge type="new" />` rendered next to the trail. It is not part of the label. `trailingActions: {type: 'button'}` is typed `React.ReactElement<ButtonProps | LinkButtonProps>`, so a badge will not typecheck there, and `leadingGraphic` is an `aria-hidden` 16×16 slot, which is semantically wrong. Either drop it or move it to `TopBar.Slot name="actions"` — say which in the PR.
+
+**Multi-part text** — `AppIcon + name + '-' + <Version truncate />`. Flatten to a template string:
+
+```tsx
+label: buildNumber ? `${appName} (${version})` : appName,
+```
+
+The `<Version>` and `<Text>` wrappers are lost, including their own truncation. That is accepted: the title truncates already.
+
+**An action with no accessible name.** Legacy markup sometimes wrapped a bare icon in a link or button with only a `Tooltip` for context. Moving it into `trailingActions` forces a real name — `copy` needs `label`, `menu` needs `triggerLabel`, a `button` element needs its own. That is a new user-facing string: wrap it in `t()` and call it out in the PR rather than passing the tooltip text through silently.
+
+**A skeleton label** — a `Flex` of `Placeholder`s in a pending branch. `label` is required and non-optional, so there is nowhere to put it. Render the title only once the name resolves, using one early return per state. Do not pass `label: ''`.
+
+## Trailing actions
+
+One action is a bare object. Two or more is an array whose absent entries are `null` — `undefined` and `false` are not assignable:
+
+```tsx
+trailingActions: [
+  {type: 'copy', text: id, label: t('Copy ID'), tooltip: t('Copy ID')},
+  canShare ? {type: 'button', element: <Button ... />} : null,
+],
+```
+
+| Action   | Required                                                                              |
+| -------- | ------------------------------------------------------------------------------------- |
+| `copy`   | `text`, `label` (accessible name). Optional `icon`, `tooltip`, `onCopy` for analytics |
+| `menu`   | `items` (`MenuItemProps[]`), `triggerLabel`. Optional `triggerIcon`                   |
+| `button` | `element`, typed `React.ReactElement<ButtonProps \| LinkButtonProps>`                 |
+
+Reach for a standalone `copy` only when it would otherwise be a single-element array. As soon as the title also needs a menu, put the copy entry **inside** the menu — one affordance beside the title reads better than a row of icons.
+
+Build conditional menu items by spreading, not filtering:
+
+```tsx
+const items = [
+  favoriteItem,
+  ...(canEdit ? [editItem] : []),
+  ...(organization.features.includes('dashboards-import') ? [exportItem] : []),
+];
+```
+
+When a button you are deleting had a `data-test-id`, reuse it as the menu item's `key` so existing selectors keep working. Move any `trackAnalytics` call onto the item's `onAction` — a menu-level handler would fire for siblings too.
+
+## Pagination
+
+`{previous, next}`, each `{ariaLabel, to?, disabled?, onClick?, tooltip?}`. A direction with no `to` renders disabled.
+
+Keep `pagination` present even when neither direction is navigable, rather than adding it once data resolves — the chevrons hold their space from the first render, so the title does not shift. Give the disabled state a `tooltip` too: it is what explains the feature to someone whose current item has no neighbours. `tooltip` accepts rich content and stays hoverable, so links inside remain reachable.
+
+## Building the item outside JSX
+
+A hook or helper returning a title item must pin the discriminant, or `type` widens to `string` and the union stops narrowing:
+
+```tsx
+return {
+  type: 'page-title',
+  label: group.shortId,
+  // ...
+} as const satisfies BreadcrumbTitleItem;
+```
+
+`import type {BreadcrumbTitleItem} from '@sentry/scraps/breadcrumbList'`. Exemplar: `views/issueDetails/header/issueIdBreadcrumb.tsx`.

From 25e56c48a9468378dddea42f174cfb8537d11ec9 Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Thu, 10 Sep 2026 10:16:44 +0200
Subject: [PATCH 2/6] fix(skills): Correct the mangled page-filter example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The snippet was a bare `to: {...}` fragment, which the formatter parsed as a
labeled statement and rewrote into a comma operator — assigning `query` to
`pathname`. Wrapping it in a complete `items` array makes it valid TypeScript
so the formatter leaves it intact.
---
 .agents/skills/migrate-breadcrumb-list/SKILL.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/.agents/skills/migrate-breadcrumb-list/SKILL.md b/.agents/skills/migrate-breadcrumb-list/SKILL.md
index bc566ac096a8..27eac408fa3a 100644
--- a/.agents/skills/migrate-breadcrumb-list/SKILL.md
+++ b/.agents/skills/migrate-breadcrumb-list/SKILL.md
@@ -61,9 +61,13 @@ const query = {
 
 // A legacy `to` is often a bare pathname string. Restructure it into an object —
 // there is nowhere to hang a query otherwise.
-to: {
-  pathname: (makeReleasesPathname({organization, path: '/'}), query);
-}
+const items = [
+  {
+    type: 'link' as const,
+    label: t('Releases'),
+    to: {pathname: makeReleasesPathname({organization, path: '/'}), query},
+  },
+];
 ```
 
 A bare pass-through is the default and is exactly what `preservePageFilters` did — override a param only when the destination genuinely needs something else, as the `statsPeriod` example above does. When the crumb already has a `to` object, merge rather than replace: `{...to, query: {...query, ...to.query}}`.

From b3da6dc9bc47444352eb86c7e73f7f914f9eaf19 Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Thu, 10 Sep 2026 11:43:19 +0200
Subject: [PATCH 3/6] docs(skills): Drop skill claims the merged breadcrumb
 fixes invalidated

Three merges landed on master: the story stopped documenting a
`preservePageFilters` prop, the spec's `containerType` warning tolerance was
removed as dead code, and the transaction-summary leading graphic gained
`disableLink`. The skill still described the first two as outstanding.

Drops the aside about the story demoing the prop, the tolerance advice telling
page specs to allow that warning, and the staleness note in Sources. The
delete condition for the page-filter section now turns solely on the six
call sites that still pass the prop.
---
 .agents/skills/migrate-breadcrumb-list/SKILL.md            | 2 --
 .agents/skills/migrate-breadcrumb-list/SPEC.md             | 4 ++--
 .agents/skills/migrate-breadcrumb-list/references/tests.md | 2 --
 3 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/.agents/skills/migrate-breadcrumb-list/SKILL.md b/.agents/skills/migrate-breadcrumb-list/SKILL.md
index 27eac408fa3a..171ce0b147e4 100644
--- a/.agents/skills/migrate-breadcrumb-list/SKILL.md
+++ b/.agents/skills/migrate-breadcrumb-list/SKILL.md
@@ -74,8 +74,6 @@ A bare pass-through is the default and is exactly what `preservePageFilters` did
 
 Six call sites still pass it: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
 
-The component's own docs still demo it (`grep -n preservePageFilters static/app/components/core/breadcrumbList/breadcrumbList.mdx`). If that grep returns nothing the docs have been fixed; trust the type, not the doc, either way.
-
 ## Which API takes what
 
 |                                      | Accepts                                                                                                                     | Shape             |
diff --git a/.agents/skills/migrate-breadcrumb-list/SPEC.md b/.agents/skills/migrate-breadcrumb-list/SPEC.md
index 6a4a53a45048..0274c1bfd7ad 100644
--- a/.agents/skills/migrate-breadcrumb-list/SPEC.md
+++ b/.agents/skills/migrate-breadcrumb-list/SPEC.md
@@ -21,7 +21,7 @@ Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/even
 ## Sources
 
 - `components/core/breadcrumbList/` — authoritative for the item unions and every prop. The types win over the story.
-- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination). **Stale on `preservePageFilters`**, which it demos but the type does not accept.
+- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination).
 - `views/navigation/topBar.tsx` — slot names, and the `<Heading as="h1">` that makes the title outlet the page heading.
 - Reference migrations: getsentry/sentry#120729 (conversations), #120794 (trace view), #123128 (transaction summary), #121282 (dashboards actions), #123569 (replay actions). #122697 removed the migration flag; the earlier PRs' flag forks are dead patterns.
 - Ten already-migrated call sites in `static/app/views/`, enumerated in `SKILL.md`.
@@ -36,6 +36,6 @@ Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/even
 ## Maintenance
 
 - Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
-- Delete the `preservePageFilters` section once `grep -n preservePageFilters static/app/components/core/breadcrumbList/breadcrumbList.mdx` returns nothing **and** no legacy importer still passes the prop.
+- Delete the `preservePageFilters` section once no legacy importer still passes the prop: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`. Six remain.
 - Prune `references/call-site-inventory.md` as rows land. When it empties and the count reaches 4, delete this skill.
 - Update `SPEC.md` when intent, scope, the non-negotiable constraints, or the sources change.
diff --git a/.agents/skills/migrate-breadcrumb-list/references/tests.md b/.agents/skills/migrate-breadcrumb-list/references/tests.md
index 40ab24165478..5f8f86dfcb20 100644
--- a/.agents/skills/migrate-breadcrumb-list/references/tests.md
+++ b/.agents/skills/migrate-breadcrumb-list/references/tests.md
@@ -129,5 +129,3 @@ If a title action fetches, mock its endpoint. To pin a loading state deliberatel
 Below 512px the trail collapses into an overflow `…` menu, driven by a container query. **jsdom never evaluates container queries**, so the collapse cannot be exercised in a page spec.
 
 The component's own spec asserts on emitted emotion rules to cover this. Do not copy that into a page spec — it couples the test to generated CSS and breaks on unrelated style edits. The collapse is covered once, in `static/app/components/core/breadcrumbList/breadcrumbList.spec.tsx`; page specs should assert the items they pass in, and leave responsive behavior to that spec and a manual resize check.
-
-That component spec also tolerates exactly one React warning: the core `Container` primitive leaks a `containertype` DOM attribute. If a page spec fails all `console.error`s, expect to allow that one until the primitive is fixed.

From 51e832d4c17a631dbf39f8221a0c3f0a18a66c3e Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Thu, 10 Sep 2026 15:02:17 +0200
Subject: [PATCH 4/6] docs(skills): Steer breadcrumb migrations to
 extractSelectionParameters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page-filter guidance led with a `statsPeriod: '24h'` override, so the
exception read as the pattern — a cold run copied it into a page that wanted a
plain pass-through. Shows preserving all six first, then overriding, then
leaving the pathname bare.

Also records why replicating the flag matters: a crumb that loses it does not
merely fail to carry filters, it clears them. `PageFiltersContainer`
reconciles against the URL on navigation and an absent `project` reads as an
empty selection rather than "unchanged".
---
 .../skills/migrate-breadcrumb-list/SKILL.md   | 39 ++++++++++---------
 1 file changed, 21 insertions(+), 18 deletions(-)

diff --git a/.agents/skills/migrate-breadcrumb-list/SKILL.md b/.agents/skills/migrate-breadcrumb-list/SKILL.md
index 171ce0b147e4..95a45033a689 100644
--- a/.agents/skills/migrate-breadcrumb-list/SKILL.md
+++ b/.agents/skills/migrate-breadcrumb-list/SKILL.md
@@ -44,33 +44,36 @@ Through a **spread it compiles clean** — and spreading legacy crumbs is the mi
 .map(crumb => ({type: 'link' as const, ...crumb}))
 ```
 
-Excess-property checking only applies to fresh object literals, so a `Crumb` carrying `preservePageFilters` passes straight through to `<Link>`, which ignores it. No type error, no failing test. **Destructure explicitly instead of spreading**, and rebuild the query yourself:
+Excess-property checking only applies to fresh object literals, so a `Crumb` carrying `preservePageFilters` passes straight through to `<Link>`, which ignores it. No type error, no failing test. **Destructure explicitly instead of spreading**, then rebuild the query.
+
+Note the stakes. A crumb that loses the flag does not merely fail to carry filters — it **clears** them. `PageFiltersContainer` reconciles its store against the URL on navigation, and an absent `project` reads as an empty selection rather than "unchanged". Replicating the flag is not polish; skipping it changes what the destination shows.
 
 ```tsx
 import {extractSelectionParameters} from 'sentry/components/pageFilters/parse';
 
-// Build the query once, above the items array. Override any param the destination
-// needs different — and drop `start`/`end` whenever you override `statsPeriod`, or
-// an absolute range and a relative period both travel and the destination picks.
-const query = {
-  ...extractSelectionParameters(location.query),
-  statsPeriod: '24h',
-  start: undefined,
-  end: undefined,
+// Preserve all six — project, environment, statsPeriod, start, end, utc.
+// A legacy `to` is often a bare pathname string; restructure it into an
+// object, as there is nowhere to hang a query otherwise.
+const preserveAll = {
+  pathname: makeReleasesPathname({organization, path: '/'}),
+  query: extractSelectionParameters(location.query),
 };
 
-// A legacy `to` is often a bare pathname string. Restructure it into an object —
-// there is nowhere to hang a query otherwise.
-const items = [
-  {
-    type: 'link' as const,
-    label: t('Releases'),
-    to: {pathname: makeReleasesPathname({organization, path: '/'}), query},
+// Preserve some — spread, then override. Clearing `start`/`end` is required
+// whenever you set `statsPeriod`, or an absolute range and a relative period
+// both travel and the destination picks one.
+const preserveSome = {
+  pathname: makeReleasesPathname({organization, path: '/'}),
+  query: {
+    ...extractSelectionParameters(location.query),
+    statsPeriod: '24h',
+    start: undefined,
+    end: undefined,
   },
-];
+};
 ```
 
-A bare pass-through is the default and is exactly what `preservePageFilters` did — override a param only when the destination genuinely needs something else, as the `statsPeriod` example above does. When the crumb already has a `to` object, merge rather than replace: `{...to, query: {...query, ...to.query}}`.
+Preserve nothing by leaving the bare pathname alone — that is what a crumb _without_ the flag did, and migrating one is not an occasion to start preserving. When the crumb already has a `to` object, merge rather than replace: `{...to, query: {...extractSelectionParameters(location.query), ...to.query}}`.
 
 Six call sites still pass it: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
 

From 5c8c2aa9be7d7a9094ae0d04b4b1fe215e40c237 Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Thu, 10 Sep 2026 15:12:17 +0200
Subject: [PATCH 5/6] docs(skills): Run the skill-writer precision pass on the
 migration skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the fallback branch the shape table was missing: an agent meeting a header
that matches no row had no instruction and dead-ended at classification. It now
follows the closest row by what the file has, and asks rather than guessing when
a header is structured unlike any of them.

Adds `preservePageFilters` to the description. The skill's most distinctive
section covered it while the trigger language did not, so a page losing filters
on a crumb click would not have surfaced the skill. The token appears nowhere
outside breadcrumbs, so it does not widen false positives.

Moves the provenance table out of `SPEC.md` into a new `SOURCES.md`, which also
records the two cold runs, the deltas they produced, and the rejected designs —
a component prop and a `pageFilterQuery` helper. Drops a baked call-site count
next to the grep that regenerates it, and tightens two passages to stay under
the 20,000-character advisory.
---
 .../skills/migrate-breadcrumb-list/SKILL.md   | 10 +++---
 .../skills/migrate-breadcrumb-list/SOURCES.md | 34 +++++++++++++++++++
 .../skills/migrate-breadcrumb-list/SPEC.md    | 10 +-----
 3 files changed, 41 insertions(+), 13 deletions(-)
 create mode 100644 .agents/skills/migrate-breadcrumb-list/SOURCES.md

diff --git a/.agents/skills/migrate-breadcrumb-list/SKILL.md b/.agents/skills/migrate-breadcrumb-list/SKILL.md
index 95a45033a689..b74659b1d03d 100644
--- a/.agents/skills/migrate-breadcrumb-list/SKILL.md
+++ b/.agents/skills/migrate-breadcrumb-list/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: migrate-breadcrumb-list
-description: Migrates page-navigation breadcrumbs from the legacy `sentry/components/breadcrumbs` component to `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across the TopBar `breadcrumbs` and `title` slots. Use when a page still renders `<Breadcrumbs crumbs={...}/>`, when parent crumbs and the page title need separating into two TopBar slots, when `Layout.Title` double-renders the page name, or when working through the BreadcrumbList migration backlog. Trigger on "migrate breadcrumbs", "migrate to BreadcrumbList", "replace sentry/components/breadcrumbs", "split breadcrumbs into TopBar slots", "BreadcrumbList.Title", "the page title renders twice". Not for event breadcrumbs (`sentry/types/breadcrumbs`, the issue-detail timeline), and not for the route-driven SettingsBreadcrumb system.
+description: Migrates page-navigation breadcrumbs from the legacy `sentry/components/breadcrumbs` component to `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across the TopBar `breadcrumbs` and `title` slots. Use when a page still renders `<Breadcrumbs crumbs={...}/>`, when parent crumbs and the page title need separating into two TopBar slots, when `Layout.Title` double-renders the page name, when a migrated crumb needs to keep the project or date selection, or when working through the BreadcrumbList migration backlog. Trigger on "migrate breadcrumbs", "migrate to BreadcrumbList", "replace sentry/components/breadcrumbs", "split breadcrumbs into TopBar slots", "BreadcrumbList.Title", "the page title renders twice", "preservePageFilters". Not for event breadcrumbs (`sentry/types/breadcrumbs`, the issue-detail timeline), and not for the route-driven SettingsBreadcrumb system.
 ---
 
 # Migrate page breadcrumbs to BreadcrumbList
@@ -75,7 +75,7 @@ const preserveSome = {
 
 Preserve nothing by leaving the bare pathname alone — that is what a crumb _without_ the flag did, and migrating one is not an occasion to start preserving. When the crumb already has a `to` object, merge rather than replace: `{...to, query: {...extractSelectionParameters(location.query), ...to.query}}`.
 
-Six call sites still pass it: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
+Find the call sites that still pass it: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
 
 ## Which API takes what
 
@@ -106,6 +106,8 @@ Classify before editing — the shapes need different amounts of work, and three
 | **C**  | Exported wrapper consumed by other pages — **only** when a consumer wraps it in a `title` slot; an exported header that owns its own slots is B or E | Every consumer changes in the same PR. Per consumer: hoist any surrounding ternary above the slot, delete the wrapping slot, and place or drop every sibling node in that slot                                                                                                                                                              |
 | **E**  | `<Breadcrumbs>` beside a raw `<Heading as="h1">`                                                                                                     | Delete the local heading, or the page ships two `<h1>`s                                                                                                                                                                                                                                                                                     |
 
+**If no row fits, do not force one.** The table describes the headers present when this skill was written. Classify by what the file _has_ — a `Layout.Title`, a raw heading, a wrapping title slot, an exported wrapper — and follow the closest row. If a header is structured unlike any of them, ask before restructuring it rather than guessing, and add a row here once the shape is settled.
+
 `views/performance/breadcrumb.tsx` is type-only (`import type {Crumb}`, no JSX). Its work is deleting a legacy adapter, and it is blocked — see `references/call-site-inventory.md`.
 
 **Shape B has one exception with no leaf crumb at all**, where applying "`Layout.Title` wins" mechanically renders the same text twice — see `references/call-site-inventory.md`.
@@ -125,7 +127,7 @@ const items = parents.flatMap(c =>
 
 An empty `items` renders nothing, and that is correct — the title slot still renders. **Do not invent a parent link to avoid it.** If the legacy code gated the trail on a length check, port the condition.
 
-That rule and Shape B's "give the displaced leaf a `to`" are not in conflict — they apply to different crumbs. A leaf that is the **page name** is now the title and simply disappears from `items`. A leaf that is a **category descriptor** ("Cron Monitor", "Uptime Monitor") is a real parent that was merely unlinked, and it should keep its place with a destination: look for a `make*Pathname` for that category beside the one you already import. Prefer the two-link trail when such a destination exists; drop the crumb only when there is genuinely nowhere to point.
+That does not conflict with Shape B's "give the displaced leaf a `to`" — they are different crumbs. A leaf that is the **page name** becomes the title and leaves `items`. A leaf that is a **category descriptor** ("Cron Monitor") is a real parent that was merely unlinked: look for a `make*Pathname` for that category beside the one you already import, and prefer the two-link trail. Drop it only when there is nowhere to point.
 
 ## Per-page workflow
 
@@ -165,7 +167,7 @@ Already migrated, simplest first. Each answers one question.
 
 ## Intentionally not migrated
 
-Four of the 26 importers keep the legacy component: the legacy component's own spec, plus three call sites that render outside the page `<h1>` and need a `<nav>` landmark `BreadcrumbList` has no mode for. **The count floors at 4 — driving it to 0 destroys a landmark.** The route-driven `SettingsBreadcrumb` system is out of scope too; it never imports the legacy component. Both lists are in `references/call-site-inventory.md`.
+Four importers keep the legacy component — its own spec, plus three call sites that render outside the page `<h1>` and need a `<nav>` landmark `BreadcrumbList` has no mode for. **The count floors at 4; driving it to 0 destroys a landmark.** The route-driven `SettingsBreadcrumb` system is out of scope too. Both lists are in `references/call-site-inventory.md`.
 
 ## Rollout
 
diff --git a/.agents/skills/migrate-breadcrumb-list/SOURCES.md b/.agents/skills/migrate-breadcrumb-list/SOURCES.md
new file mode 100644
index 000000000000..8cef1a826ed9
--- /dev/null
+++ b/.agents/skills/migrate-breadcrumb-list/SOURCES.md
@@ -0,0 +1,34 @@
+# Sources
+
+## Authoritative
+
+- `components/core/breadcrumbList/` — authoritative for the item unions and every prop. The types win over the story.
+- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination).
+- `views/navigation/topBar.tsx` — slot names, and the `<Heading as="h1">` that makes the title outlet the page heading.
+- Reference migrations: getsentry/sentry#120729 (conversations), #120794 (trace view), #123128 (transaction summary), #121282 (dashboards actions), #123569 (replay actions). #122697 removed the migration flag; the earlier PRs' flag forks are dead patterns.
+- Ten already-migrated call sites in `static/app/views/`, enumerated in `SKILL.md`.
+
+## Decisions
+
+- **Guidance is inline, not a component prop.** A `pageFilters` prop on `BreadcrumbItemLinkProps` was designed and rejected: four real call sites cannot express themselves in an enum (whole-query-minus-N keys, inheriting from an `EventView`, and a drawer-tab crumb that is not page navigation), and an escape hatch would defeat the forcing function. A `pageFilterQuery` helper was also built and dropped — at the converted call site its diff was equivalent to the spread it replaced.
+- **Page-filter policy is treated as settled.** Whether a given crumb _should_ carry filters is a product decision. The skill teaches how to replicate existing behaviour, not how to choose.
+- **`references/evidence/` was not created.** The two cold runs below are summarised here instead; their findings are already promoted into rules, and the skill has a defined end of life.
+
+## Iteration
+
+Two cold runs, each a fresh agent given only the skill and one target file, in an isolated worktree.
+
+| Run | Target                                             | Shape | Cost                              | Surfaced                                                                                                                                                                     |
+| --- | -------------------------------------------------- | ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `explore/releases/detail/header/releaseHeader.tsx` | A1    | 13 tool calls, 4 on the spec      | The `disableLink` trap; a checklist grep that flagged its own recommended fix; `LinkButton` rendering `<a role="button">`; a fixture field gating an action out of existence |
+| 2   | `insights/crons/components/monitorHeader.tsx`      | B     | 22 tool calls, ~14 on orientation | Step 6 producing an empty bordered strip; Shape B/C ambiguity; the page-filter example leading with an override; a missing `ProjectsStore` import path                       |
+
+Deltas applied: Shape A split into A1/A2; Shape E added; `disableLink` promoted to a checklist item; the checklist rewritten as greps; the page-filter example reordered to show pass-through first; `call-site-inventory.md` made a conditional read.
+
+Run 2 also found a regression introduced by run 1's fix — the step 6 "add as sibling" branch, added because run 1 read the instruction as unconditional, was wrong for a wrapper left holding only slots.
+
+## Gaps
+
+- No cold run against Shape C, the hardest shape (`explore/components/breadcrumb.tsx`, four consumers with branch-dependent titles).
+- The overflow collapse cannot be tested in jsdom, so no run has exercised it.
+- Reachability, not file counts, determines whether a call-site inconsistency is user-visible; the inventory records shapes but not reachability.
diff --git a/.agents/skills/migrate-breadcrumb-list/SPEC.md b/.agents/skills/migrate-breadcrumb-list/SPEC.md
index 0274c1bfd7ad..264c2340b419 100644
--- a/.agents/skills/migrate-breadcrumb-list/SPEC.md
+++ b/.agents/skills/migrate-breadcrumb-list/SPEC.md
@@ -18,14 +18,6 @@ Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/even
 - The legacy-importer count floors at 4. Driving it to 0 destroys a `<nav>` landmark.
 - Do not add a feature-flag fork. `ui-migration-breadcrumbs` and `useHasNewBreadcrumbs()` no longer exist.
 
-## Sources
-
-- `components/core/breadcrumbList/` — authoritative for the item unions and every prop. The types win over the story.
-- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination).
-- `views/navigation/topBar.tsx` — slot names, and the `<Heading as="h1">` that makes the title outlet the page heading.
-- Reference migrations: getsentry/sentry#120729 (conversations), #120794 (trace view), #123128 (transaction summary), #121282 (dashboards actions), #123569 (replay actions). #122697 removed the migration flag; the earlier PRs' flag forks are dead patterns.
-- Ten already-migrated call sites in `static/app/views/`, enumerated in `SKILL.md`.
-
 ## Known Limitations
 
 - Overflow collapse is a container query and cannot be tested in jsdom; the skill routes it to a manual resize check.
@@ -38,4 +30,4 @@ Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/even
 - Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
 - Delete the `preservePageFilters` section once no legacy importer still passes the prop: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`. Six remain.
 - Prune `references/call-site-inventory.md` as rows land. When it empties and the count reaches 4, delete this skill.
-- Update `SPEC.md` when intent, scope, the non-negotiable constraints, or the sources change.
+- Update `SPEC.md` when intent, scope, or the non-negotiable constraints change; record source and iteration changes in `SOURCES.md`.

From 4ae502ba50b9a95120822e32005c639d4e9917a7 Mon Sep 17 00:00:00 2001
From: Jesse Box <me@jessebox.net>
Date: Thu, 10 Sep 2026 15:28:23 +0200
Subject: [PATCH 6/6] docs(skills): Fold the breadcrumb skill's SPEC into
 SOURCES
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Only 3 of 28 tracked skills carry a committed `SPEC.md`, and most of this
one's content had drifted into duplication: its non-negotiable constraints were
already the checklist in `SKILL.md`, its scope already the description and the
exclusions table, and its jsdom caveat already a gap in `SOURCES.md`.

Keeps the part that was doing real work — the conditions for retiring the
skill and its page-filter section — plus the two limitations nothing else
recorded, and drops the file.
---
 .../skills/migrate-breadcrumb-list/SOURCES.md |  8 +++++
 .../skills/migrate-breadcrumb-list/SPEC.md    | 33 -------------------
 2 files changed, 8 insertions(+), 33 deletions(-)
 delete mode 100644 .agents/skills/migrate-breadcrumb-list/SPEC.md

diff --git a/.agents/skills/migrate-breadcrumb-list/SOURCES.md b/.agents/skills/migrate-breadcrumb-list/SOURCES.md
index 8cef1a826ed9..52601be1414d 100644
--- a/.agents/skills/migrate-breadcrumb-list/SOURCES.md
+++ b/.agents/skills/migrate-breadcrumb-list/SOURCES.md
@@ -32,3 +32,11 @@ Run 2 also found a regression introduced by run 1's fix — the step 6 "add as s
 - No cold run against Shape C, the hardest shape (`explore/components/breadcrumb.tsx`, four consumers with branch-dependent titles).
 - The overflow collapse cannot be tested in jsdom, so no run has exercised it.
 - Reachability, not file counts, determines whether a call-site inconsistency is user-visible; the inventory records shapes but not reachability.
+- Choosing the title on a Shape B or Shape C page is a judgement the skill can frame but not decide — it supplies a priority order and answer keys, not a rule.
+- `select-projects` has no production consumer, so its guidance is untested by use.
+
+## Maintenance
+
+- Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
+- Delete the `preservePageFilters` section once no legacy importer still passes the prop: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
+- Prune `references/call-site-inventory.md` as rows land. **When it empties and the legacy-importer count reaches 4, delete this skill** — it exists to retire a migration, and outliving that migration is how it rots.
diff --git a/.agents/skills/migrate-breadcrumb-list/SPEC.md b/.agents/skills/migrate-breadcrumb-list/SPEC.md
deleted file mode 100644
index 264c2340b419..000000000000
--- a/.agents/skills/migrate-breadcrumb-list/SPEC.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Migrate Breadcrumb List Specification
-
-## Intent
-
-Give an agent a reliable path for moving a page off the legacy `sentry/components/breadcrumbs` component to `@sentry/scraps/breadcrumbList`, splitting one flat crumb array across the TopBar `breadcrumbs` and `title` slots. The dominant failure mode this skill guards against is silent regression: `preservePageFilters` carried through a spread compiles and drops page filters, a surviving `Layout.Title` or raw `<h1>` double-renders the page name, and a wrapper migrated in place nests the `breadcrumbs` slot inside the page heading. None of the three produce a type error or a failing test.
-
-## Scope
-
-In scope: the 22 files importing `sentry/components/breadcrumbs` that render a page-navigation trail, including the wrapper components consumed by several pages and the type-only adapter that feeds them.
-
-Out of scope: event breadcrumbs (`sentry/types/breadcrumbs` and `components/events/breadcrumbs/`, the issue-detail timeline — an unrelated feature that shares the word); the route-driven `SettingsBreadcrumb` system; and the three landmark call sites that render outside the page `<h1>` and need a `<nav>` that `BreadcrumbList` has no mode for. Building new capabilities on the component itself is also out of scope.
-
-## Non-negotiable Constraints
-
-- Never spread a legacy `Crumb` into a typed item. Destructure the fields you want; excess-property checking does not apply through a spread.
-- After migrating a file it must contain exactly one `TopBar.Slot name="title"`, zero `as="h1"`, and zero `Layout.Title`.
-- Never nest the `breadcrumbs` slot inside the `title` slot, and never wrap `BreadcrumbList.Title` in a `Heading`.
-- The legacy-importer count floors at 4. Driving it to 0 destroys a `<nav>` landmark.
-- Do not add a feature-flag fork. `ui-migration-breadcrumbs` and `useHasNewBreadcrumbs()` no longer exist.
-
-## Known Limitations
-
-- Overflow collapse is a container query and cannot be tested in jsdom; the skill routes it to a manual resize check.
-- Choosing the title on a Shape B or Shape C page is a judgement the skill can frame but not decide — it supplies a priority order and answer keys, not a rule.
-- `references/call-site-inventory.md` names specific files and is invalidated by this migration's own PRs. It leads with a regeneration command for that reason.
-- `select-projects` has no production consumer, so its guidance is untested by use.
-
-## Maintenance
-
-- Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
-- Delete the `preservePageFilters` section once no legacy importer still passes the prop: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`. Six remain.
-- Prune `references/call-site-inventory.md` as rows land. When it empties and the count reaches 4, delete this skill.
-- Update `SPEC.md` when intent, scope, or the non-negotiable constraints change; record source and iteration changes in `SOURCES.md`.