ax:narrate - write the session's story as a structured narration
You were there. This skill turns YOUR OWN memory of the session into a
reviewable artifact: 3-7 stops in reading-flow order, each anchored to
real evidence - code hunks, turn numbers, user quotes, failures. The
point is to capture what a PR diff never shows: the corrections, the
dead ends, the recoveries.
The artifact validates against SessionNarration in
apps/studio/src/routes/narration-types.ts and renders in ax studio.
Step 1 - identify the session
- Preferred:
ax sessions here --days=1 --json and pick the current
session's id (the one matching this conversation). Use the short id.
- If
ax is unavailable or the session isn't ingested yet, derive a
slug: <repo>-<YYYYMMDD-HHmm>. Note in meta that turn seqs are
best-effort ordinals in that case.
- If available,
ax sessions show <id> --json gives you the real turn
seqs to anchor against. Prefer real seqs over guesses.
Step 2 - reconstruct the story from your own context
Re-read the conversation in your head before writing anything:
- What did the user originally ask for? (intent)
- What existed before, what exists now? (before/after)
- Where did the user redirect or correct you? EVERY one of these
becomes a
correction anchor. No exceptions.
- Which tool failures actually mattered (changed your approach, cost
real time, forced a workaround)? Each becomes a
tool_failure
anchor. Skip trivial retries that changed nothing.
- Which attempts were abandoned? They get a stop or at least a
turn anchor - abandonment is part of the story.
Step 3 - choose 3-7 stops, in reading-flow order
A stop is a LOGICAL unit of change, not a file. If three files changed
for one reason, that is ONE stop with several anchors. Order rules
(stolen from the code-tour playbook because they work):
- Entry point first: the change that, understood alone, unlocks the rest.
- Cause before effect: the correction comes before the code it caused.
- Definitions before consumers: types/schema stops before usage stops.
- Verification last: tests, typecheck, and the failures hit on the way.
- Combine trivial housekeeping into one final stop, or omit it.
Step 4 - write each stop
- title: short and friendly. "Call counts become a char diffstat",
not "Changes to files-touched.ts".
- gist: ONE sentence. Not two. A reader who reads nothing else must
get the stop from the gist. Conversational, the way you'd say it to
a colleague.
- detail: 2-4 sentences of markdown (paragraphs,
inline code,
bold). Say WHY the change looks the way it does; "we did X
instead of Y because Z" is exactly what the reader wants.
- transition: a short connective phrase to the next stop; empty
string
"" for the last stop.
- anchors: MUST be non-empty. An unanchored stop is an unsupported
claim. Anchor kinds:
| kind |
required fields |
use for |
file_hunk |
file, old_text, new_text, label, opt turn_seq |
a real code change |
code_state |
artifact, label, lang, code, opt turn_seq |
the evolving architecture snapshot |
turn |
turn_seq, label |
a plain moment in the transcript |
user_direction |
turn_seq, quote |
user steering (not correcting) |
correction |
turn_seq, quote, outcome |
user correcting course |
tool_failure |
turn_seq, tool, error_excerpt, recovery |
consequential failure |
term |
name, definition |
a domain term the story leans on |
Hard anchor rules
file_hunk carries VERBATIM old/new fragments from the actual edits
you made - copy the real text, never paraphrase code. Keep hunks
short (5-15 lines per side); pick the most telling fragment, not the
whole edit. old_text: null for pure insertions, new_text: null
for pure deletions. Never both null.
- Every user correction/redirect in the session gets a
correction
anchor with a verbatim (trimmed) quote and a concrete outcome -
what actually changed because of it.
- Every consequential tool failure gets a
tool_failure anchor with a
real error_excerpt and how you recovered (or "abandoned").
- Never fabricate turn seqs. Use
ax sessions show seqs when you have
them; otherwise count user turns from the start of the conversation
and say so in the detail.
code_state is the architecture spine of the narration: pick ONE
stable artifact id (e.g. "review-architecture") and restate the
FULL snapshot at each stop where the design moved - pseudo-code of
types/interfaces, how they compose, and the call stack (plan-style:
Caller -> Callee // note). Consecutive snapshots of the same
artifact animate token-by-token in studio, so KEEP shared lines
byte-identical between stops and let only the real delta differ - a
new method, a renamed shape, an added edge case. Use code_state
for the evolving design; use file_hunk for one-off code jumps
(those render as static before/after diffs, not motion).
Step 5 - emit the artifact
Write .ax/narrations/<session-id>.json (create the directory if
needed) with exactly this top-level shape:
{
"schema_version": 1,
"kind": "narration",
"meta": {
"session_id": "<id>",
"generated_at": "<ISO-8601 now>",
"generator": "skill",
"model": "<your model id>"
},
"title": "...",
"intent": "...",
"before": "...",
"after": "...",
"stops": [ { "title": "...", "gist": "...", "detail": "...", "transition": "...", "anchors": [ ... ] } ]
}
Before finishing, self-check against the validator's rules:
stops non-empty (3-7), every stop's anchors non-empty.
- Every gist is one sentence; every
correction has an outcome;
every tool_failure has a recovery; no file_hunk with both
sides null or empty.
- Strings are plain JSON strings (escape newlines in hunks as
\n).
Then tell the user where the file landed and give a 2-line summary of
the story you wrote. Do not paste the whole JSON into chat.
1---2name: ax-narrate3description: Write the agent-generated narration of the current session - the reviewable story of what changed, including what never reaches a PR (user corrections, abandoned attempts, tool failures). Triggers on "narrate this session", "summarize what changed", "write the session story", "narrate what we did", "session narration". Output is .ax/narrations/<session-id>.json for the ax studio narration view. Do NOT fire on "summarize this file" or generic recap questions answered inline - this skill writes a structured artifact.4role: verification5metadata:6 source: https://skillmd.com/skills/necmttn/ax-narrate7---89# ax:narrate - write the session's story as a structured narration1011You were there. This skill turns YOUR OWN memory of the session into a12reviewable artifact: 3-7 stops in reading-flow order, each anchored to13real evidence - code hunks, turn numbers, user quotes, failures. The14point is to capture what a PR diff never shows: the corrections, the15dead ends, the recoveries.1617The artifact validates against `SessionNarration` in18`apps/studio/src/routes/narration-types.ts` and renders in ax studio.1920## Step 1 - identify the session2122- Preferred: `ax sessions here --days=1 --json` and pick the current23 session's id (the one matching this conversation). Use the short id.24- If `ax` is unavailable or the session isn't ingested yet, derive a25 slug: `<repo>-<YYYYMMDD-HHmm>`. Note in `meta` that turn seqs are26 best-effort ordinals in that case.27- If available, `ax sessions show <id> --json` gives you the real turn28 seqs to anchor against. Prefer real seqs over guesses.2930## Step 2 - reconstruct the story from your own context3132Re-read the conversation in your head before writing anything:33341. What did the user originally ask for? (intent)352. What existed before, what exists now? (before/after)363. Where did the user redirect or correct you? EVERY one of these37 becomes a `correction` anchor. No exceptions.384. Which tool failures actually mattered (changed your approach, cost39 real time, forced a workaround)? Each becomes a `tool_failure`40 anchor. Skip trivial retries that changed nothing.415. Which attempts were abandoned? They get a stop or at least a42 `turn` anchor - abandonment is part of the story.4344## Step 3 - choose 3-7 stops, in reading-flow order4546A stop is a LOGICAL unit of change, not a file. If three files changed47for one reason, that is ONE stop with several anchors. Order rules48(stolen from the code-tour playbook because they work):4950- Entry point first: the change that, understood alone, unlocks the rest.51- Cause before effect: the correction comes before the code it caused.52- Definitions before consumers: types/schema stops before usage stops.53- Verification last: tests, typecheck, and the failures hit on the way.54- Combine trivial housekeeping into one final stop, or omit it.5556## Step 4 - write each stop5758- **title**: short and friendly. "Call counts become a char diffstat",59 not "Changes to files-touched.ts".60- **gist**: ONE sentence. Not two. A reader who reads nothing else must61 get the stop from the gist. Conversational, the way you'd say it to62 a colleague.63- **detail**: 2-4 sentences of markdown (paragraphs, `inline code`,64 **bold**). Say WHY the change looks the way it does; "we did X65 instead of Y because Z" is exactly what the reader wants.66- **transition**: a short connective phrase to the next stop; empty67 string `""` for the last stop.68- **anchors**: MUST be non-empty. An unanchored stop is an unsupported69 claim. Anchor kinds:7071| kind | required fields | use for |72|---|---|---|73| `file_hunk` | `file`, `old_text`, `new_text`, `label`, opt `turn_seq` | a real code change |74| `code_state` | `artifact`, `label`, `lang`, `code`, opt `turn_seq` | the evolving architecture snapshot |75| `turn` | `turn_seq`, `label` | a plain moment in the transcript |76| `user_direction` | `turn_seq`, `quote` | user steering (not correcting) |77| `correction` | `turn_seq`, `quote`, `outcome` | user correcting course |78| `tool_failure` | `turn_seq`, `tool`, `error_excerpt`, `recovery` | consequential failure |79| `term` | `name`, `definition` | a domain term the story leans on |8081### Hard anchor rules8283- `file_hunk` carries VERBATIM old/new fragments from the actual edits84 you made - copy the real text, never paraphrase code. Keep hunks85 short (5-15 lines per side); pick the most telling fragment, not the86 whole edit. `old_text: null` for pure insertions, `new_text: null`87 for pure deletions. Never both null.88- Every user correction/redirect in the session gets a `correction`89 anchor with a verbatim (trimmed) `quote` and a concrete `outcome` -90 what actually changed because of it.91- Every consequential tool failure gets a `tool_failure` anchor with a92 real `error_excerpt` and how you recovered (or `"abandoned"`).93- Never fabricate turn seqs. Use `ax sessions show` seqs when you have94 them; otherwise count user turns from the start of the conversation95 and say so in the detail.96- `code_state` is the architecture spine of the narration: pick ONE97 stable `artifact` id (e.g. `"review-architecture"`) and restate the98 FULL snapshot at each stop where the design moved - pseudo-code of99 types/interfaces, how they compose, and the call stack (plan-style:100 `Caller -> Callee // note`). Consecutive snapshots of the same101 artifact animate token-by-token in studio, so KEEP shared lines102 byte-identical between stops and let only the real delta differ - a103 new method, a renamed shape, an added edge case. Use `code_state`104 for the evolving design; use `file_hunk` for one-off code jumps105 (those render as static before/after diffs, not motion).106107## Step 5 - emit the artifact108109Write `.ax/narrations/<session-id>.json` (create the directory if110needed) with exactly this top-level shape:111112```json113{114 "schema_version": 1,115 "kind": "narration",116 "meta": {117 "session_id": "<id>",118 "generated_at": "<ISO-8601 now>",119 "generator": "skill",120 "model": "<your model id>"121 },122 "title": "...",123 "intent": "...",124 "before": "...",125 "after": "...",126 "stops": [ { "title": "...", "gist": "...", "detail": "...", "transition": "...", "anchors": [ ... ] } ]127}128```129130Before finishing, self-check against the validator's rules:131132- `stops` non-empty (3-7), every stop's `anchors` non-empty.133- Every gist is one sentence; every `correction` has an `outcome`;134 every `tool_failure` has a `recovery`; no `file_hunk` with both135 sides null or empty.136- Strings are plain JSON strings (escape newlines in hunks as `\n`).137138Then tell the user where the file landed and give a 2-line summary of139the story you wrote. Do not paste the whole JSON into chat.