announcement

name	announcement
description	Use when drafting or delivering human-facing repo change communication such as release-note style summaries or chat-ready updates. Draft value comes first; delivery, audience, and omission policy stay adapter-driven.

Announcement

Use this when the user wants human-facing communication about recent repo work, such as a release-note style summary or a delivery-ready team update.

announcement is one public concept:

• recover the human-facing value of recent changes
• draft the message in a stable shape
• deliver it through an adapter-defined human-facing backend when confirmed
• record what was delivered so later announcements can continue from there

Bootstrap

Resolve $SKILL_DIR per ../../shared/references/bootstrap-resolution.md, then resolve the adapter first.

python3 "$SKILL_DIR/scripts/resolve_adapter.py" --repo-root .

What you get after one run:

• <repo-root>/charness-artifacts/announcement/latest.md as the visible draft artifact (the default durable artifact)
• .charness/announcement/announcements.jsonl (the default delivery log) only after explicit draft finalization or delivery

What this does not do:

• backend posting without explicit confirmation
• any delivery at all when the adapter still uses delivery_kind: none

If the adapter is missing but the repo would benefit from explicit section order, audience tags, or delivery defaults, scaffold one:

python3 "$SKILL_DIR/scripts/init_adapter.py" --repo-root .

Then inspect current state:

sed -n '1,220p' <resolved-announcement-artifact> 2>/dev/null || true
python3 "$SKILL_DIR/scripts/collect_commits.py" --repo-root .
python3 "$SKILL_DIR/scripts/infer_audience_tags.py" --repo-root .
git status --short

collect_commits.py returns subject, bounded body, trailers, closing_references, parents, and is_merge per commit. Treat commit-authored body context as the first source of implementation intent before broader file archaeology.

If the adapter is missing, say that you are drafting against inferred defaults and keep the result draft-only. Missing delivery config must not block drafting, but do not present inferred audience or delivery defaults as if the repo had already declared them.

Workflow

1. Restate the announcement goal.
   • draft only
   • draft plus human-facing delivery
   • release-note style versus chat-ready summary
2. Resolve drafting context.
   • collect commits since the last recorded announcement when possible
   • if no delivery record exists yet, use a bounded recent commit window
   • inspect commit bodies, trailers, closing references, and merge commit descriptions before adjacent docs when the user-visible value is not obvious from the subject alone
   • if the announcement scope plausibly covers ongoing or backlog work that has not yet landed, ask up front whether to include in-progress items. When the adapter declares in_progress_sources (kind is host-extensible, for example control_repo or channel_automation), walk every entry and record it in the draft artifact's ## Source surfaces section as collected: <summary> or unavailable: <reason> before drafting body content.
   • when the commit window is large or spans more than one source, consider fanning out triage per references/large-window-fanout.md; merge the audience-tagged partial bullets per section before drafting wording. Pass --fanout-hint to the collect-commits script to surface a fanout_hint block (commit count, advisory signals, recommended flag).
3. Recover audience value before wording.
   • who benefits
   • what surface changed
   • what humans can now do, avoid, or understand better
4. Apply adapter policy.
   • ordered sections
   • public_body_shape: in chat_update, treat sections as coverage hints and group public output by reader-visible outcomes; in release_notes, sections may render as the public taxonomy
   • audience tags when configured (steer wording per references/draft-shape.md; user-tagged bullets must be reframed away from commit-message vocabulary)
   • omission lenses that force high-value but easy-to-miss items into the draft
   • when outputs is non-empty, route each bullet to the matching output by audience tag (see references/draft-shape.md Dual-Output Drafts)
5. Draft the message first.
   • run a public-body pass before writing: for chat updates, prefer reader-visible outcome headings and keep proof/backend vocabulary in maintainer outputs unless it directly changes user behavior
   • when a previous announcement is the baseline, recover its shape before drafting: opener, section rhythm, audience split, and specificity
   • for top-level user-facing output, translate implementation-shaped source language into reader affordances before preserving mechanism details in maintainer-facing output
   • when a change introduces both a canonical command, directive, or behavior and a shorter alias, explain the canonical behavior first and mention the alias second
   • prefer short sections and concrete bullets
   • explain why a change matters, not only the mechanism
   • omit low-signal hygiene unless the user explicitly wants a full changelog
6. Show the draft inline before delivery.
   • paste the draft body verbatim into the response, in addition to writing the artifact file. The artifact alone is invisible work; reviewers cannot critique what they cannot see in chat.
   • when outputs is non-empty, paste each output body separately and label it with its id and delivery_role.
7. If the user wants delivery, resolve the backend seam only then.
   • none: draft only; release-notes: update a checked-in markdown file; human-backend: deliver through an adapter-defined human-facing backend
   • if the backend depends on reusable private access, prefer one logical capability in delivery_capability over adapter-local secret plumbing
   • references/delivery-seams.md owns the pre-post mechanics; apply them before posting: chat-backend format conversion (Slack mrkdwn baseline, or the path declared by format_rules_path) before posting raw CommonMark, message_size_limit paragraph-boundary splitting into numbered parts for every output role including thread_reply, and the JSON-line delivery_handle chaining contract when outputs chains a parent with thread_reply posts
   • before posting, run python3 "$SKILL_DIR/scripts/preflight_sources.py" --repo-root .; if any declared in_progress_sources entry is reported as unverified, surface the gap and require explicit user confirmation before delivery
8. Record the result after delivery or explicit draft finalization.
   • append a JSONL record so the next run can continue from the current head
   • for human-backend delivery, record a typed verification (see references/delivery-seams.md Post-Delivery Verification) before the record is appended; render closeout from the verification-carrying ledger (channel, status, thread/permalink, recorded head); reuse the resolved delivery target on retry; include external-source identity when drafting from a Slack thread, doc, or gathered artifact, per ../../shared/references/closeout-discipline.md

Output Shape

The result should usually include:

• Scope
• Audience
• Reader Value
• Draft
• Delivery Plan
• Recorded Head

Guardrails

• Delivery is gated, drafting is not: never block a draft on a missing backend, and never let anything leave the draft until it is user-confirmed, format- and size-correct for the backend, and any required repo helper or permission is disclosed first. The Workflow steps and references/draft-shape.md / references/delivery-seams.md own the per-step enforcement the guardrails would otherwise restate (no invented audience tags, value-over-mechanism headline, inline draft, CommonMark conversion, message_size_limit split).

References

• references/adapter-contract.md
• references/draft-shape.md
• references/delivery-seams.md
• references/audience-policy.md
• references/large-window-fanout.md
• ../../shared/references/closeout-discipline.md
• <repo-root>/scripts/collect_commits.py
• <repo-root>/scripts/infer_audience_tags.py
• <repo-root>/scripts/preflight_sources.py
• <repo-root>/scripts/record_announcement.py