deft-directive-tutorial git:20261018.b35d8ffA

Immutable. This exact content never changes and is served at /api/v1/blob/c2e92f40607eddcc.

---
name: deft-directive-tutorial
description: >-
  Runs the Directive Tutorial inside the current session. Use after the person
  first saves their Name, or when they ask to start, skip, resume, or re-run
  the tutorial (Signal, Postcard, or Echo). Do NOT trigger on session:start
  ceremony alone, triage:welcome, or a real product build.
---
<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
<!-- Purpose: rendered skill -->
<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
<!-- Regenerate with: task packs:render -->
<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->

# Directive Tutorial

The first sitting inside the session that is already running. The person picks Signal, Postcard, or Echo.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

## When to Use

- The person first saved their Name in user preferences, or asks for the Directive Tutorial
- A later session needs to resume the tutorial
- An explicit re-run after skip or complete

Do NOT trigger on `session:start` ceremony alone, `triage:welcome`, the longer training course, or a real product build.

## Goal

The person finishes one menu option, or has a recorded skip. The agent reads each step and follows it.

## Offer

! Offer only when `deft tutorial:offer --json` prints `"offerNow": true` (status `not_started`).
! Offer after Name is first persisted. ⊗ Wait for project definition or the specification interview.
⊗ Ask the name and preference questions again.
! Skip for now runs `deft tutorial:skip` before the tutorial has started.
! An explicit `deft tutorial:start` still works after skip or complete (complete needs reset first when status is completed).
⊗ Offer again when `offerNow` is false.

## Menu

! After start, the person picks from a numbered menu: **1 Signal**, **2 Postcard**, **3 Echo**, **4 Leave**, **5 Discuss**, **6 Back**.
! Record a project pick with `deft tutorial:advance --project signal|postcard|echo` (or `1|2|3`).
! Leave runs `deft tutorial:leave` (also `--project 4` / `--project leave` on advance).
! Discuss (`--project discuss` / menu Discuss) pauses and asks what to discuss; do not advance.
! Back (`--project back` / menu Back) moves one wired step earlier; on step 1 refuse Leave or Discuss. Back refuses when status is `completed` so finished progress cannot reopen.
! Every project option uses the same seven steps. Only the toy changes.
! Practice work runs in `repoPath`, a disposable local Git repository.
! On every later step the person may still leave (`deft tutorial:leave`).
⊗ Use the person's real project as the sandbox.
⊗ `git push`. ⊗ Open a pull request.

## Each step

## Numbered choices

! Whenever the person must pick, show a numbered menu (1, 2, 3…). Accept the number or the option label.
! Include Leave on every choice menu where leaving is allowed.
! End every structured menu with **Discuss** then **Back**, in that order (`contracts/deterministic-questions.md`).
⊗ Ask for free yes/no/go prose when a numbered menu is defined on the step.
⊗ Strip Discuss/Back from the rendered `beatText` menus.


! Run `deft tutorial:inspect --json` or `deft tutorial:resume --json`.
! Say `beatText` as written.
⊗ Paraphrase it or invent a step.
⊗ Paste the JSON `command` block into what the person sees.
! When JSON `command` is non-null, run those commands in `repoPath` yourself after the person's next action.
⊗ Run promote/activate/complete (or any lifecycle commands) when `command` is null — that means start or close already ran (for example after Back).
! Record progress with `deft tutorial:advance` and the matching flags.
⊗ Move on when advance refuses.

- Step 1 choose: `--project signal|postcard|echo` (or `1|2|3`); Leave → `deft tutorial:leave`; Discuss / Back as above
- Step 2 write: first `--content "..."` (or `--project 1` / Use the example), then `--confirm` (Plan/Done; menu 1 Yes / 2 No — change the plan / 3 Leave / 4 Discuss / 5 Back), then `--work-item <path>` (may combine with confirm). After Plan/Done is accepted without a path, show the work-file prompt — do not re-ask for content.
- Step 3 start: `--confirm` (menu: 1 Yes / 2 Leave / 3 Discuss / 4 Back). Commands promote and activate the proposed work file, then create the branch. After `startLifecycleDone` (Back to start), JSON `command` is null — do not re-run them.
- Step 4 change: `--content-seen` (menu: 1 Go / 2 Leave / 3 Discuss / 4 Back)
- Step 5 prove: menu 1 Go (run check), then record `--check pass|fail` (fail stays; pass stays on Continue). Menu after pass: 1 Continue / 2 Leave / 3 Discuss / 4 Back. After fail: 1 Try again / 2 Leave / 3 Discuss / 4 Back. A combined `--project 1 --check pass` on a failed prove step records the new result.
- Step 6 close: record Findings on the work file, stamp acceptance proof, then complete (`--complete`; menu: 1 Go / 2 Leave / 3 Discuss / 4 Back; only after a pass + Continue). Commands write `plan.narratives.Findings`, run `scope:stamp-evidence`, then `scope:complete --non-delivery experiment_archived`. After `closeLifecycleDone` (Back to close), JSON `command` is null — do not re-run Findings write, stamp-evidence, or complete.
- Step 7 leave: `advance` with no extra flags (only after close); otherwise `deft tutorial:leave`

## Progress

! `deft tutorial:leave` records skipped and clears the sitting; explicit start still works.
! Progress is stored in user preferences (`tutorial-state.json` next to USER.md), not in the product project.
! `deft tutorial:reset` clears progress and does not re-fire the automatic offer by itself.
! Mid-tutorial `deft tutorial:skip` moves one step and does not mark the work done.
! Completed status requires reset before another start; a fresh start does not reuse prior content, work-file path, or check results.

## Exit

! Say whether the sitting is paused, skipped, or finished, and which step is current.
⊗ Claim the work is done before step 6 has closed it.