# Rework recipes — existing material into the narrative

Six source artefacts, each worked into narrative entries. All six work from
[rework-source-workshop.md](../assets/rework-source-workshop.md), a
persona-redacted composite of what a consultant actually arrives with.

The pattern common to all six: **the source's structure is never the
narrative's structure.** A deck organised by team becomes entries organised by
need. A retro organised by sprint becomes entries organised by constraint. A
maturity framework organised by level becomes entries organised by what is
actually in the way.

Read [narrative-format.md](narrative-format.md) for the format itself and
[evidence-and-confidence.md](../../wue-messaging/references/evidence-and-confidence.md)
for the citation policy these recipes apply.

## 0 · Start with an inventory

Before reworking anything, list what you have. Ten minutes here saves an
argument in the readout.

| Source | Date | Author | Evidence in it | Status |
|---|---|---|---|---|
| Workshop wall | 2026-07-16 | Delivery lead | Dots, SME ratings, spend stack | Current, primary |
| Maturity self-assessment | 2024-11 | Engineering manager | None | **Superseded** — premise cancelled 2025 |
| Retro notes | 2026-05→07 | Tech lead | Four sprints of observations | Current, strong |
| SDO readout | 2026-08-01 | Dashboard | Measurements, units unlabelled | Current, needs unit check |
| Prior vendor deck | 2026-06 | External vendor | None | Current, **conflicted** — tooling partnership |
| Internal findings doc | 2026-08-05 | Head of Enablement | None | Current, it is the hypothesis |

Two things fall out of the table immediately:

- The commissioning stakeholder's own doc (§6) contradicts the retro notes (§3) on cause. That gap **is the engagement's headline**: what leadership thought the problem was, versus what the diagnostic found. It is WUE's strongest proof point — do not reconcile it away.
- The 2024 self-assessment rates the group Level 3 on no evidence, and its improvement premise no longer exists. It does not become an entry. It becomes one bullet noting the last self-read is two years old and its basis has gone.

## 1 · Workshop wall → the spine of the ranking

The wall gives you dots (where experts think the problems are), SME maturity
(how they rate themselves) and a spend stack (what is already funded). Three
sources, one entry per theme.

**Before** — the facilitator's typed-up wall:

```text
Skills / knowledge silos ............ 16 dots
tech capability ......... 1.7 SME
#1  tech capability        $340k
"If Engineer C is on leave the pipeline work stops."
```

**After:**

```md
## 1-tech-capability
**Skills silos across data ops, applications and domain knowledge**

### Symptoms
The same individuals always pick up the same work. Pipeline changes wait for one
engineer; when they are on leave that work stops rather than moving to whoever
is free. The group cannot cover itself, and the person who holds the knowledge
cannot take leave without bracing for what they will come back to.

### Signals & measures
- Highest-voted item in the workshop: 16 of 52 dots across 9 participants
- SME self-rating 1.7/3 — the lowest of the five needs rated
- Ranked #1 in the spend stack at $340k, so this is a funded, live gap rather than a neglected one
```

Recipe notes:

- **Convert dots to a share, and say the denominator.** "16 of 52 dots" is checkable; "the top-voted item" is not.
- **A high spend rank is not good news.** Rank #1 means the money is already going in and the problem persists. Say that explicitly, because a client reading "#1 in spend" will otherwise read it as reassurance.
- **Quote one sticky verbatim** in Symptoms. It is the line the room will recognise, and recognition is what gets a finding accepted.
- **Name the human cost in Symptoms.** Leave, dread of on-call, a week that starts already behind, not being heard — one sentence beside the operational picture. Do not turn the thesis into a slogan.
- Only five needs were rated for maturity. That is normal, and the 36 unrated ones do not become entries.

## 2 · Maturity self-assessment → context, not a finding

**Before** — 2024, Level 3 — Defined, no evidence, premise cancelled.

**After** — no entry of its own. One bullet inside the entry it bears on:

```md
### Signals & measures
- The last internal maturity self-read (2024) rated the group Level 3 against its own framework, citing no measurements. Its improvement premise — the platform investment — was cancelled in 2025, so it has not been revisited in two years.
```

Recipe notes:

- **An unevidenced rating is not evidence, at any age.** It is a statement about what the organisation believed about itself. That is worth recording as context and worth nothing as a measure.
- **Say the date and say the basis is gone.** Both facts, no editorialising. The reader draws the conclusion.
- Resist the temptation to translate an internal framework level onto a HoEN score. Two scales measuring different things with a mapping you invented is a fabricated reading.

## 3 · Retro and incident notes → the strongest evidence you have

Four sprints of independent observations of the same thing is close to a
measurement, and it is the one source in this set that nobody wrote to make a
case.

**Before** — the retro log, organised by sprint.

**After** — reorganised by constraint:

```md
## 2-delivery-metrics
**Delivery health is reconstructed by hand, so it is argued about rather than read**

### Symptoms
The delivery numbers are rebuilt manually for each steering meeting. Three teams
keep their own spreadsheets, so a disagreement about performance becomes a
disagreement about whose figures are right. The room spends its calm reconciling
packs instead of deciding.

### Signals & measures
- "We rebuild the delivery numbers by hand for every steering meeting" — workshop, 2026-07-16
- SME self-rating 1.2/3, the lowest of the five needs rated
- No shared dashboard; three private spreadsheets identified
- Lead time and change-failure rate exist on the platform dashboard but were not the numbers used in the last steering pack

## 3-incident-mgmt
**On-call carries knowledge that was never written down**

### Symptoms
Restoring service depends on who answers the page rather than on a runbook.
On-call is something people dread, because the outcome hangs on who happens to
be holding the knowledge that night.

### Signals & measures
- 9 of 52 workshop dots; SME self-rating 1.5/3
- "Nobody wants to be on call for quota-keeper" — workshop, 2026-07-16
- 6 Sev1/2 incidents a month across 3 teams (platform dashboard, 2026-08-01)
- The internal findings doc records incident response as "fine — we have a rota". The workshop and the incident rate disagree with that, and the gap is worth raising directly
```

Recipe notes:

- **Sprint order carries no meaning to a client.** Re-file each observation under the constraint it evidences.
- **A recurring item with no owner is itself the finding.** "Reduce review turnaround" carried forward four sprints and never actioned says more about prioritisation than about review tooling.
- **Name the contradiction in the entry it affects**, in neutral language. "The findings doc records X; the workshop and the incident rate disagree" states both readings and lets the room resolve it. Do not write "leadership is wrong about incidents".

## 4 · SDO readout → readings first, claims second

A dashboard screenshot is Part A work before it is Part B work. Transcribe it
into `rawMetrics`, resolve the units, *then* write about it.

**Before:**

```text
Change failure rate ......... 0.12
MTTR ........................ 45
```

**Unit resolution.** `changeFailPct` is 0–100 and `recoveryTimeHours` is hours,
so both readings are ambiguous as printed:

| Printed | Could be | Entered as | Basis |
|---|---|---|---|
| `0.12` | 12% or 0.12% | `changeFailPct: 12` | The tool reports a fraction; 0.12% is implausible at 0.4 deploys/day |
| `45` | 45 min or 45 h | `recoveryTimeHours: 0.75` | Dashboard MTTR is conventionally minutes; 45h would be extreme for this incident rate |

Both are **assumptions**, so both are stated in the narrative:

```md
## 2-delivery-metrics
**Lead time is dominated by waiting, not by working**

### Symptoms
A change is finished and then sits. Engineers describe the queue rather than the
build as the thing they wait on. Nobody shares one picture they trust, so the
room spends its calm on reconciling spreadsheets.

### Signals & measures
- Median lead time 19h, of which 14h is review wait — 74% of elapsed time (platform dashboard, 90-day median, 2026-08-01)
- Three approvers required on every change regardless of size; "3 approvers for a one-line change" recorded in the S44 retro
- "Review queue" raised in three of the last four retros as a standing item with no owner
- Assumes the dashboard reports change-failure rate as a fraction (`0.12` entered as 12%) and MTTR in minutes (`45` entered as 0.75h). Neither unit is labelled on the dashboard; both should be confirmed with the platform team
```

Recipe notes:

- **74% is the finding; 19h and 14h are the readings.** Do the arithmetic that makes the point, and show the inputs.
- **Put assumptions in `Signals & measures`, not a footnote.** They are read with the evidence there, and the person who can settle them is named.
- **A measurement plus one observation supports a direct claim.** "Lead time is dominated by waiting" is stated flatly because the number says so. Contrast with recipe 5.
- `teamsCount: 3` matters more than it looks — incident counts are compared per team. Omit it and the group is judged as one team.

### Wait time: preserve the method

The same 14h ÷ 19h reading can populate a `waitTimePct: 74` raw override because
the dashboard does not currently carry that field through intake. The override
alone is not enough: the matching `## wait-time` curve note records the
provenance.

```md
## wait-time
**Nearly three quarters of elapsed delivery time is a review queue.**

### Signals & measures
- `waitTimePct: 74` is derived from 14h median review wait ÷ 19h median lead time across the dashboard's 90-day window
- Boundary is commit to production; review wait is the only waiting state available, so this is a partial view rather than full flow efficiency
- Confirmed against three of the last four retros; no correction factor applied
```

Do not turn 74% into a universal target or compare it directly with another
group whose workflow boundary, work types or status discipline differ. Establish
the local baseline, look for a same-group trend, and stop optimising this
measure when another constraint becomes more important.

## 5 · Prior vendor deck → strip the conclusions, keep the questions

Four confident claims, no measurements, and an author with a tooling partnership.
None of the four survives as written.

**Before → after, claim by claim:**

| Vendor claim | Disposition |
|---|---|
| "Velocity below industry benchmark for elite performers" | **Drop.** A bare benchmark proves nothing local. The local reading (19h lead time, 0.4 deploys/day) is in recipe 4 and stands on its own. |
| "Toolchain modernisation is the highest-leverage investment" | **Demote to a question.** Contradicted by the retro evidence, which points at approval policy rather than tooling. |
| "Recommend a 6-month DevOps transformation programme" | **Drop.** A recommendation, not a finding — and "DevOps transformation" is avoid-list language. |
| "Culture is a blocker to change" | **Drop or re-evidence.** Unfalsifiable as written. If there is something real here it is capacity, which has its own evidenced entry. |

What survives is one hedged entry and one honest gap:

```md
## Internal platform friction
**Teams route around the internal platform rather than through it**

### Symptoms
The platform is used where it is mandatory and avoided where it is not. Teams
do not trust it enough to bet a delivery date on it.

### Signals & measures
- 8 of 52 workshop dots; ranked #2 in the spend stack at $180k
- "We use the platform where we have to and route around it where we can" — workshop, 2026-07-16
- A prior vendor assessment (2026-06) named toolchain modernisation as the highest-leverage investment, but showed no measurements and held a tooling partnership. We have not confirmed that reading, and the retro evidence points at approval policy rather than tooling
- What would settle it: adoption figures per platform service, and the review-queue data from recipe 4 held against them
```

Recipe notes:

- **Name the conflict of interest once, factually, and move on.** "Showed no measurements and held a tooling partnership" is checkable. It is not an attack.
- **Hedge in the thesis, not just the bullets.** "Teams route around the platform" is what was observed. "Tooling is the constraint" is what was asserted, and it is not the thesis.
- **"What would settle it" is a finding too.** It converts an unevidenced claim into a next step, which is what the client is paying for.
- **The heading here is deliberately not a need id.** No need in the model is "platform friction" — the closest candidates are `2-infrastructure-as-code` and `3-helpers-templates-accelerators`, and neither is what the workshop meant. Keeping the consultant's own phrase leaves the entry held and visible in the unresolved banner, where *Map to a need* can place it without retyping a word. Forcing it onto the nearest need would bury the fact that the model had no home for it.

## 6 · Internal findings doc → the hypothesis, handled with care

This one is written by the person who commissioned the assessment. It is the
most delicate artefact in the set and the most valuable, because the gap between
it and the diagnostic is the engagement's headline.

**Before:**

> Our biggest problem is clearly tooling. Best practice says we should be
> deploying daily and we are nowhere near that. The team has raised the review
> queue repeatedly but honestly the bigger issue is that we have too few
> engineers — we need 4 more heads. Incident response is fine. We have a rota.

Four assertions, none evidenced, and one of them ("the team has raised the
review queue repeatedly") is a correct observation with the wrong conclusion
attached.

**After** — the capacity claim gets its own entry, taken seriously and re-framed:

```md
## 1-people-purpose
**No slack capacity for upskilling, incident response or design work**

### Symptoms
Every hour is committed before the week starts, so anything unplanned is paid
for out of the next planned thing. Improvement items are carried forward rather
than dropped, which reads as intent without capacity. The week starts already
behind, so there is no slack left for learning, incidents or design.

### Signals & measures
- SME self-rating 1.9/3; 5 of 52 workshop dots
- "Reduce review turnaround" carried as a standing retro item for four sprints with no owner and no action
- No protected improvement time identified in the last two quarters
- Leadership reads this as headcount ("we need 4 more heads"). We have not tested that. On the evidence so far, 74% of lead time is review wait rather than work, which four more engineers would add to rather than relieve
- What would settle it: throughput per engineer before and after the approval policy changes
```

Recipe notes:

- **Do not open with the disagreement.** Lead with what the finding is, then note where leadership's reading differs. The entry is about capacity, not about who was right.
- **Take the underlying concern seriously.** "Too few engineers" is a real feeling about a real pressure. The entry validates the pressure and questions the mechanism.
- **Use the stakeholder's own words in quotes** so they can see they were heard. Feeling heard is one of the human outcomes the messaging asks for, and it is the difference between a finding that lands and one that gets defended against.
- **"Clearly" and "best practice says" are exactly the two phrases the evidence policy names.** When they appear in a source, treat them as markers of where the reasoning stopped, and look for what is underneath.
- The incident-response claim ("fine, we have a rota") is contradicted by the incident rate. It is handled in recipe 3's entry, not here — one contradiction per entry, filed under the need it concerns.

## Finishing the pass

Once every claim is placed:

1. **Rank the entries.** The tool prints the model's own position beside each one. An unexplained `up 7` is an assertion — either the narrative says why, or the order is wrong.
2. **Check the ladder.** Each thesis firm only where a measure or a named document backs it. Recipes 1, 3 and 4 earn direct claims; recipes 5 and 6 do not.
3. **Look for the entry that is all symptoms.** Vivid symptoms in front of one weak bullet reads well-evidenced and is not.
4. **Check the human cost is in Symptoms, not the thesis.** One recognisable cost per entry is enough.
5. **Park what is real but unplaced** under `## tbc` rather than attaching it to the nearest need.
6. **Run the validator**, which catches unresolved headings, missing evidence sections, and `scope:` values no snapshot claims:

```bash
node library/skills/hoen-data-assist/scripts/validate-narrative.mjs --strict --format text narrative/*.md
```