transcript-promotion

Transcript Promotion

Lift substantive inline content from the ephemeral transcript surface to the durable plan-file surface. Extract verbatim, prepend canonical frontmatter, propagate to chezmoi-source so the autoCommit+autoPush cascade fires, and register the artifact in any series it belongs to.

Why this exists

Sessions produce two kinds of substantive output:

1. File-bound — code edits, plan writes, IRF rows, memory entries. These propagate via Write|Edit tool hooks and naturally land on disk + remote.
2. Conversation-bound — dense reference deliveries, "engine logs", inline analyses, multi-section walkthroughs the user reads and reacts to in-chat.

Class (2) is durable in the JSONL transcript but invisible to ~/.claude/plans/INDEX.md, MEMORY.md, and the chezmoi-source mirror. The transcript is on disk, but the content is buried inside conversation text rather than promoted to a discoverable artifact. A future session reading the plans index sees nothing; the content effectively dies with context exit.

Genesis case (2026-05-20 session 9cb55c4d): three engine reference docs (LOG #1 statusLine, LOG #2 Hooks, LOG #3 Subagents) delivered inline. LOG #1 was persisted to a plan file by the same session. LOG #2 and #3 were marked "inline only — not file-persisted" in the closeout. Two days later (2026-05-22), under explicit prompt to verify durability, they were extracted from the JSONL and promoted via the protocol now codified in this skill.

Pairs with artifact-resurfacing as the inverse motion:

• artifact-resurfacing — citation points at nothing → reconcile the citation
• transcript-promotion — content exists with no citation → mint the citation

Both clear different sides of the same drift entropy.

Authority boundary (read first)

This skill is propagate-with-explicit-cascade for routine plan files, propose-not-apply for any constitutional surface.

• Plan files in ~/.claude/plans/ may be written directly; the chezmoi auto-sync hook fails for bash-redirect file creation, so the skill manually runs chezmoi add to bring source into sync and let autoCommit+autoPush fire. This is the documented chezmoi gotcha protocol from home-scope CLAUDE.md.
• CLAUDE.md, MEMORY.md, governance-rules.json, registry-v2.json, any seed.yaml, INST-INDEX-RERUM-FACIENDARUM.md — never written by this skill. If transcript content names changes to a constitutional surface, defer to the conductor.
• Cross-organ push to a public ORGANVM main branch requires explicit per-session push authorization. This skill commits but surfaces the push decision to the user when the target is a public-main branch.

Discovery → propose-frontmatter → propagate via chezmoi → register in series. Four phases, last two require user-derived authorization for non-routine targets.

When to use

• "Persist LOG #N to ~/.claude/plans/..."
• "Promote this inline reference to a plan file"
• "Make sure this survives context exit"
• "Save the engine log to disk"
• "Another log for the engine" (canonically followed by promotion in the same or next turn)
• Closeout walks back and finds ≥1 deliverable flagged "inline only"
• User asks "all unique data survives present context upon exit?" and the audit table shows artifacts with JSONL ✓ / plan file ✗
• A qa-audit of substantive deliverables finds class-(2) content with no on-disk citation

Four-phase protocol

Phase 1 — Extract (verbatim from the JSONL)

The JSONL transcript is the canonical source. Extract assistant text and locate the content boundary by section anchor (preferred) or line range (fallback).

bash scripts/extract-anchor-range.sh \
  --jsonl ~/.claude/projects/<scope>/<project-uuid>.jsonl \
  --start-anchor "^## LOG #2 — Hooks: Complete Reference" \
  --end-anchor "^## LOG #3 — Subagents: Complete Reference" \
  --output "$CLAUDE_JOB_DIR/extracted-log-2.md"

The script:

1. Filters assistant-type entries, concatenates .message.content[].text via jq.
2. Greps for the start anchor; bails with non-zero exit if not found (Universal Rule #12: verify before acting).
3. Greps for the end anchor; if absent, falls back to EOF.
4. Writes verbatim slice to $CLAUDE_JOB_DIR (background-session safe path).

Verbatim is non-negotiable. The transcript is the canonical version; re-authoring breaks the audit trail. Future drift-reconciliation by artifact-resurfacing should be able to grep the transcript for the same string and find it.

Phase 2 — Frontmatter (canonical, mirrors LOG #1 precedent)

Prepend the standard frontmatter block. Required fields:

---
title: <Subject> — <Reference-Type>
date: <YYYY-MM-DD of original delivery, not promotion date>
scope: home (~/.claude/plans/) | repo (<path>) | organ (<organ>)
status: reference
extracted_from: <jsonl-path>
extraction_date: <YYYY-MM-DD of promotion>
related:
  - <sibling-artifact-paths>
  - <upstream-doc-urls>
  - <series-siblings if part of a series>
---

# <Title>

## Why this file exists

<One-paragraph rationale: who delivered it, when, why it's being promoted now, what precedent it mirrors.>

---

<verbatim extracted content>

For series content (LOG #N), the related: block includes all siblings in the series, allowing later members to grep-discover earlier ones via the cross-link.

python3 scripts/propose-frontmatter.py \
  --title "Claude Code Hooks — Complete Options Reference" \
  --date 2026-05-20 \
  --scope home \
  --extracted-from ~/.claude/projects/-Users-4jp/9cb55c4d-3191-4b61-a8e8-192e4710affb.jsonl \
  --series engine-log \
  --series-index 2 \
  --body "$CLAUDE_JOB_DIR/extracted-log-2.md" \
  --output ~/.claude/plans/2026-05-20-hooks-options-reference.md

The script enforces the schema, prepends frontmatter, prints the resulting file path. Slug convention: YYYY-MM-DD-<topic-slug>-options-reference.md for engine-log series; YYYY-MM-DD-<topic-slug>.md for one-offs.

Phase 3 — Propagate (the chezmoi gotcha workaround)

Bash-redirect / cat > file creation bypasses the PostToolUse Write|Edit hook that fires domus-memory-sync. The runtime file exists but never reaches chezmoi-source or remote. This is a documented silent-failure class — see references/known-promotion-pitfalls.md.

Manual recovery is the chezmoi-documented protocol:

bash scripts/propagate-via-chezmoi.sh ~/.claude/plans/2026-05-20-hooks-options-reference.md ~/.claude/plans/2026-05-20-subagents-options-reference.md

The script:

1. Runs chezmoi add <runtime-paths> to copy runtime → source.
2. autoCommit+autoPush fires from chezmoi config (no separate git push needed for the chezmoi-source repo).
3. Verifies parity: git -C <chezmoi-source> log @{u}..HEAD --oneline should be empty.
4. If parity check fails, surfaces the divergence to the user and stops.

For non-chezmoi-managed plan files (per-repo .claude/plans/), the script falls back to git add + manual-commit-and-push surfacing.

Phase 4 — Register (in any applicable series)

A solitary promoted artifact is durable. A series member needs registration so future members can discover the canonical series register.

For the engine-log series (LOG #N pattern), update references/engine-log-series.md in this skill with the new entry:

| N | YYYY-MM-DD | Topic | Slug | Genesis session |
|---|---|---|---|---|
| 1 | 2026-05-20 | statusLine | 2026-05-20-statusline-options-reference | 9cb55c4d |
| 2 | 2026-05-20 | Hooks | 2026-05-20-hooks-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| 3 | 2026-05-20 | Subagents | 2026-05-20-subagents-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| ... | ... | ... | ... | ... |

For ad-hoc one-off promotions (not part of a series), no register update needed — the artifact's frontmatter related: cross-links suffice.

If promotion exposes a new silent-failure class (e.g., a new way auto-sync gets bypassed), append a row to references/known-promotion-pitfalls.md and surface an IRF row proposal. The skill's prevention surface grows monotonically.

What this skill explicitly does NOT do

• Edit CLAUDE.md, MEMORY.md, governance-rules.json, registry-v2.json, any seed.yaml, or INST-INDEX-RERUM-FACIENDARUM.md directly. IRF row proposals surface to the user.
• Re-author or paraphrase transcript content (verbatim only — see Phase 1).
• Promote content that lives in <system-reminder> blocks or <command-message> blocks (those are infrastructure, not deliverable content).
• Cross-organ push to public ORGANVM main without explicit per-session push authorization.
• Run as a background daemon, cron, or LaunchAgent (Universal Rule #9 — HARD RULE).
• Batch-promote without per-artifact frontmatter (each promoted file is independently citable).
• Auto-fire on every closeout (closeout walks back and suggests; user invokes this skill).

Scripts

• scripts/extract-anchor-range.sh — anchor-bounded transcript extractor; verifies anchors exist (Rule #12) before slicing.
• scripts/propose-frontmatter.py — frontmatter generator with schema validation and series-aware related: linking.
• scripts/propagate-via-chezmoi.sh — chezmoi-add wrapper with parity verification; surfaces non-chezmoi targets for manual push.

References

• references/engine-log-series.md — register of the LOG #N series; living document, append-only.
• references/known-promotion-pitfalls.md — silent-failure classes encountered during promotion; append-only.
• references/composition-with-closeout.md — how this skill chains with /closeout (closeout flags candidates; this skill executes the promotion).
• references/composition-with-artifact-resurfacing.md — the inverse-motion pair; when to invoke which.

Examples

• examples/2026-05-20-engine-logs-2-and-3.md — the genesis case: LOG #2 (Hooks) and LOG #3 (Subagents) extracted from JSONL 9cb55c4d and promoted to plan files in session beeff468 (2026-05-22). Full protocol trace including the silent-failure discovery for bash-redirect bypass of auto-sync.

Anti-patterns

• Re-authoring transcript content from memory (Phase 1 must be verbatim grep+slice; if anchors don't match, fix anchors or use line-range fallback)
• Promoting <system-reminder> infrastructure as if it were substantive content
• Skipping Phase 3 because "the file is on disk already" (without chezmoi propagation, Universal Rule #2 is unmet)
• Promoting before the closeout has flagged candidates (close out first, then promote what closeout surfaces; reverses the dependency)
• Treating series register as ceremony — it's the discovery surface for the next session
• Inventing the extracted_from: field when the transcript has rotated out (if the JSONL is gone, the canonical source is gone; surface this rather than backfill)
• Cross-organ push to public main without explicit per-session authorization (surface the push decision)

Universal rules this skill is built around

• Universal Rule #2 — Nothing local only. Phase 3 is the literal operationalization: runtime file → chezmoi-source → remote.
• Universal Rule #6 — Fix bases, not outputs. Phase 4's series register is the base for "next LOG"; codification grows the prevention surface, not just the symptom fix.
• Universal Rule #8 — Plans are artifacts. Promoted content becomes a plan file under the standard ~/.claude/plans/YYYY-MM-DD-{slug}.md discipline.
• Universal Rule #9 — No LaunchAgents. Promotion is on-demand only.
• Universal Rule #12 — Memory is hypothesis. Phase 1 requires anchor-verification before slicing; never trust a remembered anchor without grep-verifying it in the current transcript.

Composition with other tools/ skills

Skill	Role	When
closeout	discovers candidates	end of session; flags "inline only" deliverables
transcript-promotion (this)	executes the promotion	when user invokes or when closeout candidates need durability
artifact-resurfacing	inverse motion	when promoted content's citation later goes stale and needs reconciliation
cross-agent-handoff	carries the register	promotion register travels in the handoff to the next session
qa-audit	verifies promotion success	after promotion, audits whether all candidates actually landed on disk + remote
consolidate-memory	indexes new artifacts	promoted plan files referenced from memory via [[name]] links get curated here

Why "ongoing unfurling expansion"

The skill is designed to grow monotonically without ever overwriting itself:

• Series register (references/engine-log-series.md) — append-only; LOG #N grows to N+1, N+2, ad infinitum.
• Pitfall register (references/known-promotion-pitfalls.md) — append-only; each new silent-failure class discovered during promotion gets a row.
• Examples — append-only; each genesis case becomes a worked example for future invocations.
• Scripts — versioned; new extraction patterns (anchor regex variants, multi-section windowing) extend rather than replace the base extractor.

The skill ages well because every new use case enriches the prevention surface. Drift is detected, codified, and surfaced — not papered over.