fix(stagecraft): getting started and the authoring interview ask one question at a time (swamp-club #2950) #439

Merged

seth merged 1 commit from cue/2950-stagecraft-skill-getting into main

2026-10-02 15:40:23 +00:00

seth commented

2026-10-02 15:38:00 +00:00

Owner

Fixes swamp-club #2950.

The stagecraft getting-started walkthrough opened with a paragraph of concepts and a 7-item checklist, then asked five numbered questions in one message. The authoring interview did the same. Both now talk one question at a time. The states and what they produce are unchanged.

getting-started.md
- A "How to talk" section that holds in every state. Each turn has one question or one step, and each question says its default, so a short answer works. Each answer is said back in a line before the next question. The person is never shown a numbered list of questions.
- The first reply is two or three sentences, including one line naming the steps, then State 1's first question. This replaces the checklist.
- State 1 asks its questions one per turn, each with a default, and stops once there's enough to pick an example. A default the person did not change counts as their answer.
- The concepts paragraph is kept as background for the agent, not something to recite up front.
- States 4 and 7 each get one line so the studio walk and the next-step offer stay one per turn.
authoring.md State 1: the same rule. It skips anything already answered, and the "path to keep" prompt is an optional last question.

The eval case is not in this PR: #2912, the eval suite, was closed without being implemented. The case is handed to #2912 as a comment instead.

Acceptance transcript (first three turns)

Headless claude -p / --resume in a fresh repo (swamp init, then swamp extension source add of this branch), with this branch's skill copied in (diff -r showed it identical).

Turn 1, person: Set up a stagecraft factory for our post-incident reviews.

Agent:

Stagecraft is installed, and this repo doesn't have a factory yet, so let's set one up together. We'll go one step at a time: your review process, then the factory, a look at it in the studio, and a test run.

You've already told me what goes in and what comes out: an incident goes in, and a published post-incident review comes out. I'll start from stagecraft's incident-review template. It goes timeline → analysis → second-reader review → sign-off → publish.

Who does which parts of your reviews? If you don't say otherwise, I'll set it up this way:

An agent drafts the timeline and the analysis with whoever ran the incident.

A second agent challenges the analysis.

A person signs off on the action items before the review is published.

Turn 2, person: That's right, but the on-call lead signs off, not just anyone.

Agent:

Got it: agents draft and challenge the analysis, and the on-call lead signs off on the action items before anything is published. I'll name the on-call lead in the sign-off gate, and the record of each sign-off will say who gave it.

Is sign-off the only point where a person must decide? If you don't say otherwise, the on-call lead decides in two places: signing off before publishing, and confirming before a review is dropped. Nothing else waits for a person.

Turn 3, person: Published means it's posted on the internal wiki.

Agent:

Done means the review is posted on the internal wiki, and the publish step will record its wiki link. You didn't change the decision points, so the on-call lead decides in two places: sign-off before publishing, and confirming before a review is dropped.

What sends a review back for more work? If you don't say otherwise:

When the second reader finds a serious problem (the cause is wrong, a factor that would let the incident happen again is missing, or someone is blamed), the analysis goes back to be fixed.

The on-call lead can also send it back at sign-off, with written feedback.

After three rounds of analysis, the on-call lead decides whether another round is worth it.

Verification

verify-build 0439ac96-ff07-40ae-b09f-121c76f860f2 and verify-reviews da93d6eb-77a3-4413-a55c-6de91fba465b passed on 23e43a5e7: 12 steps passed and 2 were skipped by their guards (codegen idempotency, ci-security-review). code-review and adversarial-review both passed.

🤖 Generated with Claude Code

Fixes swamp-club #2950. The stagecraft getting-started walkthrough opened with a paragraph of concepts and a 7-item checklist, then asked five numbered questions in one message. The authoring interview did the same. Both now talk one question at a time. The states and what they produce are unchanged. - **getting-started.md** - A "How to talk" section that holds in every state. Each turn has one question or one step, and each question says its default, so a short answer works. Each answer is said back in a line before the next question. The person is never shown a numbered list of questions. - The first reply is two or three sentences, including one line naming the steps, then State 1's first question. This replaces the checklist. - State 1 asks its questions one per turn, each with a default, and stops once there's enough to pick an example. A default the person did not change counts as their answer. - The concepts paragraph is kept as background for the agent, not something to recite up front. - States 4 and 7 each get one line so the studio walk and the next-step offer stay one per turn. - **authoring.md State 1:** the same rule. It skips anything already answered, and the "path to keep" prompt is an optional last question. The eval case is not in this PR: #2912, the eval suite, was closed without being implemented. The case is handed to #2912 as a comment instead. ## Acceptance transcript (first three turns) Headless `claude -p` / `--resume` in a fresh repo (`swamp init`, then `swamp extension source add` of this branch), with this branch's skill copied in (`diff -r` showed it identical). **Turn 1, person:** Set up a stagecraft factory for our post-incident reviews. **Agent:** > Stagecraft is installed, and this repo doesn't have a factory yet, so let's set one up together. We'll go one step at a time: your review process, then the factory, a look at it in the studio, and a test run. > > You've already told me what goes in and what comes out: **an incident goes in, and a published post-incident review comes out.** I'll start from stagecraft's incident-review template. It goes timeline → analysis → second-reader review → sign-off → publish. > > **Who does which parts of your reviews?** If you don't say otherwise, I'll set it up this way: > - An agent drafts the timeline and the analysis with whoever ran the incident. > - A second agent challenges the analysis. > - A person signs off on the action items before the review is published. **Turn 2, person:** That's right, but the on-call lead signs off, not just anyone. **Agent:** > Got it: agents draft and challenge the analysis, and **the on-call lead** signs off on the action items before anything is published. I'll name the on-call lead in the sign-off gate, and the record of each sign-off will say who gave it. > > **Is sign-off the only point where a person must decide?** If you don't say otherwise, the on-call lead decides in two places: signing off before publishing, and confirming before a review is dropped. Nothing else waits for a person. **Turn 3, person:** Published means it's posted on the internal wiki. **Agent:** > Done means **the review is posted on the internal wiki**, and the publish step will record its wiki link. You didn't change the decision points, so the on-call lead decides in two places: sign-off before publishing, and confirming before a review is dropped. > > **What sends a review back for more work?** If you don't say otherwise: > - When the second reader finds a serious problem (the cause is wrong, a factor that would let the incident happen again is missing, or someone is blamed), the analysis goes back to be fixed. > - The on-call lead can also send it back at sign-off, with written feedback. > - After three rounds of analysis, the on-call lead decides whether another round is worth it. ## Verification verify-build `0439ac96-ff07-40ae-b09f-121c76f860f2` and verify-reviews `da93d6eb-77a3-4413-a55c-6de91fba465b` passed on `23e43a5e7`: 12 steps passed and 2 were skipped by their guards (codegen idempotency, ci-security-review). code-review and adversarial-review both passed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 1 commit

2026-10-02 15:38:00 +00:00

fix(stagecraft): getting started and the authoring interview ask one question at a time (swamp-club #2950 )

CI / Review Integrity (pull_request) Successful in 48s

Details

CI / Validate Attestation (pull_request) Successful in 1m3s

Details

23e43a5e7d

The walkthrough opened with a concepts paragraph and a 7-item checklist,
then asked five numbered questions in one message; the authoring interview
did the same. Both now ask one question per turn, each with its default,
say each answer back before the next, and never show a numbered list of
questions. The first reply is two or three sentences and the first question.
A default the person did not change counts as their answer, so the agent
can stop asking once it has enough. States and what they produce are
unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth merged commit d0b460c46c into main

2026-10-02 15:40:23 +00:00

seth deleted branch cue/2950-stagecraft-skill-getting

2026-10-02 15:40:23 +00:00

seth referenced this pull request from a commit

2026-10-02 15:40:24 +00:00

fix(stagecraft): getting started and the authoring interview ask one question at a time (swamp-club #2950) (#439)