diff --git a/.claude/skills/workshop-start/IMPROVEMENTS.md b/.claude/skills/workshop-start/IMPROVEMENTS.md new file mode 100644 index 000000000..d36eb25d0 --- /dev/null +++ b/.claude/skills/workshop-start/IMPROVEMENTS.md @@ -0,0 +1,87 @@ +# workshop-start — Improvement Log + +Running notes on friction and fixes observed while running workshops. Fold the +confirmed ones into `SKILL.md` periodically; delete once applied. + +## From the `system-economic-specialization` relaunch (2026-05-31) + +- **Tool name drift.** SKILL.md §5 says "Use the **Task tool** to spawn each + agent." The actual spawn tool is **`Agent`** (with `team_name` + `name` + + `subagent_type`). "Task" reads as the TaskCreate/TaskUpdate family and is + misleading. Rename to "Agent tool" throughout §5. + +- **SI has no Round 1 work — say so.** The skill adds SI to every workshop but + SI's job is Round 2 ticket creation. Round 1 there is no SI task, so SI sits + with an empty TaskList and no instruction. Recommend the skill explicitly note: + "SI joins on standby; SI gets no task until Round 2 — spawn it in background + with a 'load context and wait for Round 2' prompt." Avoids an idle/confused + agent on spawn. + +- **Spawn order vs. task creation.** Following the skill literally (§4 create + tasks → §5 spawn) matters: if you spawn agents before the tasks exist, they + check TaskList, find nothing, and may idle. Worth a one-line warning in §5: + "Create and assign all Round 1 tasks BEFORE spawning, or the agents wake to an + empty list." (Recoverable by messaging them after, but cleaner to order it + right.) + +- **`TaskCreate` is one-task-per-call.** No batch/array form. A batch attempt is + rejected. The skill could state this so the lead emits N separate TaskCreate + calls (and assigns owners via TaskUpdate, since TaskCreate takes no `owner`). + +- **Read-only participants can't write their own files.** Several workshop agent + types (paula, gore, nigel, ozzie, and the read-only miri variant) have NO Write + tool — yet SKILL.md §4 makes "write your full output to disk" a hard + requirement for every participant. Paula hit this: she produced her full Round 1 + doc but had to send it to the lead to write `paula-round1.md`. The skill should + state up front: "Participants without a Write tool deliver their output via + SendMessage; the lead writes the file and marks the task complete on their + behalf." Or: assign a write-capable scribe. Either way, don't make disk-write a + per-agent requirement for read-only agent types — it guarantees a manual relay. + +- **Participants self-claim, which races owner assignment.** Paula picked up + task #3 on her own before the lead assigned owners. Harmless here, but if tasks + aren't clearly scoped per-agent an agent could grab the wrong one. The skill's + per-agent task titles ("Round 1 — Miri …") mitigate this; keep titles + agent-named. + +## Candidate feature — per-round "scout" critic (user idea, 2026-05-31) + +Add an optional independent **scout** agent that runs per round, AFTER the round's +output files land and BEFORE the user checkpoint, to surface missed options, +simpler designs, internal contradictions, and external design prior-art. + +- **Value is mostly the independent adversarial review**, not the web. Participants + build on each other and converge; a fresh agent with no stake catches blind + spots convergence hides. Web search is a bonus, useful for the *mechanism* (real + economic geography, how other games encode X, schema-granularity tradeoffs) — + NOT the lore. +- **Hard guardrails:** (1) lore is authored-canonical and fictional — the scout must + NOT "correct" the fiction with real-world/web facts; scope web to design/mechanism + prior-art only. (2) Only surface findings that would CHANGE a decision — a critic + that always finds 10 things gets ignored. +- **Shape:** cheap model (Haiku), `run_in_background: true`, reads the round files + + relevant D-records, writes `scout-round{N}.md`. Lead folds decision-changing items + into the checkpoint presented to the user. Escalate to Sonnet only to dig into a + real find. +- Pairs well with the quality-over-scope-creep principle: the scout is a cheap way + to pressure-test that "quality" claims actually hold and nothing simpler was missed. + +## Wrap-up gotchas (2026-05-31) + +- **`decision claim` is NOT idempotent.** Each call burns the next ID and appends a + placeholder. Retrying it (e.g. after misreading an unrelated error) creates a + DUPLICATE record that must be hand-removed before filing. Before re-running claim, + check `decision next D` / grep the domain file. The wrap-up step should claim each + ID exactly once and record it immediately. +- **Read-only documenter can still file**, but the lead must hand it the exact ID(s) + and the "remove any stray placeholder" instruction — the claim/file split is where + duplicate IDs sneak in. +- **Background (`run_in_background`) teammates can be slow/unreliable to consume + `shutdown_request`.** At wrap-up, qatux + si (both spawned in background per the + skill's §5 guidance) stayed "active" through multiple shutdown sends, blocking + TeamDelete. Foreground participants shut down immediately. Options to fold into + the skill: (a) don't background the always-present agents, or (b) document that + wrap-up may need several shutdown retries / a longer settle, and that the lead + should not spin indefinitely — the work is already on disk, TeamDelete is just + resource cleanup. Consider whether the skill should note the team can be left to + expire rather than blocking the session on cleanup.