Stakeholder Review Package

---
name: stakeholder-review-package
description: Create or refresh a self-contained HTML stakeholder review package from a PRD, its assumptions and mockups. Combines selected business requirements with every open business assumption and contextual screens, so people can respond in one place; technical assumptions stay with the build team. The review is a derived human-facing document, never an implementation specification.
---

# Stakeholder Review Package

Give business stakeholders one approachable document they can understand and answer. The PRD and technical design retain the complete implementation contract; the assumptions register retains the decisions and their evidence. The HTML is a dated review of those sources, not another source of requirements.

## Read and select

Read the full PRD, the whole current assumptions register, and relevant mockups. Read the technical design only where needed to resolve context. Follow the sources' own writing skills before changing them; preparing a review does not authorize changing requirements, inventing decisions or marking assumptions confirmed. The register sort, research and the changes a user asks for below are the only exceptions.

Select requirements by business consequence: changed procedures, permissions, money or data outcomes, consequential exceptions, scope exclusions, and behavior a stakeholder might reasonably reject. Include important settled rules as well as uncertain ones. Leave internal construction, test mechanics and project history in the source documents. Do not turn every acceptance criterion into a shorter bullet: readers skim this column, so aim for well under half the PRD's criteria, each cut to a sentence or two.

**Show every business assumption, and never filter by importance.** This review is the only place a stakeholder sees them, so no entry stays out because it seems minor. An open entry with no `**Researched**` line first gets `autonomous-prd-refinement`'s "The Research Pass" for that entry; once a technical design exists, the same session also carries a changed answer into the design and, once a build has started, applies `assumptions-document-feedback`'s Step 1a test for a fix or a new ask and its Step 6 placement, labelling the plan entry with where the change came from, without running that skill. The other check before building is whether each entry is the right kind: run `assumptions-document-writing`'s "Sort Every Entry by What Would Settle It" over every open entry and apply what it moves, through that skill, researching again any entry it sends back to be sized. A build choice goes to the technical design as a decision, a fact goes to the register's Technical Assumptions section or is settled, and a question that is already answered, has only one sensible answer, or builds the same thing either way is written up. A review that asks a business stakeholder to bless a build choice or confirm a fact spends their attention on questions that are not theirs, and buries the ones that are. Beyond research and what the user asks for while reviewing, this is the only change to the sources this skill makes; it is a correction of where an entry belongs, not a new decision. The same sort places each entry above or below the line, so only the questions that belong above it are asked and the rest close the review as already decided.

**Every open business assumption gets exactly one answerable place in the HTML.** The Technical Assumptions section stays out: those entries are answered by the build team, and the review states only how many there are, so nothing is hidden. Include provisional answers and reopened decisions still needing attention. Exclude settled entries unless explicitly reopened in the register. Keep original IDs. Inventory the IDs before writing and reconcile them after generation; the supplied renderer checks registers with ID-bearing Markdown headings and a `Validated Assumptions` section. For other formats, produce and check an explicit inventory rather than claiming that parser covers them.

If no assumptions register exists, confirm the PRD has no open assumptions and use `assumptions_source: null`, `open_assumption_ids: []` and an `inventory_note` explaining the absence. Do not invent assumptions or create an empty register just for the renderer. If a register exists, include it; a missing named source is an error. Recheck for a register when refreshing or preparing to share.

A genuine **Blocking Open Question** has no proposed answer to confirm. Surface it directly and resolve it through `assumptions-document-writing` before producing a complete Confirm/Change review. Never invent an ID or proposal to fit the form, or silently leave the question out. The renderer rejects the method’s `### Blocking: ...` entries even with an explicit inventory.

## Organize around the work

Use one brief per PRD by default. Write to whoever is reading it, as "you", not to a named person or role; name someone only when they are part of the behavior being decided, never to say who should answer, approve or agree. Start with two or three sentences on what exists today, what this PRD adds, and its outcome and scope, then a few sections organized around workflows, features or business topics. The renderer orders them by Impact: sections holding the highest-impact questions first, and within a section by Impact, keeping the written order within a level, so a question that defines a term can come before one that uses it. A question keeps its place beside the mockup it is about, so there is no single list across sections. When the PRD belongs to an initiative, the scope also gives its place in the order ("Second of four PRDs in the {Title} initiative"), and its initiative overview (`initiative-breakdown`, Step 5, made from the brief and PRD list first if the initiative has none) goes in `sources`, so the review links it and goes stale when it changes. Each section brings together:

- A short account of what the person will do and what changes. A reader who takes in this account and the selected requirements should understand every card in the section, so define here each term the cards depend on, and when tightening requirements keep what the cards need. Understanding a card must never require studying a mockup or a small detail in a criterion.
- The relevant mockup beside that explanation, with readable text and an enlargement control. Group alternate screens in a labelled gallery; avoid a separate wall of screenshots.
- The assumptions for that section, each shown once with its proposed answer and response controls.

Label the navigation **In this review** and the section eyebrows **Section**. Label the columns **Key acceptance criteria & mockups** and **Assumptions to confirm**. The first is selected; the second contains every asked assumption relevant to that section. Do not call the assumptions “highlights” or “most relevant assumptions.” Keep a prominent, labelled **Feedback on acceptance criteria or mockups** box in the acceptance criteria/mockups column, beside the material it refers to. On narrow screens, it stays with that material before the assumptions.

When an assumption already states a behavior, let its card do that work: do not repeat the proposal in the overview, a highlights list and an assumptions appendix. Link back to the card when needed elsewhere. Impact sets the order, and a small, explained emphasis can mark a consequential decision; never hide an asked assumption behind a filter, an accordion or a link to another document. Every asked question, proposal and answer control is visible by default. Evidence and longer examples may use expandable details.

**Close with what the team decided.** Entries in the register's **Decided by the Project Team** section go in the authoring `decided` list, not a workflow section. The renderer puts them last under its fixed statement that they are business decisions needing no reply, and leaves them out of the answered count, so an untouched section never looks unfinished. Make each entry's first `proposal` paragraph its answer in about 30 words: only that, the title and what it follows from show until the reader opens it. They stay answerable because a stakeholder may know better.

**Each card says what your answer changes.** `if_other` says what the product would do differently if they chose otherwise (what it shows, records or decides, or what it must achieve to count as done), from the register's **If they choose otherwise** line. When it cannot be written honestly, the entry is not a business question: re-sort it.

**Keep cards as short as they can be without losing a decision.** Aim for about 120 visible words from title through what the answer changes; the renderer reports the average. It is a target, so a decision that truly needs more keeps it, and when a cold read finds a card missing something the reader needs, the read wins. Facts several cards share, such as the size of the work, go in the section's account. Cut any sentence whose removal wouldn't change the reader's answer, such as where the work stands or an estimate we can't give yet. Lead with the answer. Anything that changes what Confirm agrees to stays on the card, and supporting detail goes in the expandable evidence. Project shorthand is out of the card's own words: no PRD or design references, no criterion, ticket or ruling numbers, and no ID of anything the reader cannot see in this review. Say what was decided in plain words instead ("A 3-day limit was chosen in March"). Source links may still carry those labels. The renderer rejects the common forms; the cold read below catches the rest.

**Compress words, not decisions.** Write each card in the business's own names for things, never the system's internal vocabulary (state names, flags, the labels its code uses), so a stakeholder recognizes the question as theirs. Preserve actors, values, exceptions, scope, uncertainty, relevant counterevidence and material alternatives. Open each card's proposal with the direct answer to its title, whether or not the register's entry does yet (`assumptions-document-writing`, "Entry Titles"): Yes or No, or the answer itself, then the detail, so a reviewer sees what Confirm agrees to before reading on. If one ID contains several choices, show them separately within its one card. A business-sensitive detail belongs beside the answer, not hidden as background. Do not invent confidence scores. Show the source's confidence and Impact in compact, clearly labelled badges side by side at the top of each assumption card, visible without expanding evidence. Preserve the source values; omit the confidence badge when the source has no confidence. The figure is confidence in the proposal shown and the badge carries it, so never open a card's words with it, and say which answer any other figure belongs to. Keep its styling neutral so confidence is not confused with confirmation or business importance. Evidence and the rationale for the confidence may remain expandable.

A reviewer must be able to answer without opening the full PRD. Source links offer depth and traceability. One page is a useful goal for the narrative, not a cap on the decisions: a genuinely large decision set stays large, organized into bounded workflow sections.

## Preserve sources and freshness

Put a visible notice near the start: **For business review. Selected acceptance criteria and all open business assumptions. Implementation must use the full PRD and technical design.** The renderer adds how many are already decided and listed at the end. When the register has technical assumptions, the notice adds how many, tracked separately for the build team. Make clear that the complete review includes every question, while partial feedback is welcome and unreviewed items remain unanswered.

Store the single HTML file beside the canonical PRD in the project's own Git repository. Derive `{name}` from the PRD filename by removing `.md` and a trailing `-prd`, if present. Use exactly `{name}-stakeholder-review.html`. For the method's standard layout:

```text
docs/prds/{name}/
  {name}-prd.md
  {name}-stakeholder-review.html
```

The same filename applies in `docs/changes/{name}/` or the PRD's existing directory. Refresh this file in place; the preparation date and version belong inside the HTML, with earlier versions retained by Git. Keep it in version control when committing is authorized.

**Keep and send only the HTML** (with the initiative overview, when linked). It embeds the review content, images, scripts and non-executable authoring data. The renderer reads that authoring data to regenerate the review and check freshness; no companion JSON is needed. Use temporary JSON for the first build or while editing the embedded authoring data, then remove it after verifying the HTML retains it. The authoring data holds condensed prose and source mappings, not another canonical assumptions register. Each displayed rule and assumption points to its source, using criterion IDs and assumption IDs; link to actual sections rather than an entire long document where possible.

A self-contained file is a snapshot. Show its preparation date and version and link to the current canonical documents. Record source hashes, including mockup sources and their dependencies, and check freshness before sharing. Refresh the brief after source changes; do not claim that links to a moving branch make embedded content live. Previous feedback keeps its version and IDs; compare against current sources before applying it through `assumptions-document-feedback`. Never carry a confirmation onto a changed question automatically.

Render canonical mockups into embedded images or reuse their markup safely. Record each screen's source and ID. These are generated views, not independently maintained designs. Preserve the depicted scenario, including any deliberate later-release state, and label that scope plainly. A contradiction with current requirements is a source issue to resolve, not something a disclaimer repairs. Do not embed executable third-party prototypes with access to the review's answers. Do not make private material publicly accessible to obtain an image URL.

## Build the HTML

Use [the authoring contract](references/stakeholder-review-authoring.md) and the supplied [renderer](scripts/render_review.py) with [the template](assets/stakeholder-review.html). They provide a neutral responsive layout, decision cards, image enlargement, optional browser-local drafts, a portable saved copy and feedback export. Adapt the presentation where it improves comprehension; preserve the coverage and feedback invariants.

Use inline CSS and small vanilla JavaScript, system fonts and embedded images. No CDN, telemetry, server, third-party form or client-specific branding. Retain the template’s small “Prepared with the Enso Method” footer, embedded Enso mark and link to https://ensomethod.org; keep the review itself visually neutral. Compress images without making screen text hard to read; prefer a file under 1 MB when feasible and report its actual size. Do not omit a necessary screen to hit a byte target. All substantive content remains readable without JavaScript; enhanced controls should explain when JavaScript is needed.

Feedback controls start unanswered and offer only **Confirm** and **Change**. A reviewer may leave an item untouched when they cannot decide; silence is not approval, disagreement or evidence that they read it. Expressed uncertainty belongs under Change with a comment; there is no separate discussion or defer option. Never default to approval or provide "approve all." Mark Change with no explanation as incomplete. Preserve comments even when no button is selected, labelling them as comment-only feedback rather than confirmation.

Export a self-contained reply in two parts, keeping the review title, version, preparation date, reviewer and export timestamp at the top:

1. **Reviewer's feedback:** assumption IDs with Confirmed, Change, incomplete Change or comment-only status and the reviewer's full comments. Separate entries with a line of dashes; do not repeat questions, proposals or source links here. Include acceptance criteria and mockup feedback in full, clearly distinguished from assumption answers and labelled with its section. Collect all IDs with neither a selection nor a nonblank comment into one **No response given** line (or None). These assumptions and their confidence remain unchanged and unconfirmed; do not infer why they were skipped. Entries in the closing section appear only when the reviewer responded, under their own heading; the rest stand as decided.
2. **Wording reviewed — reference only:** for every item with a selection or nonblank comment, include its ID, exact displayed question and proposal (preserving paragraphs), and source references. Separate entries with dashes. Identify this as historical context, not additional feedback, and instruct the processor to compare it with the current assumption before applying the response. Omit untouched items' wording; their IDs remain in the first part.

Retain every reviewer comment and section note without summarizing or rewriting it. Download and clipboard both include both parts. The appendix makes the reply interpretable without a Git commit or access to an old HTML file; the version and links provide traceability, not a substitute for the wording reviewed.

Explain the two downloads by purpose: **Save editable copy (.html)** keeps the review and answers for the reviewer to reopen and edit; **Download reply (.txt)** produces the response to return to the requester. Add **Copy reply to clipboard** alongside the TXT download, using the same complete feedback text so reviewers can paste it into an email or message. Confirm copying only after the browser reports success; if copying is unavailable or denied, explain that visibly and point to the TXT download. Put a short explanation beside each action. Keep the downloads separate; no ZIP or automatic paired download. Downloading saves a local file; it does not send anything or update canonical sources. State that beside the actions, followed by: **Send the downloaded reply (.txt), or paste the copied reply into a message to the person who requested this review.** This instruction works for email, chat or another sharing channel. If browser storage fails, say so and name the editable-copy action.

## Check before handing over

- Compare every proposed rule to its source for meaning, especially exceptions and release boundaries. Verify all open business assumption IDs appear once, and that no settled or technical ID is asked.
- **Run a cold read.** Whoever wrote a card cannot read it as a stranger. Give a fresh subagent only the page's opening and each section's introduction, selected requirements and cards, with no PRD, no design and no project history. Tell it to answer as a business stakeholder receiving this review, for each card: what is being decided? Is this about what the business wants, or a worry about how the work gets done? What in the product, or in what counts as done, depends on your answer? Would you say "why are you asking me?", and why? Could you understand it from the section's introduction and requirements alone, without studying a screen? Could you answer it now? Which words did you not understand? Which sentence wouldn't change your answer? What made it harder to read than it needed to be? A card it cannot explain gets rewritten. One where it cannot say what depends on the answer is rewritten around that difference, or goes back through the sort if there is none. One it would hand off because it is not a business question goes back through the sort, never for seeming unimportant. One it could not answer because what the answer asks of a person is missing goes back through "The Research Pass" for that entry, which sizes it and may change its answer, never only by adding a figure to the card. Rebuild and repeat until no card is unexplained or the wrong kind, at most three rounds, and report what remains. This replaces reading the cards yourself.
- Check source URLs and access; a private-repo URL may require recipient access. Do not silently publish material to solve access.
- Render and inspect the HTML at a phone width and desktop width. Inspect each included screen at readable size. Exercise responses, incomplete corrections, draft restore, saved-copy reopening, enlargement, feedback download, clipboard success and failure, and keyboard navigation. Confirm source confidence stays visible with evidence collapsed at both widths, and copied replies contain the same information as downloaded replies. Verify untouched asked IDs appear only in the grouped no-response list and untouched closing-section IDs not at all, comment-only and incomplete Change entries survive with their reviewed wording, the appendix preserves the displayed wording, unreviewed items never count as approved, and no runtime network request is needed.
- Run the renderer's freshness check and its tests. A matching hash proves which sources were used, not that the prose faithfully summarizes them; perform both checks.
- For a public skill or reusable example, scan every changed file for client names, URLs, record IDs, screenshots and operational facts. Examples must be fictional and unrelated to the private pilot. Keep pilot content and audit evidence in the private project.

Deliver the single HTML file for review, report its size and any meaningful limitation, and open it for the user when the environment supports that. Cold readers know nothing of the business, so they cannot catch a question that is wrong for it: say so at handover and recommend that someone who knows the business reads it before it goes to stakeholders. Do not send, publish, commit or add a new review gate merely because this skill ran.

## While the user is reviewing the page

Once the user is reading the finished review and gives feedback on it, sort the feedback by what it does, not by who first said it. Feedback that answers or changes an assumption goes through `assumptions-document-feedback`. Feedback about how a card reads changes the entry's wording through `assumptions-document-writing`. Either way, update the card, rebuild, and run the freshness check and the renderer's tests, with no research, review round or cold read beyond what those skills require. Run the browser checks once, before the file goes to anyone else. When the user has said what should change, apply it and show the result rather than holding it for another approval; a question about the review gets an answer, not a rewrite.