pi-gauntlet 5.6.0 → 5.6.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v5.6.2 - 2026-09-17
+
+- `brainstorming`: the lookup rule distinguishes current-state facts (looked up) from decisions about what should happen (asked, even when a ticket recorded one earlier); the `Recommendation:` suffix binds questionary questions only, not the skill's git-state, design-round, or spec-gate approvals; the premise note may be questionary question one. Follow-ups from the #32 post-ship assessment. (#32)
+
+## v5.6.1 - 2026-09-17
+
+- `brainstorming`: the questionary looks up questions the code, docs, or issue tracker already answer instead of asking; every question it does ask ends with `Recommendation: <answer> - <why>` (including the ask to accept a corrected fact); before approaches, a plain-prose premise note in chat names which design-dependent claims the sources support, disprove (with the corrected fact and where), or leave unverified - a contradicted claim stops the flow until the user accepts the correction or explicitly overrides, with the outcome recorded in the draft. One checklist pointer, one Red Flags entry. (#32)
+- AGENTS core v4: exactness via the example, no inline SHAs, no spiderweb replies.
+
 ## v5.6.0 - 2026-09-16
 
 - `plan-tracker`: pending-suffix rule enforced at runtime - an `update` that would leave a `pending` task ahead of a started or finished one is rejected with a message naming every offending task, the legal fixes, and the current snapshot; state is unchanged and widget replay / `phase_tracker` ignore the rejection. `update` never sets `pending`. New terminal status `skipped` (`⊘`, not applicable in this run, counted done). `init` accepts `{ name, status }` elements (mixable with strings) to recreate a list with known statuses. Registered with sequential execution. Counts are labelled `done` (`complete + skipped`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.6.0",
+  "version": "5.6.2",
   "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

@@ -61,7 +61,8 @@ Work through the items below **in order**. This is your own checklist to follow,
    substep. Unconditional, foreground, no user interaction — the next thing the user
    sees is a questionary question. This produces the draft; the step below consumes it.
 4. **Understand the idea against the draft** — `Read` the draft, verify load-bearing
-   claims against real code, ask questions one at a time, append citable findings
+   claims against real code, ask questions one at a time, append citable findings;
+   then state the chat premise note (section 3) before approaches
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in two rounds, one approval each
 7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](#marking-superseded-specs), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
@@ -143,13 +144,33 @@ path.
   section starts that answer; confirm it before designing from scratch.
 - Ask questions **one at a time** to refine the idea. Prefer multiple-choice; one
   question per message. Focus on: purpose, constraints, success criteria, who/what
-  it touches.
+  it touches. Before asking, check whether the code, the docs, or the issue tracker
+  already answer it: a fact about the current state is looked up, not asked (dispatch
+  a subagent when the lookup is costly); a decision about what should happen is asked,
+  even when a ticket recorded one earlier. Every questionary question, including the
+  ask to accept a corrected fact, ends with the line `Recommendation: <answer> - <why>`
+  (the answer, then " - ", then the reason); approvals elsewhere in this skill (git
+  state, design rounds, the spec gate) keep their own wording.
 - **Append bar:** append to the draft's `## Appended during questionary` only
   findings the spec will cite — schema shapes, hard constraints, ticket-vs-code
   contradictions, user answers that changed scope. Not a log of every grep.
   (Appending uses `edit`; the `edit` prohibition in the spec-writing step applies
   only there.)
 
+Before proposing approaches, state the premise note in chat: what the design depends
+on, which of those claims the sources support and where you saw it (a file and line,
+a doc, a ticket), which they disprove - give the corrected fact and where you found
+it - and which remain unverified, naming the lookup you tried. Write it as a note a
+person can act on: full sentences, no status-keyword lists, no template; when the
+design depends on no claims at all, one sentence saying so is enough. An unverified
+claim is not a stop - it enters the spec as an Open Question or a stated assumption.
+If a claim the design depends on was contradicted, the note is your next message -
+even as questionary question one - and it ends by asking the user to accept the
+corrected fact or explicitly override it; nothing else continues - no other questions,
+no approaches - until they answer, and the outcome is recorded in the draft's
+`## Appended during questionary` so spec-writing carries it into `## Problem` or the
+relevant `## Design` decision.
+
 ### 4. Explore approaches
 
 - Propose 2-3 different approaches with trade-offs.
@@ -382,6 +403,7 @@ Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "c
 - Running, deploying, or validating the proposed change before approval.
 - Proceeding to `/skill:writing-plans` before the user approves the spec, or invoking `/skill:brainstorming` to amend an approved spec.
 - Writing a replacement spec without the known predecessor's banner, or offering a multi-spec split that fails `../shape-ticket/reference/split-axes.md`.
+- Proposing approaches while a contradicted claim is unresolved.
 
 ## Project overrides