From c0fd1e973e040347d424e09934099f1bd6c2dee0 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 6 Aug 2026 14:48:55 +0100 Subject: [PATCH 1/2] refactor(wizard): remove the minutes estimate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The wizard always told the human how many minutes the procedure would take and how many were left. The number was invented at authoring time and never true, so it is gone. - template.sh: drop TOTAL_MINUTES and _MINUTES_ELAPSED, the "about N minutes" banner line, and the "(~N min left)" stage suffix. stage() takes a name only; progress is a stage count. - SKILL.md: state the rule — no minutes in the script, in stage headers, or in what the agent tells the user. - docs: the Stages section counts stages, not minutes. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/wizard-no-minutes.md | 5 +++++ docs/engineering/wizard.md | 2 +- skills/engineering/wizard/SKILL.md | 8 +++++--- skills/engineering/wizard/template.sh | 26 ++++++++++---------------- 4 files changed, 21 insertions(+), 20 deletions(-) create mode 100644 .changeset/wizard-no-minutes.md diff --git a/.changeset/wizard-no-minutes.md b/.changeset/wizard-no-minutes.md new file mode 100644 index 0000000..e054ebc --- /dev/null +++ b/.changeset/wizard-no-minutes.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": patch +--- + +wizard: never give a time estimate. The template drops `TOTAL_MINUTES` and the time-remaining display, `stage` takes a name only, and progress is counted in stages. diff --git a/docs/engineering/wizard.md b/docs/engineering/wizard.md index 043f54c..a5eebe6 100644 --- a/docs/engineering/wizard.md +++ b/docs/engineering/wizard.md @@ -25,7 +25,7 @@ None to generate one. The wizard it writes runs on bash, and uses `gh` when a st ## Stages -A **stage** is one focused task on one screen. The script clears the terminal between stages, so a stage that overflows the screen loses the part that scrolled away. You author stages in dependency order and set `TOTAL_STAGES` and `TOTAL_MINUTES`, which drive the time-remaining display — make the estimate honest, because the person running it will hold you to it. +A **stage** is one focused task on one screen. The script clears the terminal between stages, so a stage that overflows the screen loses the part that scrolled away. You author stages in dependency order and set `TOTAL_STAGES`, which drives the progress display. There is no time estimate anywhere: progress is counted in stages, never in minutes. Scoping happens before a line is written. The [skill](https://www.aihero.dev/ai-coding-dictionary/skill) reads the repo instead of asking cold: `.env*`, `docker-compose*`, framework config, and every `secrets.*` / `vars.*` reference in `.github/workflows/` — each of those is a value the wizard has to produce. It then shows you the ordered stage list to confirm, and only after that maps each stage to the exact path a human follows ("Dashboard → Developers → API keys → Reveal test key → copy"). Where it doesn't know the current UI, it asks you or checks the docs rather than inventing clicks. diff --git a/skills/engineering/wizard/SKILL.md b/skills/engineering/wizard/SKILL.md index 7c42dbd..7427b91 100644 --- a/skills/engineering/wizard/SKILL.md +++ b/skills/engineering/wizard/SKILL.md @@ -5,9 +5,11 @@ description: Generate an interactive bash wizard that walks a human through step # Wizard -A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how much is left. It might configure third-party services, run a one-off migration, or move the project from one state to another. +A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another. -The delightful UX is already solved by [template.sh](template.sh) — progress with time-remaining, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it. +**Never give a time estimate.** No minutes in the script, in the stage headers, or in what you tell the user — not for a stage, not for the wizard as a whole. Progress is measured in stages only. + +The delightful UX is already solved by [template.sh](template.sh) — stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it. A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo. @@ -32,7 +34,7 @@ For each stage, write the precise path a human follows: which URL to open, what ### 3. Author the wizard -Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` and `TOTAL_MINUTES` to honest estimates (this drives the time-remaining display). +Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote (this drives the progress display). Give `stage` a name only; it takes no duration. Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker. diff --git a/skills/engineering/wizard/template.sh b/skills/engineering/wizard/template.sh index 95b7a6a..feccfbc 100644 --- a/skills/engineering/wizard/template.sh +++ b/skills/engineering/wizard/template.sh @@ -19,12 +19,10 @@ else BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED="" fi -# Author sets these two at the top of the stages section. +# Author sets this at the top of the stages section. TOTAL_STAGES=0 -TOTAL_MINUTES=0 _STAGE_INDEX=0 -_MINUTES_ELAPSED=0 ENV_FILE="${ENV_FILE:-.env}" WRITTEN_ENV=() # KEYs written to ENV_FILE this run WRITTEN_SECRET=() # secret NAMEs set this run @@ -37,28 +35,24 @@ _clear() { if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi } -# banner "Title" — opening frame: what this wizard does and how long it takes. +# banner "Title" — opening frame: what this wizard does. Never a time estimate. banner() { _clear printf '\n%s%s %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET" - printf '%s %s stages · about %s minutes%s\n\n' \ - "$DIM" "$TOTAL_STAGES" "$TOTAL_MINUTES" "$RESET" + printf '%s %s stages%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET" printf '%s You drive the browser; this wizard tells you exactly what to do and\n' "$DIM" printf ' captures the values you copy back. Stop any time with Ctrl-C and re-run\n' printf ' later — it remembers values already saved.%s\n' "$RESET" pause "Ready to start?" } -# stage "Name" — clear the screen, then announce a stage and show -# progress + time remaining. Clearing keeps only the current step on screen. +# stage "Name" — clear the screen, then announce a stage and show progress as a +# stage count. Clearing keeps only the current step on screen. stage() { _clear _STAGE_INDEX=$((_STAGE_INDEX + 1)) - local remaining=$((TOTAL_MINUTES - _MINUTES_ELAPSED)) - (( remaining < 0 )) && remaining=0 - _MINUTES_ELAPSED=$((_MINUTES_ELAPSED + ${2:-0})) - printf '\n%s%s▸ Stage %s/%s · %s%s %s(~%s min left)%s\n' \ - "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" "$DIM" "$remaining" "$RESET" + printf '\n%s%s▸ Stage %s/%s · %s%s\n' \ + "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" } # say "..." — a plain instruction line. @@ -187,16 +181,16 @@ finish() { # ────────────────────────────────────────────────────────────────────────── # STAGES — author this section. One stage() per step the human takes. -# Replace the example below. Set the two totals to match the stages you write. +# Replace the example below. Set TOTAL_STAGES to match the stages you write. +# Never tell the human how many minutes anything takes. # ────────────────────────────────────────────────────────────────────────── TOTAL_STAGES=1 -TOTAL_MINUTES=5 banner "Stripe setup" # ── Example stage: replace with your real steps ─────────────────────────── -stage "Stripe — API keys" 5 +stage "Stripe — API keys" say "We'll grab your Stripe test keys and store them for local dev + CI." open_url "https://dashboard.stripe.com/test/apikeys" step "On the API keys page, copy the Publishable key (starts pk_test_)." From cb7db0eeb6270b5534128dafcc1a59e3e7ab0472 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 6 Aug 2026 14:56:50 +0100 Subject: [PATCH 2/2] refactor(wizard): cut the no-ops about time estimates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Telling the agent not to give minutes, in a template that has no minutes, pays load to say nothing — and naming the banned behaviour makes it more available, not less. The absence does the work. - SKILL.md: drop the "never give a time estimate" paragraph and the "stage takes no duration" note; the example stage already shows it. - template.sh: drop the two comments about not printing minutes. - docs: drop the sentence about there being no estimate. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/wizard-no-minutes.md | 2 +- docs/engineering/wizard.md | 2 +- skills/engineering/wizard/SKILL.md | 4 +--- skills/engineering/wizard/template.sh | 7 +++---- 4 files changed, 6 insertions(+), 9 deletions(-) diff --git a/.changeset/wizard-no-minutes.md b/.changeset/wizard-no-minutes.md index e054ebc..9daf823 100644 --- a/.changeset/wizard-no-minutes.md +++ b/.changeset/wizard-no-minutes.md @@ -2,4 +2,4 @@ "mattpocock-skills": patch --- -wizard: never give a time estimate. The template drops `TOTAL_MINUTES` and the time-remaining display, `stage` takes a name only, and progress is counted in stages. +wizard: remove the time estimate. The template drops `TOTAL_MINUTES` and the time-remaining display, `stage` takes a name only, and progress is counted in stages. diff --git a/docs/engineering/wizard.md b/docs/engineering/wizard.md index a5eebe6..9918d28 100644 --- a/docs/engineering/wizard.md +++ b/docs/engineering/wizard.md @@ -25,7 +25,7 @@ None to generate one. The wizard it writes runs on bash, and uses `gh` when a st ## Stages -A **stage** is one focused task on one screen. The script clears the terminal between stages, so a stage that overflows the screen loses the part that scrolled away. You author stages in dependency order and set `TOTAL_STAGES`, which drives the progress display. There is no time estimate anywhere: progress is counted in stages, never in minutes. +A **stage** is one focused task on one screen. The script clears the terminal between stages, so a stage that overflows the screen loses the part that scrolled away. You author stages in dependency order and set `TOTAL_STAGES`, which drives the progress display. Scoping happens before a line is written. The [skill](https://www.aihero.dev/ai-coding-dictionary/skill) reads the repo instead of asking cold: `.env*`, `docker-compose*`, framework config, and every `secrets.*` / `vars.*` reference in `.github/workflows/` — each of those is a value the wizard has to produce. It then shows you the ordered stage list to confirm, and only after that maps each stage to the exact path a human follows ("Dashboard → Developers → API keys → Reveal test key → copy"). Where it doesn't know the current UI, it asks you or checks the docs rather than inventing clicks. diff --git a/skills/engineering/wizard/SKILL.md b/skills/engineering/wizard/SKILL.md index 7427b91..fdc2a72 100644 --- a/skills/engineering/wizard/SKILL.md +++ b/skills/engineering/wizard/SKILL.md @@ -7,8 +7,6 @@ description: Generate an interactive bash wizard that walks a human through step A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another. -**Never give a time estimate.** No minutes in the script, in the stage headers, or in what you tell the user — not for a stage, not for the wizard as a whole. Progress is measured in stages only. - The delightful UX is already solved by [template.sh](template.sh) — stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it. A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo. @@ -34,7 +32,7 @@ For each stage, write the precise path a human follows: which URL to open, what ### 3. Author the wizard -Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote (this drives the progress display). Give `stage` a name only; it takes no duration. +Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote. Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker. diff --git a/skills/engineering/wizard/template.sh b/skills/engineering/wizard/template.sh index feccfbc..e5b28ab 100644 --- a/skills/engineering/wizard/template.sh +++ b/skills/engineering/wizard/template.sh @@ -35,7 +35,7 @@ _clear() { if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi } -# banner "Title" — opening frame: what this wizard does. Never a time estimate. +# banner "Title" — opening frame: what this wizard does. banner() { _clear printf '\n%s%s %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET" @@ -46,8 +46,8 @@ banner() { pause "Ready to start?" } -# stage "Name" — clear the screen, then announce a stage and show progress as a -# stage count. Clearing keeps only the current step on screen. +# stage "Name" — clear the screen, then announce a stage and show progress. +# Clearing keeps only the current step on screen. stage() { _clear _STAGE_INDEX=$((_STAGE_INDEX + 1)) @@ -182,7 +182,6 @@ finish() { # ────────────────────────────────────────────────────────────────────────── # STAGES — author this section. One stage() per step the human takes. # Replace the example below. Set TOTAL_STAGES to match the stages you write. -# Never tell the human how many minutes anything takes. # ────────────────────────────────────────────────────────────────────────── TOTAL_STAGES=1