{{PACKAGE_VERSION}} to {{PACKAGE_VERSION}}

---

name: lythoskill-project-scribe

version: {{PACKAGE_VERSION}}

description: |

Session context dump. Self-assess what the conversation contains that has

NO other carrier (no task, no ADR, no epic) — pitfalls, working-tree anomalies,

why-we-chose-this, specific next steps — and write to daily/YYYY-MM-DD.md.

Things WITH structured carriers go to their carriers. Things WITHOUT

carriers but needed by the next agent go here. Forms CQRS write-side pair

with project-onboarding (read-side).

when_to_use: |

Record after a batch of commits lands — mid-session or at close, while

facts are fresh. Use when: user hits a pitfall, makes an important

decision, completes a milestone, asks to checkpoint, or says context is

getting long. Do NOT treat "record" as "stop working" — the section

name marks the next session's read artifact, not this session's end.

---

# 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

```

| 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.

## Pre-Handoff Checklist (mandatory before writing)

```bash

# 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.

| File type | Template | When to write |

|:---|:---|:---|

| **Daily** | [references/daily-template.md](./references/daily-template.md) | At session milestones or end |

| **Weekly** | [references/weekly-template.md](./references/weekly-template.md) | End of week (Sunday night) |

**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.

```bash

# 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`:

```markdown

### 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:

| Part | Question | Bar |

|------|----------|-----|

| **What** | What is the action | One concrete action, not a theme ("wire X into Y's stdout", not "finish the feature") |

| **Why** | Why do it | Cost of NOT doing it — the incident or drift it prevents |

| **Done** | What does done look like | Observable end state: command output, test count, filed ADR id — not "looks good" |

| **Raw ref** | Where to jump | `file:line`, TASK-/ADR-/EPIC-id, commit hash, or URL — zero re-derivation |

**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.

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.

| ❌ Telegram-style (the reader can't execute it) | ✅ Recommended (What + Why + Done + ref as one sentence) |

|---|---|

| "Next: kimi adapter 加固" ("harden the kimi adapter") | "Harden the kimi adapter probe (TASK-20260828212204402): probe times out under sandbox though `--version` passes; done = probe e2e green under CI-sim env, `env -u CLAUDE_CODE_SSE_PORT bun --filter='*' run test` EXIT=0" |

| "deck lock 又脏了，提交一下" ("deck lock is dirty again, commit it") | "skill-deck.lock dirty after `deck refresh --exec` — hash-only, 4 entries (upstream content moved); commit it (`git add skill-deck.lock`), done = `git status` clean" |

| "dsh 插件化待定" ("dsh plugin-ization TBD") | "Pending decision: ship lythoskill-as-dsh-plugin? (a) adapter-only — current, low cost; (b) full plugin — blocked on dsh stable API (≥0.2); unblocker = dsh roadmap signal, else close as adapter-only by 2026-09-15. Ref: cortex/wiki/02-research/2026-08-29-deepseek-harness-integration-survey.md §Recommendation" |

| "卡在 npm 发布" ("stuck at npm publish") | "Stuck: `npm view @lythos/skill-deck` 404 immediately after publish; republish → E403. E403 = publish already succeeded (propagation delay). Next probe: exact-match `[ \"$OUT\" = \"0.19.1\" ]` after 60 s — never grep the version in error text (false positive)" |

## 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:

```markdown

### 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

| When you need to… | Read |

|--------------------|------|

| See the full daily file template with all sections | [references/daily-template.md](./references/daily-template.md) |

| See the weekly file template (YAML + markdown body) | [references/weekly-template.md](./references/weekly-template.md) |

| Understand the CQRS relationship with onboarding | [references/cqrs-architecture.md](./references/cqrs-architecture.md) |

| Set up automation triggers (hooks, events) | [references/automation-triggers.md](./references/automation-triggers.md) |