lythoskill-project-scribe {{PACKAGE_VERSION}}A

Immutable. This exact content is served forever at /api/v1/blob/b863e6b37bca55e6.

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

```
User: "踩坑了" ("hit a pitfall") → Record pitfall → Continue working on the bug
User: "记录一下这个决定" ("record this decision") → Write to daily → Continue with the task
User: "先记一下进度" ("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) |