narrative

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.

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:

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:

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

Then inspect current state:

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
   • name the reader or operator capability the durable story must make true
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 warns 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
   • separate capability claims from feature inventory before polishing the story
   • 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 per references/brief-shape.md, which owns the audience-neutral discipline and the what-to-avoid rules.
   • 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, Capability Claim, Updated Truth, Brief, Claim Audit, Compression, Carry-Forward, Open Questions, and Next Step.

Guardrails

• Do not leave user-confirmed direction changes only in an ephemeral brief.
• Trust the adapter and its listed sources only as far as they can produce the requested reader-facing outcome: volatile/internal/archived notes never become default README truth, and per-repo adapter hints never harden into a global template (references/adapter-contract.md owns the fuller trust failure modes).
• 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.
• Keep the brief portable enough that later audience adaptation does not require re-aligning the durable truth from scratch.

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