katra

Files (1)

• SKILL.md

SKILL.md (first lines)

# katra

Keep a living dev log while you work, using the `katra` CLI (or the
`katra-mcp` MCP tools, if connected). The log is markdown entries with embedded
rich components, served as a live page and committed alongside the code.

The harness-neutral workflow is the public contract:
<https://craigjmidwinter.github.io/katra/workflow>. This skill is a Claude Code
delivery mechanism for the same task/epic/spec/entry/decision/stamp loop; it
does not define behavior unavailable to a plain CLI or another coding harness.

## The model (read this first)

- A katra lives in `katra/` at the repo root: `entries/` (one markdown file per
  post) + `media/` + `config.yml`. Run `katra list` to see if one exists; if not,
  `katra init`.
- **A draft is an entry with no commit hash.** It renders in the "In Progress"
  panel immediately — there is no scratch file and no promote step. The draft is
  the running post; you *stamp* it at commit time (hash + diffstat) and it drops
  into the log. Nothing can get stuck.

## Specs come before drafts

Before starting a task, check whether it is `specced`
(`katra task list --status specced`). That means a design is already
committed — its `spec:` frontmatter is a node slug in the katra, or a path
relative to the repo root. Read that file before writing any code; it exists
so you do not have to re-derive intent from a conversation that will not be
there next session.

If you are the one writing the design, not just building from one already
committed, and the task deserves it: write it (a decision, an article, or any
other markdown), then attach it —

```
katra task spec <task-slug> <ref>
```

— and commit the artifact plus task pointer as one planning change. This moves
the task `todo`/empty → `specced` and leaves a further-along status alone. Then
`katra task start <task-slug>` and implement from the committed spec.
Keep logging entries as you go, the same as any other work — and let them say
where the build diverged from the plan and why. That comparison is what makes
the entry worth more than the spec alone.

## You are writing a post, not a report

This is the part that goes wrong. Entries drift into flat technical documents —
a wall of prose that reads like a handoff note to the next agent — and a log of
those is one nobody, including you in a month, ever reads.

Claude Code project-memory may already capture the play-by-play, and Katra's
optional Claude adapter can offer that memory for deliberate authoring. It
never copies memory into the public log automatically. In Claude sessions,
don't re-type the transcript; in every harness, explicitly append the reasoning
worth publishing. Spend your effort on the two things a transcript can't hold:

- **Show the thing.** Screenshots, renders, before/after sliders, diagrams,
  charts. A single capture is worth paragraphs.
- **The reasoning.** The decision and the *why*, the alternative you rejected,
  what broke first. That's the signal memory paraphrases away.

Write it the way you'd write it up for someone who wasn't there:

- **Open with the stakes, not the filename.** "The HUD was eating the city" beats
  "Implemented WorldHUD.cs changes in-place."
- **Name the thing you rejected**, and why it lost. A post with no discarded
  alternative reads as though the answer was obvious, which it wasn't.
- **Land it.** End on what's now true and what's still shaky — a `warning` block
  for the parts that need a device, a person, or a rerun to confirm.

Anti-patterns, all observed in real katras:

- Addressing the next agent instead of a reader ("Integrator notes: wire X after
  Y", "Do NOT trigger a full compile"). Put coordination in the task/memory; the
  entry is for the reader.
- Closing on tooling receipts ("Validated clean via ValidateScript: 0
  diagnostics"). Evidence is good — bury it mid-post, don't end on it.
- Invariant checklists and spec-dumps as the *body*. Summarize the guarantee in
  a sentence; link or fold the exhaustive list into a collapsible tail if you
  must keep it.
- An entry with no visual at all (see below).

## Every entry ships at least one visual

Treat a draft with zero visuals as unfinished. If you're about to stamp one, stop
and ask what could be *shown* instead of described. In order of preference:

1. **It has a UI, a render, or a scene** → `katra capture` a screenshot or gif.
   Changed something visible? `katra compare before.png after.png`.
2. **It generates or transforms structured output** — a map, a graph, a layout, a
   schedule, a parse tree → render one and capture it. A map generator's post
   should contain a picture of a map.
3. **It has numbers** — frame times, token counts, latencies, file sizes, pass
   rates, before/after benchmarks → chart them (recipe below).
4. **It's pure architecture** → a diagram. A small hand-authored SVG or an HTML
   figure showing the pieces and the arrows beats three paragraphs describing the
   same boxes.

Only when none of those apply is a text-only entry the right call — and that's
rarer than it feels in the moment.

### Charts and diagrams: author HTML, then capture it

There's no chart component; you build the figure yourself and embed it, which
means any chart you can draw is available, not a fixed set of types.

Write a **self-contained** `.html` file to a scratch path, then capture it —
`katra capture` recognizes `.html` and emits an `embed` block automatically:

```
katra capture /tmp/frame-times.html --caption "Frame time vs district count, Quest 3 vs Editor"
```

Rules for the HTML, because it renders inside a sandboxed iframe:

- **No external requests.** No CDN scripts, no web fonts, no remote images.
  Inline everything; embed images as `data:` URIs. A `<script>` tag with inline
  JS is fine, but plain inline SVG is usually less work and always renders.

From craigjmidwinter/katra, MIT.

More from craigjmidwinter/katra