kimal3 0.4.0 → 0.6.0

package/skill/en/commands/k3plan.md

@@ -0,0 +1,342 @@
+---
+description: Check the specs against the code and upload the planning to the app
+---
+
+<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
+     overwritten on every update. Your own changes will be lost; if you want
+     to keep them, copy the file under a different name. -->
+# Checking and uploading the planning
+
+## 1. What for
+
+You check the user stories in this project's specs against the code and upload **only the
+result** to the app — never the code. There, on the project page (tab "Planning"), the person
+sees what is open, what is waiting for their test and what is done, and gives a verdict with
+"Works" or "Doesn't work".
+
+Work through the sections in order. You need the rules (section 5) and the file format
+(section 6) from section 2 onwards — read them first. What an exit code of `kimal3` means is in
+**`~/.claude/skills/kimal3/SKILL.md`, section "Exit codes"**; this file does not repeat it.
+
+🔑 **`/k3plan` checks, sorts and uploads — it builds nothing.** Whatever needs fixing is
+attached to the story as a finding afterwards; building happens when the person says so.
+
+## 2. Fetch the responses
+
+Work in the **project folder** (where the specs and the code are). The file is always called
+`plan/stand.json`, relative to that folder.
+
+```
+kimal3 plan
+```
+
+**If you get `There's no plan/stand.json in this folder.`**, it is the first time (or you are in
+the wrong folder — check that first):
+
+1. `kimal3 project list` — look for the project this is about. If there is **no** matching one,
+   ask the person which one is meant and suggest `/k3project <what you built>`
+   (German: `/k3projekt`): without an entry in the success profile there is no project page.
+   Stop there, don't invent anything.
+2. Create `plan/stand.json` with the name **exactly as the list writes it**:
+
+   ```json
+   {
+     "format": 1,
+     "projekt": "LinkedIn Content App",
+     "projekt_id": null,
+     "basis": null,
+     "geprueft_am": "2026-10-21T22:10:00+02:00",
+     "specs": [],
+     "themen": [],
+     "uebernommen": []
+   }
+   ```
+
+   (Name and time are an example.) The field names are German and stay German. `kimal3 plan
+   upload` enters `projekt_id` and `basis` itself after the first upload — **leave them at
+   `null`**.
+3. Run `kimal3 plan` again.
+
+**What the output means** (example, made-up values):
+
+```
+#12 · doesn't work · 2026-09-23-content-planner / US-2 (round 1): When dragging, it jumps to Tuesday
+#13 · Topic: The calendar should show public holidays
+Confirmed: 2026-09-23-content-planner / US-1 (round 1)
+View: https://app.kimal3.de/projekt/…
+```
+
+- `#12 · doesn't work · <spec> / <story> (round n): <sentence>` — the person tested the story and
+  it doesn't hold. → Rule 1 in section 5. You need the number later for `uebernommen`.
+- `#13 · Topic: <sentence>` — something new they noted in the app. → Rule 3.
+- `Confirmed: …` — for these stories they said "Works" in **this** round; they are done. You
+  never need to hand on a "Works".
+- `View: …` — the link to the planning. Keep it for the report.
+- `No open responses.` — nothing to hand on; carry on with section 3.
+
+**Refusals:**
+- `No project is called "…". Your projects: … Enter the name in plan/stand.json exactly like
+  that.` — copy the matching name **word for word** from the list into `"projekt"`. If two could
+  fit, ask.
+- `Several of your projects are called "…" (ids: …).` — ask the person which one is meant and
+  enter its id as `"projekt_id"`.
+- `The project number in plan/stand.json belongs to none of your projects.` — the number comes from
+  a copied folder or a deleted project. Set `"projekt_id"` to `null` (the line stays, the field is
+  required); then kimal3 searches by name. This is the **only** case in which you change
+  `projekt_id` yourself.
+- `The plan can't be read: plan/stand.json doesn't contain a valid JSON object.` — repair the
+  brackets or commas in the file.
+
+## 3. Find the specs
+
+In the project folder, look in **`docs/superpowers/specs/`**, **`plan/`** and **`docs/specs/`**
+for Markdown files with user stories ("As … I want … so that …", often `US-1`, `US-2`, with
+acceptance criteria and a counter-check). `plan/stand.json` itself, status notes and task lists
+are not specs.
+
+One entry in `specs` per spec, one entry in `stories` per user story, one entry in `kriterien`
+per acceptance criterion (in short, at most 500 characters: starting point → action → result).
+
+🔴 **The keys are binding.** The app ties every "Works" and "Doesn't work" to spec key + story
+key + round. If a spec or story is already in `plan/stand.json`, **keep its key unchanged** — a
+renamed key makes the person's verdict disappear. New: spec key = file name without `.md`; story
+key = the number from the spec (`US-3`); if the spec doesn't number them, count `US-1`, `US-2` …
+yourself in their order.
+
+- `titel`: the heading of the spec or the story. `datei`: the path of the spec in the project
+  folder (relative, ends in `.md`; otherwise `null`). `kimal3 plan upload` reads the **text** of the spec from
+  this file and sends it along — it does not read paths outside the project folder.
+- The story key is **the same as in the heading of the spec**, where the spec numbers its stories
+  (`### US-3 · …` → `US-3`): the app finds the story in the spec text through this key.
+- A spec without stories goes in with `"stories": []`; mention it in the report.
+- Limits: at most 50 specs, 60 stories per spec, 400 altogether. If there are more, ask the
+  person which specs belong in.
+
+**The state of each story (`stand`):**
+- `offen` — nothing built yet.
+- `in_arbeit` — partly built, or a finding is open. `gebaut_am` is then `null`.
+- `gebaut` — built. `gebaut_am`: the date on which **this round** was finished (`YYYY-MM-DD`);
+  plus a `testen` sentence (section 4).
+- `weggelassen` — deliberately not built, `grund` is required (rule 8). Only if the spec or the
+  person decided so — never on your own to tidy up. If in doubt: leave it `offen` and ask in the
+  report.
+
+## 4. Check against the code
+
+Run the counter-check of each criterion **wherever you can**: the project's guards or tests
+(`npm test`, `npm run …`), a command, starting the app and calling the address, reading a file.
+
+- `bestanden` (passed) — **only** if the counter-check ran in this session and showed the
+  expected result. Never from memory, never from last time, never because the code "looks right".
+- `gescheitert` (failed) — it ran and showed something else. That is a finding (rule 1); the app
+  then puts the story and its spec under "In progress".
+- `offen` (not run) — everything that did not run: needs a browser, a sign-in, real data or a
+  person. Reading only counts if the criterion says something about the file itself (a file
+  exists, a text is there as written) — reading does not prove a behaviour.
+
+⚠️ A story with an `offen` criterion is shown under "Claude test pending", and the person can't
+test it yet. Say in the report what is missing so the counter-check can run.
+
+**The `testen` sentence** (on every `gebaut` story, at most 1000 characters) names **the address
+or the command** and **what must be visible there**, for example: "Start `npm run dev`, open
+http://localhost:3000/calendar and drag the post from Monday to Wednesday — it is then on
+Wednesday." Without it the app shows: "Claude didn't write down how to test this".
+
+**Findings** (`befunde`): only **open** ones. `quelle: "claude"` for something the story promises
+and doesn't do, and that no criterion covers. `seit`: the date the finding came up — if it is
+already in the file, it keeps its old date.
+
+**The round** (`runde`) ties a verdict to a build — like a stamp on one version of a document:
+- It starts at `1` and **never** goes down.
+- **Raise it by exactly 1** when a story with a finding from the person (`quelle: "mensch"`) has
+  been fixed since (Git history, and the counter-checks pass now): then `befunde: []`,
+  `stand: "gebaut"`, a new `gebaut_am`, a new `testen` sentence. The person tests again. If it is
+  unclear whether it was fixed: leave the finding and ask in the report.
+- **Also raise it** if you changed a **confirmed** story in a way the person would notice — their
+  old "Works" no longer applies (rule 7).
+- Otherwise **leave it alone**: a confirmed story stays done as long as its round stays the same.
+
+## 5. The eight rules
+
+The app shows them to the person in exactly this wording ("How planning stays short"):
+
+1. **A finding is not a new card.** If a story doesn't hold what it promises — Claude's check fails or you say "Doesn't work" — the finding is attached to that story and its spec goes back to "In progress".
+2. **Only what nobody promised is new. It goes into the inbox, which has five places.**
+3. **Claude sorts every topic at the next `/k3plan`:** as a new story in a spec, as a finding on a story, or dropped with a reason. There is no "later". What happened to it is shown under "Recently sorted".
+4. **Nothing stays in the inbox longer than 14 days.**
+5. **At most one spec in progress at once** ("In progress" and "Claude test pending" together). Finish it before starting the next.
+6. **At most five stories wait for your test.** If there are more, Claude starts nothing new until you have tested.
+7. **Done means checked twice:** Claude's checks passed, and you said "Works" — for exactly this version.
+8. **A spec is only closed when every story is done or deliberately left out** — with a reason. There is no silent remainder.
+
+**What you do with them:**
+
+- **Rule 1 — every `doesn't work` from `kimal3 plan`:** if the story still exists, attach the
+  person's sentence to it as a finding (`{ "text": "<their sentence>", "quelle": "mensch",
+  "seit": "<today>" }`), `stand: "in_arbeit"`, `gebaut_am: null`. If it has already been fixed
+  since, raise the round by 1 and set `befunde: []` instead (section 4). Plus in `uebernommen`:
+  `{ "rueckmeldung": 12, "antwort": "Finding on US-2" }`. If the story no longer exists, the
+  `antwort` says why. ⚠️ Without a finding from `mensch` and without a higher round, the server
+  refuses the upload.
+- **Rule 2 — something new:** what you notice while checking, or what the person says in the
+  conversation, and what **no** spec promises goes into `themen`:
+  `{ "schluessel": "T-1", "text": "…", "quelle": "claude" | "mensch", "seit": "<today>" }`.
+  The five places are shared by `themen` and the open notes from the app.
+- **Rule 3 — sort:** every `Topic` from `kimal3 plan` **and** every topic already in `themen` from
+  earlier is sorted **now** — one of three:
+  - **new story:** write it into the spec it belongs to (user story, acceptance criterion with
+    counter-check) and into `plan/stand.json` with `stand: "offen"`. If no spec fits, ask where it
+    goes. Answer: `new story US-7 in "Content planner"`.
+  - **finding on a story:** as in rule 1. Answer: `finding on US-2 in "Content planner"`.
+  - **dropped:** answer `dropped: <reason in one sentence>`, for example
+    `dropped: public holidays are already in the calendar tool.`
+
+  For a note from the app, the answer goes into `uebernommen` as **one sentence** (the app shows
+  it under "Recently sorted" as `<note> → <answer>`); so write it **without** an arrow at the
+  start. A topic from the file you take out of `themen` and name how it was sorted in the
+  report.
+- **Rule 4:** because you sort everything at every `/k3plan`, nothing stays long. A topic with
+  `seit` more than 14 days ago is sorted now **in any case**.
+- **Rules 5 and 6 — don't start a new spec** while another spec is in progress (one of its
+  stories is `in_arbeit`, has a finding or a failed counter-check, or is `gebaut` with an `offen`
+  criterion or with no criteria at all), or while more than five stories are waiting for the person's test (`gebaut`, all
+  passed, no finding, not yet confirmed). **Tell the person what to test instead** — with the
+  `testen` sentences. If you sort a topic in as a new story in a spec, you do not start that spec
+  with it: it stays `offen`, and the spec does not count as in progress.
+- **Rule 7:** only the person sets "Done", with "Works" in the app; the file has no field for it.
+  You only keep the round stable (section 4).
+- **Rule 8:** `weggelassen` only with a `grund` (section 3).
+
+## 6. The file
+
+`plan/stand.json` is under Git. Example, shortened:
+
+```json
+{
+  "format": 1,
+  "projekt": "LinkedIn Content App",
+  "projekt_id": null,
+  "basis": null,
+  "geprueft_am": "2026-10-21T22:10:00+02:00",
+  "specs": [
+    {
+      "schluessel": "2026-09-23-content-planner",
+      "titel": "Content planner as a page",
+      "datei": "plan/2026-09-23-content-planner-page-spec.md",
+      "stories": [
+        {
+          "schluessel": "US-2",
+          "titel": "Move posts in the calendar",
+          "stand": "gebaut",
+          "runde": 1,
+          "gebaut_am": "2026-10-21",
+          "kriterien": [
+            { "text": "Drag the post from Monday to Wednesday -> it is on Wednesday", "gegenprobe": "bestanden" }
+          ],
+          "befunde": [],
+          "testen": "Open /calendar and drag the post from Monday to Wednesday.",
+          "grund": null
+        }
+      ]
+    }
+  ],
+  "themen": [
+    { "schluessel": "T-1", "text": "The calendar should show public holidays", "quelle": "mensch", "seit": "2026-10-21" }
+  ],
+  "uebernommen": [
+    { "rueckmeldung": 12, "antwort": "Finding on US-2" }
+  ]
+}
+```
+
+**The fields** — every one must be there, even if it is `null` or empty; the server refuses an
+unknown field (a typo like `"befund"`):
+
+- `format`: exactly `1`.
+- `projekt`: the name as in the app, 1–200 characters.
+- `projekt_id`, `basis`: `null` at first; after that `kimal3 plan upload` writes them — **never
+  change them by hand**. Only exception: the refusal "The project number in plan/stand.json
+  belongs to none of your projects." — then set `projekt_id` to `null` (section 2).
+- `geprueft_am`: now, with time zone (`date +%Y-%m-%dT%H:%M:%S%:z` in Bash, `Get-Date -Format
+  "yyyy-MM-ddTHH:mm:sszzz"` in PowerShell).
+- `specs[]`: `schluessel` (unique, 1–80 characters), `titel` (1–200), `datei` (path or `null`),
+  `stories[]`.
+- `stories[]`: `schluessel` (unique within its spec), `titel`, `stand` (`offen` · `in_arbeit` ·
+  `gebaut` · `weggelassen`), `runde` (1–999), `gebaut_am` (`YYYY-MM-DD` for `gebaut`, otherwise
+  `null`), `kriterien[]`, `befunde[]`, `testen` (sentence or `null`), `grund` (required for
+  `weggelassen`, otherwise `null`).
+- `kriterien[]`: `{ "text", "gegenprobe": "bestanden" | "gescheitert" | "offen" }`, at most 30
+  per story.
+- `befunde[]`: `{ "text", "quelle": "claude" | "mensch", "seit": "YYYY-MM-DD" }` — open ones only,
+  at most 20.
+- `themen[]`: `{ "schluessel", "text", "quelle", "seit" }`, at most 50 (the inbox has five places,
+  rule 2).
+- `uebernommen[]`: `{ "rueckmeldung": <number from kimal3 plan>, "antwort": "<one sentence>" }`.
+  `kimal3 plan upload` empties it itself after uploading.
+- The whole file: at most 300 KB.
+
+## 7. Upload
+
+First the dry run — it checks everything and saves nothing:
+
+```
+kimal3 plan upload --dry-run
+```
+
+`Dry run: would upload 9 stories and mark 2 responses as handled. Nothing was saved.` (numbers as
+an example). **Compare the second number** with the open responses from `kimal3 plan`: if it is
+smaller, you forgot one — it would stay in the app under "Waiting for Claude".
+
+Then:
+
+```
+kimal3 plan upload
+```
+
+It worked if you see `✓ Planning for "…" uploaded: … stories, … waiting for your test.` and
+`View: …`; the first time also `projekt_id and basis are now in plan/stand.json.` The CLI has
+entered `projekt_id` and `basis` and emptied `uebernommen` — leave the file like that. Tell the
+person that `plan/stand.json` has changed and belongs in the next commit.
+
+After that comes a line `Spec texts uploaded: 1 of 3. Without text: …` — the text of the specs goes up too.
+A spec without text is a **hint, not a failure** (exit code `0`): tell the person which specs are in
+the brackets and what to do (correct the path in `datei`; over 300 KB cannot be uploaded).
+
+**Refusals — read the message, fix it, dry run, again:**
+
+| The message starts with | What you do |
+|---|---|
+| `The plan can't be read: <place> …` | Repair that place (`specs[0].stories[2].stand`) in the file. |
+| `No project is called …` · `Several of your projects are called …` · `The project number in plan/stand.json belongs to none of your projects.` | As in section 2. For the project number you may set `projekt_id` to `null` — only here. |
+| `<spec> / <story> has round 1, round 2 is already saved.` | The file is older than the saved state. Set the round to the saved value — never lower. |
+| `Response 12 doesn't exist in this project or is listed twice …` | Only numbers from `kimal3 plan`, each one once. |
+| `Response 12 ("…") is marked as handled, but US-2 has no finding from you …` | Attach the finding with `quelle: "mensch"` to the story (rule 1) — or raise the round by 1 if it has been fixed. |
+| `The app has a newer plan (uploaded …).` | Another working copy has uploaded. **Do not overwrite.** Tell the person and ask whether you should first fetch that state (Git) and check again. `kimal3 plan upload --overwrite` **only after their explicit yes.** |
+| `The planning saved in the app is damaged …` | Here too, `--overwrite` **only after their yes.** |
+| `The planning is saved, but the responses aren't marked as handled yet.` | Run `kimal3 plan upload` **unchanged** once more — that is harmless, the CLI has already entered `basis` and left `uebernommen` in place. |
+| ``The plan is saved, but the spec texts are not. Run `kimal3 plan upload` again.`` | Run `kimal3 plan upload` **unchanged** once more — the plan is already in the app, the CLI has entered `basis`. |
+| `⚠ The planning is saved, but plan/stand.json couldn't be updated. Enter it yourself: …` | Write exactly these values into the file. |
+| `… couldn't be loaded just now` / `… couldn't be saved just now` | Try once more; if it still fails, tell the person. |
+
+🔴 **`--overwrite` replaces what someone else uploaded.** Never on your own decision, not even
+when the message suggests it.
+
+## 8. Report to the person
+
+**At most five lines**, without jargon:
+
+- what was **done** (confirmed since last time),
+- what is **waiting for their test** — with the `testen` sentence, so they can start right away,
+- what was decided in the **inbox** (each topic with its answer),
+- a **warning** if rule 5 or 6 is broken: "Test … first" instead of a new story,
+- the **link** from `View: …`.
+
+Example (made-up values):
+
+```
+Done: US-1 "Create posts".
+Your test: US-2 - open /calendar and drag the post from Monday to Wednesday.
+Inbox: "The calendar should show public holidays" -> new story US-7 in "Content planner".
+Claude test pending: US-4 needs a browser I don't have here.
+Planning: https://app.kimal3.de/projekt/…
+```

package/skill/en/commands/k3show.md

@@ -0,0 +1,302 @@
+---
+description: Show a task instead of describing it — I record it and turn it into a plan
+---
+
+<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
+     overwritten on every update. Your own changes will be lost; if you want
+     to keep them, copy the file under a different name. -->
+# Show
+
+> You do a task once on screen and say out loud what you are doing and why.
+> I record it, evaluate it on your computer and write a description of it into the
+> project — so that we can automate the task afterwards without you first having to write
+> it down as a requirement.
+
+Carry out the steps in order. Stay in the coaching tone: English, friendly, **one question at a
+time and always with a suggestion**, the why before the how, no prior knowledge assumed. The
+mechanics are done by the program (`kimal3 show …`); you lead the conversation with the person. How
+to deal with `kimal3`'s exit codes in general is in `~/.claude/skills/kimal3/SKILL.md`; here are only
+the cases of this command.
+
+## 🔴 Three rules for the whole conversation
+
+1. **Before the yes in step 10 you read nothing from the recording.** No `zeitleiste.md`, no
+   picture, no log, no other file from `material/aufnahmen/` — and you don't **search** there
+   either: no grep, no glob, no file search across the project that includes this folder. What
+   lies there only leaves the computer with the person's yes. You may read the output of
+   `kimal3 show …` — it contains only numbers, times and folder names.
+2. **Install nothing, record nothing, delete nothing without an explicit yes to exactly that
+   step.** You open a file from the recording for the person only in Notepad, and in a way that
+   your call returns at once: in Bash `cmd //c start "" notepad "<path>"`, in PowerShell
+   `Start-Process notepad -ArgumentList '"<path>"'`. A bare `notepad "<path>"` blocks until the
+   window is closed again. Never in an IDE or an editor that Claude Code is attached to (selected
+   lines end up in the conversation there by themselves).
+3. **A failure never looks like a success.** If a `kimal3 show …` doesn't end with `0`, say
+   honestly what its message says, and don't carry on as if it had worked.
+
+Every `kimal3 show …` runs **in the project folder** (step 3) — the program finds the recording
+through the folder it is started in. If a recording lies in another project, change into it first:
+the project folder is the part of the path before `material/aufnahmen/`.
+
+## 1. Arrive and look
+
+First run `kimal3 show status`. It only reads. **Don't** read the “Set up:” block out to the
+person — just note whether anything in it is missing (a line with “missing”, “can't be checked”,
+“I can't tell” or “(… is needed)” → step 4).
+
+| The output says | What you do |
+|---|---|
+| `kimal3 show` is Windows-only for now; the Mac follows. | Say exactly that, kindly: showing a task doesn't work on this computer yet, the Mac is coming. Offer that the person describes the task in words instead. The command ends here. |
+| “I can't tell whether a recording is running.” (exit code 1) | Say honestly that you can't tell right now. **Start nothing.** Offer to look again in a minute. |
+| “Running since 09:12 (3 minutes), folder `…`, stops at 09:27 at the latest.” | A recording from an earlier session is still running. If the folder is a full path outside this project, first change into its project folder. Then ask: “There's still a recording running from 09:12 — are you through with showing the task? Then I'll stop it now.” Yes → step 8. |
+| “Running (started in another session).” | A recording is running that this project can't match. Say so, **don't start a second one**, and suggest checking with `kimal3 show status` once it has ended. |
+| “No recording is running.” followed by “The last one (`…`) stopped by itself after 15 minutes.” | A recording is finished but probably not evaluated yet. **Don't silently start a new one over it.** Ask with a suggestion: “The recording from 09:12 stopped by itself after 15 minutes — shall I evaluate it, or would you rather show the task again? I'd evaluate it; whatever you did after the 15 minutes is then missing.” Evaluate → step 9 (the time is in the folder name, `…-0912`). Again → carry on here. |
+| “No recording is running.” followed by “The last one (`…`) broke off.” | Kindly: the last recording broke off in the middle — the person did nothing wrong. Offer to show the task again. |
+| “No recording is running.” | Carry on. |
+
+The last line says whether the folder is right — remember it for step 3:
+“Recordings go here: …” (right) · “Switch into a project first …” (the session is in the
+workbench) · “The project folder is nested too deeply for the recorder …” (the path is too long).
+
+If the session is in the workbench, say **that first**, in one sentence: the recording belongs in
+a project, and you'll suggest one in a moment. Then explain in at most five short sentences what
+happens, and ask **one** question:
+
+> “You show me the task once and talk while you do it. I record the screen, sound, clicks and
+> keys. It stays on your computer. Before I read any of it, I'll ask you. Which task do you want
+> to show me — in one sentence?”
+
+Until the person has answered, nothing is installed and nothing is recorded.
+
+## 2. The task in one sentence
+
+Wait for the answer. You take the person's sentence **unchanged** — it will stand at the top of
+the timeline, and exactly where it and the demonstration differ lies the most important follow-up
+question (step 11). A rough sentence is enough; don't dig.
+
+## 3. The right folder
+
+- **Recordings already go to the right place here?** Carry on with step 4.
+- **The session is in the workbench** (`workbench-…`): suggest a project with a short name from the
+  task — lower case, hyphens: “I'd create the project `projects/quote-list` for this — does that
+  work?” (if the folder in the workbench is called `projekte/`, then there). Only after the yes do
+  you create **only** `plan/` and `material/` in it, nothing in advance. From now on every
+  `kimal3 show …` runs in this project folder (e.g. `cd "<project folder>" && kimal3 show status`).
+  Check with `kimal3 show status` that the last line now says “Recordings go here: …”.
+- **The path is too deep:** name the number from the message and why (the recorder fails on long
+  paths). Suggest creating the project closer to the drive, and ask before you create anything.
+
+## 4. Setting up — only if something is missing
+
+If nothing is missing, skip this step without a word about it. If something is missing, say
+**exactly this first** and wait for the answer:
+
+> “For this I'll set up the recorder once — a free program that records screen, sound, clicks
+> and keys. About 2.1 GB, 10 to 20 minutes depending on your connection, only in your user
+> folder, no admin rights. Because it records keystrokes, your company's antivirus may flag it;
+> on a work computer, check with IT first if in doubt. Shall I?”
+
+- **Yes:** start `kimal3 show setup` **in the background** — it can take longer than the ten
+  minutes a command may run in the foreground. Say that it is running and the person can do
+  something else meanwhile. **Wait for the notice that it has finished** — don't check in between,
+  and don't sleep in a loop. After that:
+  - exit code `0` → `kimal3 show status`; if all four parts are there (uv, recorder, FFmpeg,
+    speech model), carry on with step 5.
+  - exit code `1` (“Step … didn't work.”) → name that step, and offer a ready-made
+    message to IT: **what** (uv from Astral · the recorder openadapt-capture 1.3.0, MIT licence,
+    with Python 3.12 · FFmpeg · the speech model large-v3-turbo from Hugging Face), **what for**
+    (showing a work task once on screen and evaluating it on the computer), **where from**
+    (astral.sh or winget, pypi.org, huggingface.co), **which folders** (only the user folder, no
+    admin rights).
+- **No:** “No problem — you can do it any time later with `/k3show`.” The command ends here.
+
+## 5. The briefing before the start
+
+Say these four points before anything records:
+
+1. **All screens** are recorded. Close anything that shows other people's data, switch on “Do
+   not disturb”, and not during a call. If you can, use a **test customer** instead of a real
+   one.
+2. **Don't type a password** — every key is recorded.
+3. Say out loud **why** you do something.
+4. When you're done, come back here and type **“done”**; the recording stops by itself after 15
+   minutes at the latest.
+
+Then: “Type ‘go’ when you're ready.” — and wait.
+
+- **A clear go** — “go”, “ready”, “start” — → step 6.
+- **A bare “ok” or “yes”** → ask once: “Shall I start now?”
+- **Anything else** → answer and say that it starts with “go”.
+
+**Nothing starts before the go.**
+
+## 6. Starting
+
+After the go: `kimal3 show start '<the person's sentence>'`. Pass the sentence as **one** argument,
+so that the shell changes nothing in it — in Bash in single quotes (a `'` inside as `'\''`), in
+PowerShell in single quotes (a `'` inside doubled). `--at-most` (1 to 15 minutes) only if the person
+explicitly wants it shorter.
+
+| The output says | What you do |
+|---|---|
+| “The recording is running (folder …), stops at … at the latest.” (exit code 0) | Say exactly: “Running. Show me — and type ‘done’ here when you're through.” **Then end your turn** — no further command, no checking. |
+| “A recording is already running (since 09:12, folder `…`).” · “A recording is already starting …” | No second one is created. Ask: “There's still a recording running from 09:12 — shall I stop it so that we can start again?” Yes → `kimal3 show stop` (step 8), then back to step 5. |
+| “A recording is already running (started in another session).” | Ask: “There's still a recording running from another session — shall I stop it so that we can start again?” Yes → `kimal3 show stop`; if it says it can't match it here, say so honestly and suggest waiting until it stops by itself (`kimal3 show status`). |
+| “I can't tell whether a recording is running — so I won't start a second one.” | Say it honestly, force nothing, look again later. |
+| “The recorder isn't set up yet: `kimal3 show setup`.” | Back to step 4. |
+| “The recording didn't start: <reason>. Log: …” | Name the reason. **Don't open the log** — it contains window titles. If “Whether the recorder is still running: `kimal3 show status`.” follows, run `kimal3 show status` and say what it reports. Offer another attempt. |
+| “Switch into a project first …” · “The project folder is nested too deeply …” | Back to step 3. |
+
+## 7. While recording
+
+If the person writes anything other than “done” (a question, a thought), answer briefly and end
+with: “The recording is still running — type ‘done’ when you're through.” Open nothing on the
+screen meanwhile (it would end up in the video) and don't stop the recording on your own.
+“done”, “finished”, “I'm through” and the like → step 8.
+
+## 8. Stopping
+
+First say: “I'm finishing the recording — that can take a minute, with a long recording several.”
+Otherwise the person sees nothing happen while it finishes.
+
+Then `kimal3 show stop` — with the **longest wait the tool allows (10 minutes)**: the recorder finishes
+the video, and with a long recording that takes a while; with the default of 2 minutes the call
+would break off in the middle. The program answers after a little over 8 minutes at the latest, so
+before the 10 minutes are up.
+
+| The output says | What you do |
+|---|---|
+| “Recording stopped: 1:33 minutes, 30 clicks, 49 keys, audio present.” | Repeat the numbers in one sentence, carry on with step 9. |
+| “The recording is still being finished — run `kimal3 show stop` again in a moment.” (exit code 1) | Say: “The recorder is still finishing the recording — I'll check again in a moment.” Then run `kimal3 show stop` again, again with the 10-minute wait. **Never** say “not closed cleanly”, and don't offer a new recording. |
+| “The recording stopped by itself after 15 minutes: …” (exit code 0) | Say: “The recording stopped by itself after 15 minutes — whatever you did after that isn't in it.” Carry on with step 9. |
+| “No recording is running.” | Check with `kimal3 show status`. If it says “The last one (`…`) stopped by itself after … minutes.”, carry on with step 9; otherwise say honestly that there is no recording. |
+| “I can't tell whether a recording is running.” | Say it honestly — **never** “stopped”. Offer to look again in a minute with `kimal3 show status`. |
+| “The recording wasn't closed cleanly: <reason>.” (exit code 1) | Name the reason and offer a new recording. |
+| “The recording broke off: <reason>. …” (exit code 1) | Kindly: the person did nothing wrong. Name the reason and offer a new recording. |
+| “The recording couldn't be stopped …” · “A recording is running that I can't match here …” | Run `kimal3 show status` and say honestly what it reports — **never** “stopped”. If the session is in the wrong folder, change into the recording's project. |
+
+## 9. Evaluating — on the person's computer
+
+`kimal3 show evaluate` (without a folder it takes the project's latest recording; the language of
+the speech recognition follows the account — `--language de` or `--language en` only if the person
+spoke the other language). This takes about as long as the recording:
+
+- **Recording up to about 3 minutes:** in the foreground, with the longest wait (10 minutes).
+- **Longer — and always when it stopped by itself after 15 minutes:** **in the background**, as
+  with the setup. Say that it takes about as long as the recording, and **wait for the notice that
+  it has finished** — no checking in between, no loop.
+
+| The output says | What you do |
+|---|---|
+| “Timeline ready: … File: `…`.” | Say the numbers in one sentence. Remember the path — **don't open the file**. Carry on with step 10. |
+| “I didn't recognise any speech — was the microphone muted or the wrong one selected?” | Ask exactly that and offer a new recording. |
+| “The recording has no audio track — without sound there's no timeline. A new recording helps.” | Offer a new recording. |
+| “I can't find a recording in this project (`material/aufnahmen/`).” | The session isn't in the recording's project: change into it (the part of the path before `material/aufnahmen/`, from `kimal3 show status` or the stop message) and evaluate again. |
+| “The recording folder doesn't exist: …” | Say honestly that the recording isn't (or is no longer) there. Check with `kimal3 show status`; otherwise offer a new recording. |
+| “The recorder isn't set up yet: `kimal3 show setup`.” | Back to step 4, then evaluate again. |
+| “The timeline wasn't created: <reason>.” | Name the reason; if the speech model is missing, back to step 4. |
+| “The recording is still running — first `kimal3 show stop`.” | Back to step 8. |
+
+## 10. Data protection — before you read
+
+First one question, and wait for the answer:
+
+> “Did the demonstration show real data about people — customer names, email addresses?”
+
+**Yes:** then the four questions from `context/security.md` (in the workplace above the workbench;
+in a German workplace `kontext/sicherheit.md`) come **now**, before reading — one at a time, each
+with a suggestion: which fields · where to (to Anthropic, the company behind Claude, data centres
+in the USA) · on what legal basis · can it be done more sparingly, e.g. once more with test
+customers. You write the answers to `results/data-protection-demonstration.md` (in a German
+workbench `ergebnisse/`). If the answer is “once more with test customers”, read nothing, suggest
+deleting this recording (step 13, the sentence **without** the plan), and start again at step 5.
+
+Then this question, word for word:
+
+> “For me to read the timeline, it goes to Anthropic: what you said, where you clicked (with the
+> names of the buttons and fields — these can contain names) and what you typed. Screenshots show
+> your whole screen — I'll only look at those where the text isn't enough, and ask you before
+> each one. Shall I open the file for you so you can look first? Agreed — or would you rather
+> leave out the typed parts?”
+
+- **“Open it”:** in Notepad, as in rule 2 (`cmd //c start "" notepad "<full path>"` or
+  `Start-Process`), with the full path to `zeitleiste.md` (the project folder plus the path from
+  step 9). The person reads it themselves; you don't read along. Then ask the question about
+  agreeing once more.
+- **“Without the typed parts”:** `kimal3 show evaluate --without-typed` — with the same
+  `--language` as the first time, if you set one, and with the same waiting rule as in step 9. The
+  timeline is rewritten, and typed text then stands as “[typed, left out]”. The person has agreed
+  to this version → step 11.
+- **Agreed:** → step 11.
+- **No:** read nothing. Say: “You can read the file yourself and describe the task to me — or I
+  delete the recording.”
+  - **The person describes it:** take the description, ask follow-up questions as in step 11,
+    point 4 (one at a time), and carry on with step 12 — plan and way to build it **from the
+    description**, without reading anything from the recording. Then step 13.
+  - **Delete:** step 13, the sentence **without** the plan.
+
+## 11. Read, retell, ask
+
+Now — and only now — you read `zeitleiste.md`, and only this file.
+
+1. **Retell the task:** in numbered steps, in the **person's words** (quote what was said), each
+   step with the time from the timeline (`0:26`).
+2. **Look for the contradictions, explicitly.** Three sources say something about the task: the
+   task sentence at the top of the timeline, what the person **says**, and what they **click and
+   type**. Go through the task sentence part by part (what, where to, to whom, when) and ask for
+   each part: does the demonstration show exactly that? Then check every spoken sentence against
+   the click next to it. Every place where two sources differ, you name in the retelling with ⚠️ —
+   for example: “You clicked ‘tomorrow’, but said ‘for the current day’ — which one applies?” or
+   “The task sentence says ‘into a channel’, but you showed a direct message — which one applies?”
+   *These places are exactly why showing reveals more than describing.*
+3. **Screenshots only one by one and only after asking.** If the text isn't enough at a point (a
+   click without a name, a sentence pointing at something visible), ask first: “At 0:26 the text
+   only says ‘…’. May I look at the screen at that point?” Yes → `kimal3 show picture 0:26`; it
+   reports “Picture: <path>”, and you look at **only this one** picture. No → ask what was to be
+   seen there.
+4. **Then ask — one question at a time, always with a suggestion:** first the contradictions, one
+   after the other. After that, what a single demonstration can never show: **how often and when**
+   (“I'd guess every Monday morning — is that right?”) · **what happens in an exception** (a
+   public holiday, an empty list, the system can't be reached) · **who the result goes to**.
+
+## 12. Write it into the plan and suggest a way to build it
+
+Write `plan/task-shown.md` with these parts:
+
+- **Goal** in one sentence
+- **The steps**, numbered
+- **Rules and exceptions** from the answers
+- **What is still open**
+- **Where it comes from:** demonstration of <date> (or: description of <date>, if nothing was
+  read)
+
+The plan carries the content **itself** and doesn't point to files in the recording — that is
+about to go. Typed text that looks like access data doesn't go into it.
+
+Then say how you **would build it**: through the programs' interfaces (fetching the data
+directly, sending the message directly), **not** by re-clicking the clicks — that way it doesn't
+break when a screen changes. The building doesn't happen here; it is the next step in the
+project, right away or in the next session with `/k3start`.
+
+## 13. Deleting the recording — only after a yes
+
+Measure the size of the recording folder and suggest, with the real values. If the task is in
+the plan (step 12):
+
+> “The recording is 12.9 MB and lies in `material/aufnahmen/2026-10-19-0912`. I'd delete it —
+> the description is in the plan, and the recording contains everything you typed. What I read
+> from it stays in the conversation history on this computer. Is that alright?”
+
+If the suggestion comes without a plan (no in step 10, or “once more with test customers”), leave
+out the part about the plan:
+
+> “The recording is 12.9 MB and lies in `material/aufnahmen/2026-10-19-0912`. I'd delete it —
+> the recording contains everything you typed. What I read from it stays in the conversation
+> history on this computer. Is that alright?”
+
+- **Yes:** delete **exactly this one** folder — not `material/aufnahmen/` as a whole, not the
+  `.gitignore` and `.ignore` next to it — and check that it is gone.
+- **No:** it stays. Say where, and that it doesn't end up in Git.
+
+Finally, in two sentences without jargon, what is now in the project, and **one** concrete next
+step.