Lythoskill Project Scribe

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) → write to that carrier, not scribe
  └── No carrier → self-assess: does the next agent need to know this?
        ├── Yes → scribe
        └── No → don't write it

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

Pre-Handoff Checklist (mandatory before writing)

# 1. Git state — snapshot LAST: after any deck link/refresh/release step,
#    immediately before writing (a later link can silently dirty the tree)
git status
git log --oneline -5
# 2. Cortex state (if cortex is active)
bunx @lythos/project-cortex@{{PACKAGE_VERSION}} list
# 3. Session recall — ask yourself:
#    - What did I modify but not commit?
#    - What pitfalls did I hit?
#    - What important decisions were made verbally?
#    - What temp files did I create and where?
#    - What would the next agent most likely misunderstand?
# 4. After drafting: run the ZK Review Gate (below) — before commit

Template Usage

Scribe produces two file types. Follow the templates — they encode the best-practice format that evolved from 100+ daily/weekly files.

Rule: Do not invent format. If the template has a section, include it. If a section is marked REQUIRED, it must be present even if empty (e.g., quests_paused: [] proves you checked, not forgot).

Core Operation: Write Daily File

Output goes to daily/YYYY-MM-DD.md. The first section must be ## Session Handoff. Human work logs follow after the handoff section.

# File location
daily/
├── 2026-04-23.md    # Yesterday's daily (contains handoff + work log)
├── 2026-04-24.md    # Today's daily
└── ...              # Flat date-based, no subdirectories

Multiple sessions on the same day: prepend a new ## Session Handoff section at the top of the file. The onboarding skill reads the first (most recent) handoff section.

Handoff Must Include Verification Commands

The handoff is not a snapshot — it's a snapshot plus instructions to verify freshness. Always include in ### 0. Verify Current State:

### 0. Verify Current State
git diff <handoff-commit> --stat    # Construct "from T0 to now"
git status --short                  # Real-time working tree
git log --oneline -3                # Confirm recent commits match

If the reader runs these and output diverges from the handoff, the handoff is stale. Real-time output takes precedence.

Resumption Items: What + Why + Done + Raw Ref

Items the next agent must ACT on carry a stricter contract than narrative sections. Applies to four categories: half-done work, stuck, pending decision (ADR-worthy or not), and every Next Steps entry.

Each item answers four things:

No raw ref → no item. An item you cannot point at is a wish, not a handoff entry (mirrors cortex's "no source → no rule" — false confidence is worse than empty space).

Category-specific additions:

• Stuck: blocker as fact (exact error text / missing input) + what was already tried (one line + ref) + the cheapest next probe.
• Pending decision: the decision question + options one line each + what input unblocks it (who/what is missing). File the ADR, or link the existing id.

Rationale: the reader is an agent under onboarding time pressure with zero conversation context. What/Why/Done lets it verify completion without guessing intent; the raw ref lets it jump to ground truth instead of re-deriving the search path. "Continue testing" fails because it re-exports the derivation cost to the reader. The contract is also the anti-jargon bar: a writer in a hurry produces telegraphic fragments that decode to nothing for a zero-context reader; forcing What/Why/Done + ref per item forces complete, checkable sentences at write time.

This contract is the handoff-scope instance of the project's 5W1H reporting rule (AGENTS.md §3 — What / Why / Where / When / Who / How; scribe's Done ≈ When + How). One convention, two carriers: cortex applies it to review and status reports, scribe to every resumption item. Same two hard bars — no private vocabulary the reader cannot resolve from the repo or the glossary, and any verdict word (score, gate, severity) must define its criteria in the same file. An undefined scale cannot be disagreed with, so it is not a report.

Write sentences like these, not telegraphic fragments. The ❌ samples below are synthesized typical shorthand (any user's, not a specific person's words). The writer acts as secretary, not stenographer: humans abbreviate by nature when speaking fast — decode the shorthand into these sentences; never transcribe the fragment as-is.

ZK Review Gate (mandatory before commit)

The handoff's irreplaceable content — resume pointers ("agent-0 still holds the four-round context, don't open a fresh session for review"), temp artifacts, colloquial context — is exactly what a session-internal author writes worst: it is the most session-specific and the most likely to come out as unresolvable jargon (curse of knowledge). The play-by-play sections need no such care — cortex task cards + git history already carry them. So before commit the handoff gets a zero-knowledge pass, weighted at the top:

1. Draft the handoff (with ### 0. Verify Current State) and write it after user confirmation (Gotchas: show diff first).
2. Spawn a fresh ZK reviewer — pass-by-reference: the handoff file path, the AGENTS.md path, and the glossary path cortex/wiki/04-ssot/glossary.md. Never paste content.
3. Charter the reviewer accordingly — this goes into the spawn prompt: effort goes on the resume pointers (the **Resume** field in ### 0. Verify Current State) and the Temp Artifacts section — not on task state or history.
4. Fix every unresolved item on the spot, then commit.
   • Anti-bloat: a fix = one-sentence gloss + a pointer, bounded by the Value Boundary above — a fix restores what ls/git log cannot recover, it never adds what they can. Never dump transcript into the handoff — reading cost kills recall in reverse. A term that needs a paragraph belongs in the glossary, not expanded here.
   • Recurring jargon → deposit a row in the glossary (with source); one-off jargon → gloss in place.
5. ZK agents are sensors, not bosses (AGENTS.md) — you judge each finding.

Methodology + gap-processing rules: packages/lythoskill-project-cortex/skill/references/zk-review.md.

Pitfall Recording

When the user says "hit a bug" or "踩坑了" ("hit a pitfall"), immediately record:

### Pitfall: <short description>
- **Wrong approach**: what was tried
- **Symptom**: error message or behavior
- **Fix**: what actually worked
- **Root cause**: why the wrong path seemed right
- **Time wasted**: X minutes

Record Then Continue

Recording is a checkpoint, not a termination signal.

Agents must not infer "I wrote the daily file → my job is done." The user may ask you to record a pitfall at turn 5 and then continue debugging at turn 6.

Trigger phrases: "踩坑了" ("hit a pitfall") → record pitfall, keep debugging; "记录一下这个决定" ("record this decision") → write to daily, continue the task; "先记一下进度" ("jot down progress first") → checkpoint, continue.

Default assumption: record then continue. Only stop when the user explicitly confirms (e.g., "session ending", "LGTM", "先到这里" "let's stop here").

Gotchas

Show diff before writing. Always present the handoff content to the user for confirmation before writing to the daily file. Prevents hallucinated state from being persisted. Daily file = handoff + log. Do not create a separate HANDOFF.md. The daily file is the single source of truth. The onboarding skill reads from it directly. Diff artifacts ≠ working tree. If you generated code in a diff artifact during the conversation but haven't written it to disk, explicitly warn in the handoff: "⚠️ The following changes are in conversation artifacts only, not on disk." Cortex is optional. If the project uses cortex, read active tasks/epics during the pre-handoff check. If not, skip — scribe works independently.

Supporting References