pi-gauntlet 8.4.7 → 8.4.8

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v8.4.8 - 2026-11-11
+
+- Brainstorming opens with Today, The change, and What I checked in everyday words, followed by one question. Sources stay in the draft; the opening span is capped at 220 words except corrected or unchecked claims and intact quoted ticket rows.
+
 ## v8.4.7 - 2026-11-11
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "8.4.7",
+  "version": "8.4.8",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -95,7 +95,7 @@ Clarify freely. For a PR subject, run the framing check against the PR's diff as
 
 `Read` the gathered draft unconditionally before question one. Treat it as a helper, not a fence: verify load-bearing claims from primary code, and confirm whether the codebase or ecosystem already solves the problem.
 
-Ask one question per message, about purpose, constraints, success, and affected actors. Offer 2-4 labeled options (`A)`, `B)`, ...) for every questionary question, each a different outcome. Put the lead-in before the first option, each labeled option on its own physical line, and `Recommendation: <letter> - <why>` on its own final line; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. Use this one-option-per-line layout even when chat-style rules in `AGENTS.md` require one paragraph or no Options/Recommendation layout. A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and cite the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
+Ask one question per message, about purpose, constraints, success, and affected actors. Offer 2-4 labeled options (`A)`, `B)`, ...) for every questionary question, each a different outcome. Put the lead-in before the first option, each labeled option on its own physical line, and `Recommendation: <letter> - <why>` on its own final line; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. Use this one-option-per-line layout even when chat-style rules in `AGENTS.md` require one paragraph or no Options/Recommendation layout. A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and attribute it to the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
 
 Bad: `May I treat those two acceptance criteria as location-only deviations? Recommendation: yes`
 Good:
@@ -108,37 +108,18 @@ C) the existing skill step.
 Recommendation: A - the extension already holds the poll loop, so no new entrypoint.
 ```
 
-Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
+Before sending the opening message, append every checked claim, held ones included, with its source, the lookup, and the result, together with schemas, hard constraints, contradictions, and scope-changing answers, using `edit`: to `## Appended during questionary` when the draft is the gather draft; directly to `## Problem` when it is the approved or carried spec (redraw or the unmarked spec-only PR route), where gather is skipped and that section does not exist.
 
-Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups, in full sentences - no status-keyword lists, no template; if the design depends on no claims, one sentence says so. Treat an implicit dependency found missing as a corrected premise and one not checkable as unverified; state each in the premise note with the lookup the repo or spec names and its result, and carry it into `## Problem`. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and states the corrected fact with its source; the design continues on it and the user overrides in reply. Record the corrected fact, and any override, in the draft for `## Problem` or the relevant design decision.
+Before approaches, state in chat the supported, disproved, corrected, and unverified premises in the opening message's `## What I checked` section: supported renders as `Held:`, disproved and corrected as `Corrected:`, and unverified as `Not checked:`; that section is the premise note, and after the opening message a premise note is a `Corrected:` line. Treat an implicit dependency found missing as a corrected premise and one not checkable as unverified; state each in the premise note in everyday words that name what was looked at and what was found; record the lookup the repo or spec names and its result in the draft, and carry it into `## Problem`. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and states the corrected fact; the design continues on it and the user overrides in reply. Record the corrected fact, and any override, in the draft for `## Problem` or the relevant design decision; spec-writing carries every recorded claim, held ones included, into `## Problem`.
 
-Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name, including retained loaders and every repro and verification step's implicit dependencies, before writing the holds-statement or the question; check those dependencies with the lookup the repo or spec names, and name the traces and dependencies in the holds-statement, not only the files read. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question in the questionary format:
+Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name, including retained loaders and every repro and verification step's implicit dependencies, before writing the holds-statement or the question; check those dependencies with the lookup the repo or spec names, and record the traces and dependencies in the draft through the evidence write above. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question; without a concern, the message carries the holds-statement and the first ordinary question.
 
-```text
-gauntlet: question
-A) as framed
-B) pivot: <named alternative> - <cited reason>
-C) smaller or none: <what ships, or what happens if nothing ships>
-Recommendation: <letter> - <why>
-```
-
-For a band-aid concern, put the root-cause alternative in B. Without a concern, follow the marker with one sentence naming what was checked - `The framing holds: checked <x>, <y>` - and continue to the first ordinary question; a scout objection that yielded no alternative is named among the things checked.
+Read [Opening message](reference/opening-message.md) now and write question one's message against it; unreadable -> stop with a blocking error, never write it from memory.
 
 After any premise correction in the same message, ask the framing question or give the holds-statement. Ask the framing question at most once per brainstorm, including after pushback; the user's reply is final, and later doubts on the same point go to Open Questions or a `Pattern:` line. Recommend; never pivot without the reply. A ticket-recorded decision on the exact point follows the ticket rule above; an adopted decision records `Framing: kept (ticket <id>)`. A pivot never rewrites AC rows: rows it no longer satisfies take `deviates:` dispositions, and a pivot that changes the topic re-mints the slug.
 
 Record the outcome in the draft under `## Appended during questionary` as `Framing: kept` or `Framing: pivoted to <x> - <why>`; spec-writing carries that line into `## Problem`. On redraw entry (checklist step 4) the count restarts: run this evaluation once against the new draft. On redraw the draft is the approved spec: its `## Problem` `Framing:` line is context, not scout evidence, and the new outcome is recorded directly in `## Problem`. When the scout failed there is no `Framing:` line; supply the implicit-dependency check and the holds-statement or question from your own recon.
 
-Bad: `The ask adds another settings path - should we? Recommendation: no`
-Good:
-```text
-gauntlet: question
-The ask adds a second settings path beside the resolver that already owns every setting (settings/resolver.ts:11).
-A) as framed
-B) pivot: a key under the existing resolver - one read path, no new boundary
-C) smaller or none: document the default and ship no setting.
-Recommendation: B - the owning schema already exists.
-```
-
 ### 4. Explore approaches
 
 In a separate message after the premise note, restate each implicit dependency recorded as missing or not checkable, with its lookup and result, before presenting any approaches.

package/skills/brainstorming/reference/opening-message.md

@@ -0,0 +1,96 @@
+# Opening message
+
+Use this wording for question one's message at checklist step 4, including fresh, redraw, restored, and unmarked spec-only PR entry. Apply [Menu layout](menu-layout.md) for the first-line rule. The relatedness question before provisioning belongs to `pr-subject.md`.
+
+## Shape
+
+```text
+gauntlet: question
+
+## Today
+<how the affected part works now>
+
+## The change
+<what the request does to it, as something the user observes>
+
+## What I checked
+- Held: <one short sentence naming the held claims by role>
+- Corrected: <the claim as stated>; <the fact>, so <the consequence for the design>.
+- Not checked: <the claim> - <why it could not be checked>, so <what the design assumes or waits on>.
+
+The framing holds: checked <things, named by what they do>.
+<lead-in question>
+A) <outcome>
+B) <outcome>
+Recommendation: <letter> - <why>
+```
+
+Keep the three titles in that order, with a blank line between sections. Give each body one short paragraph or one list. Use `##`: pi renders it as a bold title, while `###` keeps its hashes.
+
+| Section | Write |
+|---|---|
+| `## Today` | Summarize how the affected part behaves now in one to three present-tense sentences total, combining related behaviors within a sentence. For a PR subject describe the PR's current state; on a redraw, the approved spec. |
+| `## The change` | Write one to three sentences total about the changes the user observes once it ships; fit related outcomes and any stated assumption into those sentences. Put the held claims' consequence for the design here, not on the `Held:` line. For a ticket request, say what the ticket asks, without listing acceptance rows. Put an assumption made in place of a yes/no question last. |
+| `## What I checked` | Group the held claims by role in one short `Held:` sentence; keep per-claim evidence in the draft. Give each corrected premise one `Corrected:` line stating the fact and its consequence for the design. Give each unverified premise, and a ticket gather could not fetch, one `Not checked:` line with the reason and what the design assumes or waits on. Use SKILL.md's premise paragraph to classify them. Omit labels with no entry. With no claims, write only `The design rests on no claims.` |
+
+For a request that is only an unread ticket reference, make `## Today` and `## The change` one sentence each saying their content is not known until the ticket's content is supplied. Infer neither current behavior nor the requested change from the reference or repo recon. Keep the `Not checked:` line, the framing line, and the usual question slot; name the failed ticket fetch among the things checked in `The framing holds: checked ...`.
+
+## Words and length
+
+Name each part by what it does. Use a literal name when the user used it in the request or when it is the finding itself: a missing file, a failing input, a quoted ticket row. Name a lookup by what was looked at, such as `the supplied templates/ directory listing`. Keep file-and-line references, commit ids, tracker ids, and trace counts in the draft. Use a tracker id only inside a command option such as `/skill:shape-ticket <ref>`, even when the user typed it; elsewhere, including an unfetched-ticket line, say `the ticket`, and render a lettered option with an unsupplied destination as a request to name that destination.
+
+Keep at most 220 words from the `## Today` line through the line before the first lettered option, both included. Exclude the marker and options. Count whitespace-delimited tokens containing a letter or digit: titles and labels count; `##` and `-` do not. Over the cap, cut `## Today` and `## The change` to one sentence each; keep `Held:` to its one short sentence. Only `Corrected:` lines, `Not checked:` lines, and an intact quoted ticket row in the question may then carry the message past 220: none of them is dropped, and the row stays intact.
+
+## Framing and question
+
+Write `The framing holds: checked <x>, <y>` with the checked things named by role, including a scout objection that yielded no alternative. For a concern, replace that line with the concern in one sentence, then offer `A) as framed`, `B) pivot: <named alternative> - <reason in everyday words>`, and `C) smaller or none: <what ships, or what happens if nothing ships>`, ending with `Recommendation: <letter> - <why>`. Put the root-cause alternative in B for a band-aid concern.
+
+Use the question slot for one question: the framing question with a concern, otherwise the first ordinary question. Apply [Ticket acceptance - Cut question](ticket-acceptance.md#cut-question) and its trigger table for which question comes first, when a cut question takes the slot, and how its row is quoted.
+
+Render the sections from the recon at hand; give anything it could not check a `Not checked:` line. Leave scout-failure flow to SKILL.md's `Framing:` record paragraph.
+
+Open the next message after a later correction with one `Corrected:` line under the same register, with no section titles: the first line, or directly after the marker when the message has one.
+
+## Worked examples
+
+Holds:
+
+```text
+gauntlet: question
+
+## Today
+The export uses the saved column order for every download.
+
+## The change
+Users can choose a different order for one download. The saved order remains the default, so existing downloads stay the same.
+
+## What I checked
+- Held: The export reads the saved order, and the download form can pass a different order.
+
+The framing holds: checked the saved order and the download form.
+Where should users choose the order?
+A) in the download form
+B) in a separate preview
+Recommendation: A - users can choose without leaving the download.
+```
+
+Concern:
+
+```text
+gauntlet: question
+
+## Today
+Every caller reads settings through the same resolver.
+
+## The change
+The request adds another settings file to supply a timeout override.
+
+## What I checked
+- Corrected: The draft says the resolver cannot accept overrides; it already accepts a timeout override, so the caller can pass it without another settings file.
+
+Another settings file duplicates the existing read path. Which outcome should we pursue?
+A) as framed
+B) pivot: pass the override through the existing resolver - it already supports it
+C) smaller or none: document the default and ship no setting
+Recommendation: B - the existing resolver can handle the override.
+```