fix(han-core): give the pre-build ask its own turn - #213
Merged
Conversation
Issue #201 reports a pairing session that tucked the piece-3 pre-build ask under piece 2's stop, read "commit and next" as declining it, built piece 3 without the person's read, and wrote "ask declined" into the feedback record as the person's decision. The skill text permits it: the rule says the ask comes before the build and pairing Step 5 says "ask first", and neither forbids folding the ask into the previous stop. `docs/plans/gh-201-pre-build-ask-timing/` holds the change plan, its decision log, the current-state findings from a structural and behavioral discovery round, and the scope boundary. The plan re-scopes three sections of `collaborative-stop-rule.md` (and its two byte-identical copies), pairing Steps 5 and 6, and the pairing long-form doc, and pins every sentence the three files must agree on. Two behavior changes were put to the operator and accepted: the ask is a turn of its own that a stop never carries, and the record holds the person's words with the run's reading labeled as the run's. A review round with the junior developer, UX designer, and risk analyst extended the first change to a marked first piece, gave the ask's reply a recorded path, and named the run as the cause in the after-build message. Eight items sit under Deferred (YAGNI) with their reopening triggers.
Closes #201. The collaborative stop rule said the pre-build ask comes before the build and pairing Step 5 said "ask first", and neither forbade folding the ask into the tail of the previous piece's stop. A run did exactly that, read "commit and next" as declining the ask it had tucked under piece 2's stop, built piece 3 without the person's read, and wrote "ask declined" into the feedback record as the person's decision. `collaborative-stop-rule.md` now says a stop covers what just closed and asks nothing about a later piece; the ask is a turn of its own, opening the marked piece's turn after the person has replied to the previous stop or to the plan; a reply to a stop or the plan answers that alone and never counts as declining an ask the person has not answered; a question about the ask holds it open; a bundled ask was never posed and is presented on its own before building, and one found after the build is named with the run as the cause rather than re-asked. "Never require an answer before building" is gone, because the build now waits for a reply to the ask, though a decline is a full reply. The record's entry form is pinned: the person's words, the stop or ask they answered, and any reading the run adds labeled as the run's, with one worked example. The two vendored copies in `han-coding` and `han-planning` are byte-identical to the canonical file. Pairing Step 5 item 1 carries the same rule in the loop's terms and names what happens to the reply: recorded against the ask, then the build, with no pass through Step 6. Item 3 says naming the next concern is a report, never a question. Step 6 writes the response in the person's words against the stop or ask it answers. The long-form doc promises each of these to the person in the same terms and adds one turn per marked piece to its cost line. The change plan, decision log, and findings behind every sentence are under `docs/plans/gh-201-pre-build-ask-timing/`.
mxriverlynn
marked this pull request as ready for review
September 11, 2026 16:15
This was referenced Sep 11, 2026
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #201.
A pairing session tucked the piece-3 pre-build ask under piece 2's stop, read "commit and next" as declining it, built piece 3 without the person's read, and wrote "ask declined" into the feedback record as the person's decision. The skill text allowed it: the rule said the ask comes before the build and pairing Step 5 said "ask first", and nothing forbade folding the ask into the previous stop.
The ask is a turn of its own, and a stop never carries it
collaborative-stop-rule.mdnow says a stop covers what just closed and asks nothing about a later piece. The ask opens the marked piece's turn after the person has replied to the previous stop, or to the plan when the marked piece is the first, and it is the whole turn. A reply to a stop or the plan answers that alone and never counts as declining an ask the person has not answered. A question about the ask holds it open.The line "never require an answer before building" is gone. Read literally it licensed the build the issue reports. The build now waits for a reply to the ask, and a decline is a full reply: "I don't know" still advances the piece.
A bundled ask is an unanswered ask
When an earlier turn put the ask under a stop or the plan and the reply spoke only to that, the ask was never posed on its own, so the run presents it now, on its own, before building. If the piece was already built when that comes to light, the run says it put the ask under an earlier turn so it went unanswered, and continues from the stop in hand. It does not ask after the fact, because an ask after the build collects the cost and none of the benefit.
The record holds the person's words
The rule's "Recording what the person says" section pins the entry's form: the person's words, the stop or ask they answered, and any reading the run adds labeled as the run's, never written as what the person decided. One worked example pins the shape. An ask with no entry is an ask with no answer. This goes one step past the issue's suggested fix; the issue names the wrong record entry as a second effect, and the long-form doc already promised the record holds "which piece prompted it" with nothing delivering it.
What is in this PR
Two commits. The first adds the change plan, its decision log, the current-state findings from a structural and behavioral discovery round, and the scope boundary under
docs/plans/gh-201-pre-build-ask-timing/. The second applies the plan: five paragraphs in the canonical rule with its two vendored copies kept byte-identical, three edits topairing/SKILL.md(Step 5 item 1 rewritten with what happens to the ask's reply, one sentence on item 3, Step 6's opening sentence), and five edits tohan-core/docs/skills/pairing.mdso the doc promises exactly what the rule delivers, including one more turn per marked piece in its cost line.Every sentence the three files must agree on was pinned in the plan before it was written, and copied rather than paraphrased.
md5 -qprints one hash for all three rule copies.npm run lintandnpm testpass. The five backing skills are untouched: the one new clause they can act on sits in "What a stop presents", which they already read, and none of them poses an ask.Deliberately not in this PR
Eight items sit under Deferred (YAGNI) in the plan with reopening triggers, among them a three-state ask marker in the record, ask behavior inside a "show me the next three" batch, a piece anchor on the ask turn, and an acknowledgment on a re-presented ask. None is implicated by the one incident on record.
No ADR links the rule to the pairing plan's decision D7, which named the sentence this PR removes; the plan's decision D-3 records why it went. No version bump and no changelog edit; both belong to
/han-release.