From 581cc7002096cb73231bfb2e0725f02f08bbdea1 Mon Sep 17 00:00:00 2001
From: Vasily Guzov <vasily.guzov@gmail.com>
Date: Mon, 19 Oct 2026 10:02:18 +0300
Subject: [PATCH] docs: add session workflow note (lesson start/end prompts)

---
 docs/index.md                      |  1 +
 docs/workflows/session-workflow.md | 65 ++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 docs/workflows/session-workflow.md

diff --git a/docs/index.md b/docs/index.md
index 072bac8..9126df3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,6 +10,7 @@ of the repository.
 - [[workflows/research-workflow|Research workflow]] — how we collect and analyze research artifacts
 - [[workflows/gitea-workflow|Gitea workflow]] — how the board, labels, milestones and issues are organized
 - [[workflows/english-workflow|English workflow]] — how the project doubles as English practice
+- [[workflows/session-workflow|Session workflow]] — the two ritual prompts that open and close every practice session
 
 ## Folders
 
diff --git a/docs/workflows/session-workflow.md b/docs/workflows/session-workflow.md
new file mode 100644
index 0000000..a1afa65
--- /dev/null
+++ b/docs/workflows/session-workflow.md
@@ -0,0 +1,65 @@
+# Session workflow
+
+Two ritual prompts bookend every practice session: the assistant assembles the lesson plan
+from the vault itself (sprint note, DevLog, open tasks), and closes the session by writing
+the artifacts back. Planning stops being a manual step that eats lesson time and drifts
+from the methodology (sprint rhythm 5/30/10, one drill = one commit).
+
+The vault keeps the English canonical version. Ready-to-paste Russian originals (the chat
+language) are kept outside the repo at `~/.local/share/viexp/session-prompts-ru.md` — the
+vault itself is English-only, and `TMP/` is tracked in git despite the name. The English
+prompts below are also safe to paste as-is.
+
+In ZCode both rituals are project commands, no pasting needed: `/lesson-plan [budget-min]`
+and `/lesson-close` (defined in `.agents/skills/`).
+
+## Session-start prompt
+
+Paste as the first message of a new chat. Fill in the lesson budget; the assistant replies
+with the plan only and waits for a go-ahead.
+
+```text
+viexp lesson — prepare today's plan. Plan only, do not start the work.
+
+Gather the context yourself:
+1. Active sprint: docs/sprints/ with status: active.
+2. The latest docs/devlog/*.md by date — its "Next session" section.
+3. Open tasks of the sprint: docs/tasks/ (status: todo | in-progress | blocked)
+   and open issues of the current milestone via tea.
+
+Answer strictly in this format:
+Where we are — 2–3 lines: last commit, what is left from the previous lesson.
+Lesson goal — one phrase + task/issue number.
+Drills — 2–4 × 20–30 min, each: name / what I do / done-when (demoable
+  result). One drill = one commit.
+Wrap-up — last 10 minutes: DevLog, ErrorJournal, sync the board.
+Lesson budget: __ min — drills plus wrap-up must fit the budget.
+
+Rules:
+- If it does not fit the budget, cut the number of drills, never the time of each.
+- If something is missing or unclear — pick an obvious default, mark it
+  "assumption", do not ask questions.
+- Until I reply "go" (or correct a point) — do nothing.
+```
+
+## Session-end prompt
+
+Paste in the last ~10 minutes of the session; review the diff and commit yourself.
+
+```text
+Close the viexp lesson:
+1. Create/update today's docs/devlog/ entry from the TMP/DevLog.md template:
+   what I did, frustrations, English practice, Next session.
+2. ErrorJournal — today's errors with a self-correction cue, if any.
+3. Sprint note: update hours-logged and checkboxes.
+4. Bring task-note statuses in line with reality.
+Show the changes — I will review and commit myself.
+```
+
+## Why it works this way
+
+- **Fixed answer format** — the plan always has the same shape, so the methodology can't
+  drift: the assistant pulls "Next session" from the DevLog and open issues itself.
+- **Planning is separated from work** — nothing happens before the explicit "go"; correcting
+  a plan point is cheaper than redoing a lesson mid-way.
+- **The budget cuts scope, not depth** — fewer drills, never shorter drills.