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) → 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

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill