lythoskill-project-scribe

Files (5)

• SKILL.md
• automation-triggers.md · references/
• cqrs-architecture.md · references/
• daily-template.md · references/
• weekly-template.md · references/

SKILL.md (first lines)

# Project Scribe
> Write what `ls` + `cat` + `git log` cannot recover. Skip everything else.

## Trigger: save discipline, not session-end

The intent is the old **save-to-disk discipline**: save constantly, because
a power cut can hit at any moment. For an agent the power cut is
compaction / crash / context loss: it can hit mid-task with no warning, and
only git-tracked, already-written files survive it. Scribe = save game; the
daily file is the save slot.

The reliable save anchor is a **batch of commits landing** — scribe right
after, while facts are fresh. A session cannot judge its own remaining
context; "write the handoff when the session feels done" is unreliable and
produces rushed, telegraphic output. Anchor to the commit, not the mood.

`## Session Handoff` names the artifact the NEXT session reads, not the
moment you write it. One session saves any number of times; saving says
nothing about this session ending (record-then-continue is the default,
see below).

## Value Boundary

**Scribe = session context dump for things WITHOUT structured carriers.**

```
What came out of this conversation?
  ├── Has a structured carrier (task/ADR/epic/experiment/wiki) → write
  │   to that carrier, not scribe prose — AND give the batch one Batch
  │   Index line (below)
  └── No carrier → self-assess: does the next agent need to know this?
        ├── Yes → scribe
        └── No → don't write it
```

| File exploration recovers (~70%) | Scribe must dump (~30%) |
|----------------------------------|------------------------|
| Project structure, tech stack | Pitfalls from this session |
| skill-deck.toml content | True working-tree state (prevents hallucination) |
| cortex/ tasks and epics | Why we chose A not B (not ADR-worthy but still important) |
| git log history | Specific next steps (not "test it") |
| README, docs | Temp artifacts: location + purpose |
| git diff (code changes) | Uncommitted modifications and their intent |
| | Meta-observations that emerge mid-conversation |

If the next agent can find it via `ls`, `cat`, or `git log` — don't repeat it.

### Batch Index: carriers get a line, not prose

The boundary above governs **prose, not presence**. A batch whose content
fully lives in carriers (task card + ADR + commits + demo artifacts) still
gets
exactly one line in the handoff's `### Batch Index` — because onboarding
reads the handoff first, and without that line the batch is invisible: the
carrier holds the content, but nothing tells the next agent the batch exists
or when its carrier is worth opening. Production-side completeness is
exactly what makes consumption-side absence fatal — the better a batch is
governed, the more completely it vanishes from the session narrative without
this rule. (Downstream incident: a five-carrier batch in another project
left zero trace in the handoff; the next session had to archaeologize what
the daily never said.)

**Highest-risk carriers — index these on sight.** The absence is most
fatal for batches whose carriers are quiet by nature: **experiments**
(result directories that exist on disk but are never announced) and
**research/wiki pages** (pages sitting in the tree that nobody opens).
Code batches leave diffs, trails, and review noise; experiment and wiki
batches leave files that look like background. A session that produced
either gets its index line without debate — for quiet carriers, the
`read when` trigger is the only door to the work. The paths are project
conventions, not part of the rule: name YOUR project's experiment dirs and
wiki (this repo's instances: `playground/`, `runs/`, `cortex/wiki/` —
cortex is optional, a wiki dir is whatever this project uses).

Coverage rule: **every batch that has progressed since the last handoff gets
≥1 line** — whether or not its commits have landed yet. A batch = work
toward one outcome, not each commit. Check coverage mechanically — no
relying on session recall:

```bash
git log <last-handoff-HEAD>..HEAD --oneline
```

`<last-handoff-HEAD>` = the HEAD recorded in `### 0. Verify Current State`
of the **immediately preceding handoff** — the handoff section directly
below if you're prepending to today's file, else the first handoff of the
latest earlier daily file. No prior handoff → index since session start.
"The last handoff" is never a recall question: the filename date pattern
makes it visible — the newest `daily/YYYY-MM-DD.md` (filter dated names
before sorting), first `## Session Handoff` section in it; on prepend days,
the section directly below that one. (The HEAD you record in `### 0` today
is the next handoff's `<last-handoff-HEAD>` — the chain is the freshness
contract.)

Group the commits into batches; each batch names itself in the index.
Meta-commits are not batch-bearing and need no line: the daily-file commit
itself, post-commit-hook trailer follow-ups, pure lockfile/version churn. A
batch whose carriers exist but are **not yet committed** still gets its line
— refs point at the working-tree paths, marked `uncommitted`. Write `none`
only when no batch progressed at all.

Line shape — one line per batch; details stay in the carrier, never
summarized here:

```markdown
- **<batch name, 3-8 words>** — refs: TASK-xxx, ADR-xxx, @a1b2c3 — read when: <trigger>
```

`refs` = **all carrier IDs the batch touched (TASK/ADR/EPIC/wiki) + one
representative commit hash** — not every commit in the range. If a "batch"
needs two lines to name its outcomes, it is two batches.

`read when` is a **condition, not a summary** — "when the spec-vs-registered
flow diverges again", not "about the spec-flow batch". It answers the
reader's actual question: *I have this problem now — is there prior art,
and where?*
## Pre-Handoff Checklist (mandatory before writing)
```bash
# 1. Git state — snapshot LAST: after any deck link/refresh/release step,

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill