# Persona-voice posture loader

Aperant-authored posture loader consumed by `apt-release-notes/SKILL.md`.
Per the CLAUDE.md `appendices/` convention, this file augments the parent
skill's context — it is NOT independently router-invocable.

## Why this exists

The dev `CHANGELOG.md` (owned by `/apt:docs changelog`) describes WHAT
changed in engineering terms: file paths, function names, task IDs,
schema bumps. Release notes describe WHY the change matters to a
specific human. Same merge, different voice. The release-notes pipeline
hands you a structured fragment payload — your job is to tune the prose
so the line reads like product-marketing copy for the persona, not like
a commit message with the prefix stripped.

## Posture rules (apply when composing a `Release note: …` line)

1. **Verb first.** Start with the user's outcome — "See your shipped
   builds in one tab" — not the implementation ("Added a `/builds` tab
   to the dashboard"). The reader doesn't care that you added a tab;
   they care that they can now see builds.
2. **Persona-specific framing.**
   - **End-user persona (audience: `end-user`)** — plain language, no
     jargon. Avoid framework names, file paths, API endpoint paths.
     One sentence. Concrete value.
   - **Developer / API persona (audience: `developer-api`)** — API + SDK
     semantics are the value proposition. Naming a new method is good.
     Linking the migration page is good. Don't hide the implementation
     details; they ARE the user-visible surface for this persona.
   - **Internal-team persona (audience: `internal-team`)** — lighter
     polish, faster cadence. One sentence is still ideal but the
     internal team is fine with a touch of process-jargon ("we now
     auto-rotate session tokens") when it conveys real value.
3. **Triage bucket is your friend.** If you don't have strong signal
   for the persona's framing — leave the line in the form the auto-draft
   produced. The compile step will surface it under `## Needs Triage`
   and the human curator can decide whether to ship it. Forced
   confidence in the note voice is a regression class.
4. **Tone matches the persona's archetype.** "The Vibe Coder" persona
   wants energy ("Now you can branch off any session in one click").
   "The Reviewer" persona wants precision ("Branch-from-session now
   preserves your review queue with exact ordering"). Read the
   archetype field in personas.json before composing.
5. **No emoji unless the project's design taste explicitly calls for
   it.** Aperant's house style is restrained; consumer-facing apps with
   "playful" design tokens may differ — defer to the project's design
   brief if one exists.

## What this loader does NOT cover

- Compile-time narrative beyond the per-PR sentence — that's the host
  LLM's wider job at `/apt:release-notes --compile`, informed by
  `PROJECT.md` Core Value, the personas roster, and the structured
  per-tier sections the compiler writes.
- Translating between audience values — picking the right audience is
  set at `/apt:setup` Batch 9 time. The audience field doesn't change
  mid-release; voice changes only at the per-fragment level inside the
  audience already chosen.
