---
name: narrative
description: "Use when a repo's source-of-truth docs and current product or project story need to be aligned together. Tighten the durable narrative first, then derive one audience-neutral brief skeleton when a compressed handoff artifact would help."
---

# Narrative

Use this when the repo already has a product, project, or operating story, but
that story needs to be created, realigned, or compressed into one portable
brief skeleton without leaving the durable docs behind.

`narrative` is one public concept:

- map the current source-of-truth surface
- surface contradictions, stale assumptions, and missing decisions
- rewrite the durable docs so the current story is honest in one place
- derive one audience-neutral brief skeleton from that aligned story when
  useful

Borrow Barbara Minto-style structure when compressing a repo story: lead with
the governing idea, group supporting points cleanly, and order the document so
the reader can recover the argument without reverse-engineering it.

If the idea is still under-shaped, use `ideation` first. If the docs are
already aligned and the user mainly wants audience adaptation or delivery-ready
wording, use `announcement`.
If the repo has little or no durable truth surface yet, use `setup` to
bootstrap that surface before treating the task as narrative alignment.
If a high-leverage truth surface lacks a repo-specific narrative contract, shape
or scaffold the adapter before rewriting; fallback inference is a repo-level
`block` seam, not a best-effort warning.

## Bootstrap

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

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

Default durable artifact:

- `<repo-root>/charness-artifacts/narrative/latest.md`

What you get after one run:

- one aligned truth-surface artifact anchored to the repo's durable docs
- one audience-neutral brief skeleton that later delivery work can adapt

If the repo would benefit from an explicit truth surface, scaffold an adapter:

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

When rendered Markdown proof matters for README, landing pages, or durable
spec prose, surface the supported runtime recommendation before pretending raw
source review is enough:

```bash
python3 "$SKILL_DIR/scripts/list_tool_recommendations.py" --repo-root .
```

Then inspect current state:

```bash
sed -n '1,220p' charness-artifacts/narrative/latest.md 2>/dev/null || true
python3 "$SKILL_DIR/scripts/map_sources.py" --repo-root .
git status --short
```

## Workflow

1. Restate the narrative goal.
   - bootstrap a new durable story surface
   - realign stale source-of-truth docs
   - realign docs and also produce an audience-neutral brief skeleton
   - state the primary reader context before rewriting a first-touch surface
2. Map the current truth surface.
   - read the source documents before inventing a fresh summary
   - review adapter fitness before trusting its source set, mutable documents,
     and special entrypoints
   - for README, landing, or operator-doc work, use the adapter repair loop:
     review, edit, rerun until no `block` findings remain, then fill or
     explicitly waive thin-adapter `warn`s before drafting
   - surface stale-git or stale-context risk before editing when freshness is
     ambiguous
   - shape the truth-surface contract before rewriting first-touch docs when the adapter is missing or thin
   - repair or downgrade missing, volatile, internal, archived, or handoff inputs
   - if the source map is effectively empty or only placeholder-level, stop and
     recommend `setup` rather than pretending there is already a narrative
     surface to align
3. Inventory intent before rewriting a high-leverage first-touch surface.
   - recover explicit intent from source docs, repo-local adapter guidance, and
     user-confirmed direction from the current thread
   - classify high-signal prior blocks as preserved, moved, compressed, or
     intentionally deleted
   - treat preserved meaning as the contract; headings and section order are
     flexible
4. Run the landing rewrite loop when the target is a high-leverage first-touch
   surface.
   - use `references/landing-rewrite-loop.md` for comparables, intent inventory,
     claim audit, compression metric, reader critique, and carry-forward review
   - if the work is really a cross-repo issue or proposal packet, use
     `references/cross-repo-issue-shaping.md` so `why` and `what` stay ahead
     of `how`
   - when rendered preview matters, surface the repo-owned install/verify path
     for `glow` before accepting degraded raw-Markdown review
   - resolve research/source-truth tensions before editing
   - keep a claim-to-acceptance/spec matrix before calling the rewrite done
5. Tighten the durable story first.
   - rewrite contradictions instead of layering parallel narratives
   - propagate user-confirmed direction changes into source-of-truth docs, not
     only into the brief
   - when the repo has multiple first-class use cases or the adapter declares
     `scenario_surfaces`, add short scenario blocks for the main use-case
     paths; use the relevant subset of `references/scenario-blocks.md` instead
     of forcing every slot
   - if the docs coin product-local jargon, define it inline at first use
     instead of sending the reader to a later glossary
   - when the repo is aligning around a non-trivial design decision, keep one
     short rejected-alternative or `Deliberately Not Doing` block in the
     durable docs instead of leaving that memory in chat or handoff only
   - for first-touch truth surfaces, run success criteria review with focuses:
     intended reader action, avoided misread, claim proof, durable next step
6. Derive the brief second.
   - keep it audience-neutral by default
   - prefer one self-contained compression layer that `announcement` can later
     adapt for a concrete audience, language, tone, or channel
   - when the repo adapter declares `brief_template`, use that ordered skeleton
     instead of inventing a new brief shape in session
7. Show the aligned edits, claim audit, compression metric, and brief draft
   before any delivery action.
   - include a short carry-forward note for user-stated intents that were
     preserved, challenged, or left unresolved
   - when the rewrite creates doc-code or generated-reference obligations,
     name the owning follow-up instead of hiding the gap in polished prose
   - when the realignment depends on an external originating context (Slack
     thread, Notion page, Drive file, gathered artifact, or web URL),
     include canonical source identity per
     `../../shared/references/closeout-discipline.md`
8. Hand off to `announcement` only when the user explicitly wants human-facing
   adaptation or backend delivery after the narrative itself is aligned.

## Output Shape

The result should usually include `Source Map`, `Narrative Drift`, `Updated Truth`,
`Brief`, `Claim Audit`, `Compression`, `Carry-Forward`, `Open Questions`, and `Next Step`.

## Guardrails

- Do not use `narrative` as a substitute for `ideation` when the concept is
  still vague or upstream decisions are genuinely unresolved.
- Do not leave user-confirmed direction changes only in an ephemeral brief.
- Do not let volatile handoff, internal, or archived notes become default
  README truth just because an adapter listed them or git freshness is unclear.
- Do not trust a repo-local adapter blindly; review whether it can produce the
  requested reader-facing outcome before using it as the rewrite contract.
- Do not collapse durable truth docs and audience-specific briefs when their
  lifecycles differ.
- Do not mistake a cleaner outline for success when preserved intent was lost.
- Do not strip away the short "why not this other path" note when that note is
  what keeps the next reader from reopening the same design debate.
- Do not let audience, language, tone, or channel adaptation pull `narrative`
  into `announcement` territory.
- Do not let repo-local adapter hints harden into a global README template for
  every repo.
- Keep the brief portable enough that later audience adaptation does not require
  re-aligning the durable truth from scratch.
- If delivery backend execution is the only remaining task, prefer
  `announcement` rather than growing `narrative` into a transport skill.

## References

- `references/adapter-contract.md`
- `references/source-map.md`
- `references/brief-shape.md`
- `references/scenario-blocks.md`
- `references/landing-rewrite-loop.md`
- `references/cross-repo-issue-shaping.md`
- `../../shared/references/agent-assessment-invariant.md`
- `../../shared/references/closeout-discipline.md`
- `../../shared/references/success-criteria-review.md`
- `<repo-root>/scripts/map_sources.py`
- `<repo-root>/scripts/review_adapter.py`