Stakeholder Summary

Project Context

• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f
• personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
• project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

• Plain language only. The stakeholder summary never contains file paths, line numbers, function or class names, library mechanics, database tables, API shapes, or language primitives. Use product-level subsystem names ("the telematics provider", "the customer list"), user-facing UI vocabulary (badge, popup, list), and behavioral verbs (create, edit, update, claim, merge, sync). A non-technical stakeholder must be able to read the document end-to-end without translation.
• Center the customer, not the system. Lead with the problem the customer experiences, then the capabilities introduced, then the experience, then the data flow, then what is out of scope, then the questions. The system is the means, not the subject.
• High level only. A stakeholder summary is for getting feedback before kickoff. Skip anything that would only matter once implementation has started: schemas, sequencing, file boundaries, test plans, rollout strategy, telemetry. If a detail is only meaningful to engineers, it does not belong in this document.
• Diagrams carry weight. Use Mermaid for both the user experience flow and the data flow before-and-after. Diagrams are not decoration — they replace paragraphs of prose, so they must be readable on their own.
• Open questions are stakeholder-shaped. The closing questions are framed in customer or product language, not engineering language. They ask stakeholders to confirm framing, scope, and trade-offs — not to make technical decisions.
• Apply the shared readability standard. As it writes and refines the summary, the skill sources the standard by invoking han-communication:readability-guidance and applies it, holding the named audience: the non-technical stakeholder. The plain-language rules above are this skill's domain-specific supplement to the shared standard, not a replacement for it. The standard's dedicated han-communication:readability-editor rewrite pass (Step 5) is this skill's readability rewrite; it and the standardized self-check (Step 6, Pass B) take the place of the freehand plain-language rewrite this skill used to run, so the summary gets one readability review, not two. The standard governs how the summary reads, never whether a required fact from the spec survives.

Stakeholder Summary

Step 1: Resolve the Source and Output Paths

Read the user's argument and conversation context. Identify:

1. The source specification — the file the summary will be derived from. Usually a feature-specification.md, but may be a PRD, design doc, or similar. If the user did not name a file, ask in one short message which file to summarize.
2. The output path — stakeholder-summary.md in the same directory as the source file. Do not place it anywhere else unless the user explicitly says so.
3. Shaping context — anything the user added about the audience, tone, or emphasis ("this is going to leadership", "lean into the customer-trust angle"). Capture it for use in Steps 3 and 4.

If stakeholder-summary.md already exists in the target directory, ask the user whether to overwrite, append a timestamp suffix, or stop. Do not silently overwrite.

Step 2: Read the Source and Project Context

Read the feature specification end-to-end. Then capture:

• The customer problem the feature addresses, in the customer's own words where possible.
• The capabilities the feature introduces, expressed as user-visible actions (not API endpoints, not database changes). This is true even if the outcome is an API and not user visible yet. We want to provide what the spec will do for our end users.
• The user experience: what the customer sees, what choices they make, what happens after each choice.
• The current data flow (what happens today) and the new data flow (what will happen after this ships), at the level of "system A sends X to system B".
• What the spec explicitly says is out of scope, deferred, or handled elsewhere.
• Any open questions the spec already names.

Read the CLAUDE.md in the project named in the specification and project-discovery.md if present — they may surface vocabulary or naming conventions the stakeholder summary should follow.

Step 3: Translate Technical Content into Plain Language

For every piece of content destined for the summary, apply a translation pass:

• System names generalize one level up. "PostgreSQL" → "the database"; "the FleetCommand API" → "the telematics provider"; "the React component" → "the screen".
• API and data shapes become user-visible behaviors. "POST /units/claim" → "Claim it"; "PATCH /customers/1/update endpoint with [field_name]" → "update the existing customer record".
• Engineering trade-offs become product trade-offs. "Eventually consistent reads from the replica" → not mentioned; "we are not building bulk actions" → "Bulk actions. One record at a time for now."
• Acronyms and brand names stay only if a stakeholder would already know them (e.g., the product's own brand, well-known integrations). Otherwise generalize.

If a piece of content cannot be translated without losing meaning, leave it out. The summary is for feedback on shape and direction, not technical correctness.

Step 4: Draft the Stakeholder Summary

Invoke han-communication:readability-guidance to surface the shared readability standard into your context, then draft against it. Use the template at references/stakeholder-summary-template.md. Write the file at the resolved output path, filling in each section in order:

1. Title — # {{Feature Name}} — Stakeholder Summary. Derive the feature name from the source spec's title or H1.
2. What problem are we solving? One or two short paragraphs from the customer's point of view, followed by a short bulleted list of the capabilities the feature introduces (each as a bold name plus one sentence in the customer's voice).
3. What does this open up? Four to six bullets naming the outcomes the feature enables — customer confidence, data trust, downstream features unblocked, etc. Each bullet leads with a bold phrase and adds one sentence of why it matters.
4. What will the user experience look like? One short paragraph framing the experience, followed by a Mermaid flowchart TD showing the user-facing decision and its branches. Keep nodes short and customer-readable. It is acceptable to omit if the change truly has no user interface impact, but this will be rare.
5. How does the data flow today vs. after this change? Mermaid flowchart LR diagrams. The number of diagrams in each subsection — both "today" and "after this change" — matches the number of meaningfully distinct paths the spec actually describes. Never invent paths to hit a template count. Never collapse genuinely distinct paths into one diagram to fit a template count. One today diagram and three "after this change" diagrams is correct if that is what the spec needs; two today diagrams and one "after this change" diagram is also correct if that is what the spec needs. Both subsections follow the same shape:

• Today. One diagram per meaningfully distinct current path, each showing the pain point with style highlighting on the problem nodes. If there is only one current path worth showing (the common case), produce a single "Today" diagram with a one-sentence lead-in above it and no prose block below — the lead-in is enough. If there are two or more current paths, each diagram gets a one-sentence lead-in and a 3 to 5 sentence prose block immediately below that walks the reader through the flow, names the pain point, and names what makes this current path distinct from the other current paths.
• After this change. One diagram per meaningfully distinct new path, highlighting the resulting good state in green. Every "after this change" diagram is followed by a 3 to 5 sentence prose description placed immediately below the diagram, walking the reader through the flow the diagram shows. When there are two or more "after this change" paths, each prose block must additionally name the trigger or condition that sends the customer down this path rather than the others, and the outcome that differs between paths — a stakeholder reading the prose blocks back-to-back should be able to articulate when each path applies. When there is only one "after this change" path, the prose still walks the flow but does not manufacture a contrast against paths that do not exist.
• For all Mermaid charts, do not literally match the template unless the spec aligns. Use a chart that makes sense for the user experience and data flows being described by the feature specification itself. The template contains examples only.

6. What is intentionally not in this slice? Bulleted list of items deliberately excluded. Each item leads with a bold phrase and a one-sentence reason or pointer to where it lives instead. Close the section with a single one-line catch-all confirmation prompt directed at stakeholders — something like "If any of these cuts would block your team, flag it before we kick off." That one line replaces the per-item "is this OK?" question that would otherwise duplicate into the next section.
7. What we are asking stakeholders. Three to five open questions that present a real trade-off, framing call, or sequencing choice the stakeholder must weigh in on. A question only earns a spot here if it asks the stakeholder to choose between two or more substantive alternatives, or to confirm framing the document presents as genuinely open. A bare "is it acceptable that X is deferred?" — where X is already listed in "What is intentionally not in this slice?" — is the duplication this rule exists to prevent. Push those back into the prior section's closing prompt. Questions in this section must either:

• present a trade-off with two or more named alternatives (for example, "Remove the broken button vs. show a placeholder message — which fits the brand better?"), or
• confirm framing or scope that is not already settled by the body of the document (for example, "Are we right to treat this as a v1 for desktop users only, or should mobile parity be part of v1?"), or
• surface an open question the source spec itself names as unresolved. Frame every question so a non-technical reader can answer it, and connect each one to a section above it so the reader can see what it follows from.

Write the file in one pass once the content is ready — the document is short enough that incremental saves are unnecessary. After writing, read it back end-to-end and rewrite any sentence that still leaks implementation detail.

Step 5: Readability Rewrite

Dispatch han-communication:readability-editor over the drafted summary to rewrite it for the non-technical stakeholder against the shared readability standard, preserving every fact from the source spec. This is the skill's dedicated readability rewrite; it replaces the freehand plain-language rewrite the skill used to do at the end of Step 4.

• han-communication:readability-editor — rewrite the summary at the output path against the shared readability standard for the named audience (the non-technical stakeholder), preserving every fact: every capability, exclusion, quantity, named system-in-customer-terms, and stated condition survives with its precision intact. It operates on prose regions only: it does not touch the Mermaid diagram bodies (their customer-readable node and edge labels are checked separately in Step 6, Pass C), and it leaves no engineering artifacts behind. Pass it the output-file path and the named audience; the editor reads han-communication's own canonical rule, so pass no rule path. It rewrites the file in place and returns a rubric verdict and a fact-preservation ledger.

Apply its rewrite. If the editor reports it could not preserve a fact while satisfying a criterion, keep the fact.

Step 6: Self-Check Before Presenting

Run three passes before reporting the summary as done. Each pass has a single focus, and each pass begins with a fresh Read of the output file from disk — do not check against working memory or the draft you held while writing. The Read tool call is required, not optional. Working memory drifts from what actually landed on disk; only the file contents matter.