pi-gauntlet 6.1.0 → 6.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/README.md +5 -5
- package/package.json +1 -1
- package/skills/brainstorming/SKILL.md +34 -173
- package/skills/brainstorming/gatherer.md +3 -2
- package/skills/brainstorming/reference/amendment-surface.md +9 -3
- package/skills/brainstorming/reference/documentation-impact.md +4 -2
- package/skills/brainstorming/reference/spec-finalization.md +128 -0
- package/skills/brainstorming/reference/ticket-acceptance.md +18 -0
- package/skills/chase-bug/SKILL.md +2 -2
- package/skills/gauntlet-resume/SKILL.md +2 -2
- package/skills/gauntlet-resume/reference/reconstruction.md +6 -3
- package/skills/writing-plans/SKILL.md +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v6.2.1 - 2026-10-01
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- **Brainstorming entry is explicit opt-in.** `/skill:brainstorming` is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. Ordinary implementation requests and agent recommendations do not authorize tracker resets or worktree creation. Enforcement starts once opted in, and spec approval still automatically chains into planning and implementation.
|
|
8
|
+
- **Brainstorming instructions are shorter without dropping workflow rules.** Ticket handling and spec finalization now have two required-read reference owners; the main skill keeps entry consent, questionary, and named entry points. Existing ticket dispositions, critique verdict branches, summary degradation, approval, and amend/redraw contracts remain in place.
|
|
9
|
+
|
|
10
|
+
## v6.2.0 - 2026-09-30
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- Brainstorming questionary questions offer 2-4 labeled options and end `Recommendation: <letter> - <why>`; this format overrides `AGENTS.md` chat-style rules. Would-be yes/no or "may I" decisions are made and stated as assumptions instead of asked. A contradicted load-bearing premise is stated with its source and the design continues on it (the user overrides in reply) rather than blocking on accept-or-override. `deviates:`/`deferred:` dispositions are asked only when they change what the user observes post-ship, with the dispositions as the options; ticket-recorded decisions are adopted and cited unless a cited contradiction prevents it. Supersedes the gh-32 spec's accept-or-override and ask-even-when-ticket-recorded clauses.
|
|
15
|
+
|
|
3
16
|
## v6.1.0 - 2026-09-30
|
|
4
17
|
|
|
5
18
|
### Changed
|
package/README.md
CHANGED
|
@@ -36,7 +36,7 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
|
|
|
36
36
|
Concretely, one change through the gauntlet:
|
|
37
37
|
|
|
38
38
|
0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write that may include one optional gated Reporter-note comment. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. It never activates on its own (`disable-model-invocation: true`) - invoke it explicitly. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
|
|
39
|
-
1.
|
|
39
|
+
1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`), the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows after deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** No implementation code exists yet.
|
|
40
40
|
2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
|
|
41
41
|
3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor. Independent implementation, review, and council batches remain parallel, but their dispatches are foreground: the orchestrator waits for terminal results before accepting work or advancing a phase.
|
|
42
42
|
4. **verify**: the parent first runs the plan's full verification command set; only a passing result permits whole-diff code review, then the **conformance gate**. A review fix invalidates that result, so the parent reruns full verification before the next review or conformance gate. When the overrides file declares a happy path for the touched paths (see [Project-specific overrides](#project-specific-overrides)), the parent runs it once here, between code review and the conformance gate, and the reviewer reads its transcript as runtime evidence - a hang or a failed request shows up in the audit with the transcript quoted - as a gap when an origin clause ties to it, otherwise as a `happy-path: failed - unattributable` line - never as a silent green. The conformance subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Unauthorized rows - shipped surface no human input asked for, whether it crept in or was laundered through the spec - follow their recommendation like every other row: a contained removal auto-runs, anything another requirement leans on is deferred with a plain-language "I'd cut it / I'd keep it" recommendation. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
|
|
@@ -48,7 +48,7 @@ Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive
|
|
|
48
48
|
```mermaid
|
|
49
49
|
flowchart LR
|
|
50
50
|
T["shape-ticket<br/>(optional, explicit)"]
|
|
51
|
-
R([
|
|
51
|
+
R([explicit opt-in]) --> B[brainstorm<br/>+ spec]
|
|
52
52
|
T -.-> R
|
|
53
53
|
B --> G1{{human gate 1:<br/>approve spec}}
|
|
54
54
|
G1 --> P[plan]
|
|
@@ -69,11 +69,11 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
|
|
|
69
69
|
|
|
70
70
|
pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
|
|
71
71
|
|
|
72
|
-
- **20 skills** - the workflow logic.
|
|
72
|
+
- **20 skills** - the workflow logic. Twelve activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Eight more require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
|
|
73
73
|
- **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
|
|
74
74
|
- **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept untracked and git-excluded until `finishing-a-development-branch` seals and commits it once with `gauntlet-telemetry-seal` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
|
|
75
75
|
|
|
76
|
-
pi-gauntlet is **opinionated**:
|
|
76
|
+
pi-gauntlet is **opinionated**: it recommends this pipeline for non-trivial changes, but starts `brainstorming` only after explicit user consent. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
|
|
77
77
|
|
|
78
78
|
**Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31; a plain (non-colocated) jj workspace has no `.git`, so the resolver falls back to `jj root` there, reading primary-vs-workspace from `.jj/repo` (a directory in the primary checkout, a pointer file in added workspaces).
|
|
79
79
|
|
|
@@ -106,7 +106,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
|
|
|
106
106
|
|
|
107
107
|
## When to use / when NOT to use
|
|
108
108
|
|
|
109
|
-
**Use it** for any change with more than one moving part: a feature, a refactor across files, anything where "what did we actually agree to build" matters by the time it's done.
|
|
109
|
+
**Use it** for any change with more than one moving part: a feature, a refactor across files, anything where "what did we actually agree to build" matters by the time it's done. Start with `/skill:brainstorming`; a request to implement the change alone does not opt you in.
|
|
110
110
|
|
|
111
111
|
**Don't use it** for a one-line fix, a typo, or a throwaway spike you're going to discard. The gates have real overhead - a spec, a plan, a conformance check - and that overhead isn't worth paying for a change trivial enough to just make. Between that carve-out and the full pipeline sits one middle tier: `chase-bug`'s hotfix row - a small, evidenced, urgent fix landed as an unpushed squash, entered only through the triage verdict menu.
|
|
112
112
|
|
package/package.json
CHANGED
|
@@ -1,17 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: brainstorming
|
|
3
|
-
description: "
|
|
3
|
+
description: "Use only when the user explicitly requests brainstorming or selects a handoff into it."
|
|
4
|
+
disable-model-invocation: true
|
|
4
5
|
---
|
|
5
6
|
|
|
6
|
-
> **Related skills:** Use `/skill:using-git-worktrees` **before** writing the spec — the spec is the worktree's first artifact. Then `/skill:writing-plans` for implementation planning.
|
|
7
|
-
|
|
8
7
|
# Brainstorming Ideas Into Designs
|
|
9
8
|
|
|
10
9
|
## Overview
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
Identify the target project → set up an isolated worktree → understand current project context → ask questions one at a time → propose 2-3 approaches with trade-offs → present the design in two rounds → write spec to disk inside the worktree → user reviews before any implementation.
|
|
11
|
+
Collaborate on designs.
|
|
15
12
|
|
|
16
13
|
## HARD CONSTRAINT
|
|
17
14
|
|
|
@@ -27,11 +24,17 @@ The line: current-system observation is research; exercising the proposed change
|
|
|
27
24
|
|
|
28
25
|
Set top-level `async: false` on every flow-owned dispatch and leave `forceTopLevelAsync` unset or false. If a dispatch still returns an async handle, stop and report; do not poll, relaunch, or advance. A detached child is incomplete work: use the existing coordination path, never accept or duplicate it. Preserve independent parallel `tasks` batches and await all terminal results before acceptance or tracker/phase advancement.
|
|
29
26
|
|
|
27
|
+
## Entry consent
|
|
28
|
+
|
|
29
|
+
Start fresh only on `/skill:brainstorming`, explicit prose requesting brainstorming/the gauntlet, or a human-selected handoff. Ordinary implementation requests, discussion about usefulness, and recommendations are not consent: wait for explicit choice before reset or worktree creation.
|
|
30
|
+
|
|
31
|
+
Treat the flag as discovery control, not harness authorization. The command reliably discovers this skill; honor prose when already loaded or identified by an available route, never promise otherwise unreachable prose discovery. Continue restored state and amend/redraw at their named steps without fresh entry.
|
|
32
|
+
|
|
30
33
|
## Checklist
|
|
31
34
|
|
|
32
35
|
Work through the items below **in order**. This is your own checklist to follow, not a `plan_tracker` plan — brainstorming is open-ended exploration, and `plan_tracker` is execution-only (the implement phase). The terminal state is the user review gate; after approval the **only** next skill is `/skill:writing-plans`. Do not jump to implementation, and do not silently drop the critique pass.
|
|
33
36
|
|
|
34
|
-
1. **Start brainstorm tracking (fresh epoch)** - as the first action on entry, before reading code, the worktree, or answering the user, reset both trackers and start the phase. A new brainstorm owns a clean slate, so stale phases and tasks from earlier work are cleared; re-entering mid-brainstorm is safe (nothing to lose, same clean slate):
|
|
37
|
+
1. **Start brainstorm tracking (fresh epoch)** - as the first action on authorized fresh entry, before reading code, the worktree, or answering the user, reset both trackers and start the phase. A new brainstorm owns a clean slate, so stale phases and tasks from earlier work are cleared; re-entering mid-brainstorm is safe (nothing to lose, same clean slate):
|
|
35
38
|
|
|
36
39
|
```
|
|
37
40
|
phase_tracker({ action: "reset" }) // clears all phases
|
|
@@ -40,13 +43,13 @@ Work through the items below **in order**. This is your own checklist to follow,
|
|
|
40
43
|
```
|
|
41
44
|
|
|
42
45
|
2. **Set up the worktree** - see [Worktree First](#worktree-first).
|
|
43
|
-
3. **Gather context** - follow [`gatherer.md`](gatherer.md) without a human stop.
|
|
44
|
-
4. **Understand the idea against the draft** - see [Understand the idea](#3-understand-the-idea).
|
|
46
|
+
3. **Gather context** - read [Ticket Handling](#ticket-handling), then follow [`gatherer.md`](gatherer.md) without a human stop.
|
|
47
|
+
4. **Understand the idea against the draft** - read [Ticket Handling](#ticket-handling), then see [Understand the idea](#3-understand-the-idea).
|
|
45
48
|
5. **Propose 2-3 approaches** - see [Explore approaches](#4-explore-approaches).
|
|
46
49
|
6. **Present the design** - see [Present the design in two rounds](#6-present-the-design-in-two-rounds).
|
|
47
|
-
7. **Write the spec** -
|
|
48
|
-
8. **Spec self-review (lint)** - run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
|
|
49
|
-
9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council
|
|
50
|
+
7. **Write the spec** - read [Spec Self-Review](#spec-self-review-before-user-review-gate) before writing; follow steps 1-5.
|
|
51
|
+
8. **Spec self-review (lint)** - read [Ticket Handling](#ticket-handling), then run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
|
|
52
|
+
9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council).
|
|
50
53
|
10. **Re-run placeholder scan** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate).
|
|
51
54
|
11. **Generate spec summary** - follow [User Review Gate](#user-review-gate).
|
|
52
55
|
12. **User review gate** - follow [User Review Gate](#user-review-gate).
|
|
@@ -62,9 +65,7 @@ Detection order: (1) infer from ticket labels, description, or paths; (2) use th
|
|
|
62
65
|
|
|
63
66
|
The spec is the first commit in a dedicated worktree, never a separate commit on `main`.
|
|
64
67
|
|
|
65
|
-
|
|
66
|
-
2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
|
|
67
|
-
3. Write, review, and commit there.
|
|
68
|
+
Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
|
|
68
69
|
|
|
69
70
|
Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals and commits the record before landing. Explicit trivial one-off edits outside this flow need no worktree.
|
|
70
71
|
|
|
@@ -86,13 +87,18 @@ If any test fails, offer no split. Never split by service, package, repo, layer,
|
|
|
86
87
|
|
|
87
88
|
### 3. Understand the idea
|
|
88
89
|
|
|
90
|
+
Clarify freely.
|
|
91
|
+
|
|
89
92
|
`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.
|
|
90
93
|
|
|
91
|
-
Ask one question per message,
|
|
94
|
+
Ask one question per message, about purpose, constraints, success, and affected actors. Every questionary question offers 2-4 labeled options (`A)`, `B)`, ...), each a different outcome, and ends `Recommendation: <letter> - <why>`; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. This format overrides chat-style rules in `AGENTS.md` (one paragraph, 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.
|
|
95
|
+
|
|
96
|
+
Bad: `May I treat those two acceptance criteria as location-only deviations? Recommendation: yes`
|
|
97
|
+
Good: `The two ACs name a path that moved; the spec marks them deviates: location only. Which surface owns the refresh? A) the extension B) a new bin C) the existing skill step. Recommendation: A - the extension already holds the poll loop, so no new entrypoint.`
|
|
92
98
|
|
|
93
99
|
Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
|
|
94
100
|
|
|
95
|
-
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. 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
|
|
101
|
+
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. 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.
|
|
96
102
|
|
|
97
103
|
### 4. Explore approaches
|
|
98
104
|
|
|
@@ -104,37 +110,11 @@ Prefer clear testable boundaries, YAGNI, existing conventions, the owning schema
|
|
|
104
110
|
|
|
105
111
|
### 6. Present the design in two rounds
|
|
106
112
|
|
|
107
|
-
Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by
|
|
108
|
-
|
|
109
|
-
`## Documentation impact` is required. Cite `reference/documentation-impact.md` by relative path, do not restate its categories, and reproduce this template verbatim:
|
|
110
|
-
|
|
111
|
-
```markdown
|
|
112
|
-
## Documentation impact
|
|
113
|
-
- Feature / user-facing docs introduced: <list, or "none">
|
|
114
|
-
- Materially amended existing docs: <list, or "none">
|
|
115
|
-
- Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
Use doc names, `none`, or `deferred: <trigger>`. Apply `reference/documentation-impact.md`; amend the existing owner; create a standalone file only where no doc owns the topic. Put project taxonomy in the overrides file's `## documentation` block (guidance only; no settings key). Doc updates ship in the same commit as the code and the conformance gate verifies them against the spec. Clarify when needed.
|
|
113
|
+
Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, read and apply [Documentation impact](reference/documentation-impact.md), including its verbatim template; cite that portable relative path in the spec; do not restate its categories. Ask the user when doc impact is unclear. Unreadable -> stop the step with a blocking error. Cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by that owner's materiality bar, never list them automatically.
|
|
119
114
|
|
|
120
115
|
## Ticket Handling
|
|
121
116
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
**Extract the ticket's ACs.** When the ticket body has a heading matching `/acceptance criteria/i`, every list item under it until the next heading is an AC (numbered, bullet, or checkbox) and no other list in the body is. When there is no such heading, every top-level checkbox row in the body is an AC, except rows under a `Post-deployment housekeeping`, `Out of scope`, or `Follow-up` heading. Otherwise the ticket has no ACs. A nested list under an AC row rides with its parent as one row; an AC heading holding prose and no list makes each paragraph one row. Carry checked and unchecked rows alike, all written `- [ ]`. Take the rows from the gather draft's `## Ticket acceptance criteria (verbatim)` heading; when the ticket was not fetched, the gate summary shows the `none` line so the user can paste the rows, which then become rows.
|
|
125
|
-
|
|
126
|
-
**Write the section in every spec**, after `## Problem`:
|
|
127
|
-
|
|
128
|
-
```markdown
|
|
129
|
-
## Acceptance criteria
|
|
130
|
-
|
|
131
|
-
Ticket <ref>, <heading or "checkbox list">, rows verbatim:
|
|
132
|
-
|
|
133
|
-
- [ ] <row text copied verbatim>
|
|
134
|
-
<disposition>
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
The heading `## Acceptance criteria` names the ticket contract only; the spec's own requirements stay in Design. Disposition is exactly one of `in-scope`, `deviates: <why>`, `deferred: <where>`, `venue: <env> - <observation>`; default `in-scope`. Never edit the row text: a wrongly stated row is `deviates: <why>`, an ambiguous row stays `in-scope` with the chosen reading written as a Design clause. Name a `venue:` row's enabling change in Design. An `in-scope` row is a requirement as written; disposition reasons are never normative for the plan or the reviewer, so a `deviates:` reason that adopts part of a row restates that part as a Design clause. Defer a row only when the shipped change operates without it - cost is never a reason; a hard but direct AC stays `in-scope` and ships. Ask every `deviates:`/`deferred:` decision in the questionary and name it in the gate summary; `venue:` states where the observation can happen and is not a scope decision. A disposition changes in any later phase - a reviewer finding `recommended: rescope` at the finish gate, a wrong row noticed mid-implementation, or a ticket edited after approval when the user asks - through [Amending an approved spec](#amending-an-approved-spec) (`reference/amendment-surface.md`); the row text still never changes. With no ticket, or a ticket without ACs, the section body is the single line `none - no ticket`, `none - ticket has no acceptance criteria`, or `none - ticket not fetched (<reason>)`. Never author acceptance criteria on the ticket's behalf; that is `/skill:shape-ticket`'s job.
|
|
117
|
+
Read [Ticket Handling](reference/ticket-acceptance.md) before gathering context or step-4/8 entry, even with no ticket; unreadable -> stop with a blocking error, never reconstruct from memory.
|
|
138
118
|
|
|
139
119
|
## First-Feature Oversight (Early Project Stages)
|
|
140
120
|
|
|
@@ -142,7 +122,7 @@ For the first two features of a new module, long-lived component, schema area, o
|
|
|
142
122
|
|
|
143
123
|
## Anti-Pattern: "Too simple to need a design"
|
|
144
124
|
|
|
145
|
-
|
|
125
|
+
Inside an opted-in flow, shared schemas, contracts, and invariants require a spec. If work is mechanical and contained, such as a rename, formatting, or dependency bump, say so explicitly and skip brainstorming; otherwise spec first within that flow.
|
|
146
126
|
|
|
147
127
|
## Filename Convention
|
|
148
128
|
|
|
@@ -152,130 +132,15 @@ Mint the slug once during gather and reuse it. If questionary invalidates it, wr
|
|
|
152
132
|
|
|
153
133
|
## Spec Self-Review (Before User Review Gate)
|
|
154
134
|
|
|
155
|
-
Spec-writing
|
|
156
|
-
|
|
157
|
-
1. `Read` the draft in full — **immediately before** the overwrite. Without this, a
|
|
158
|
-
pruned questionary plus a full-replacement `write` destroys the only copy of the
|
|
159
|
-
gathered context at the moment it feeds the spec.
|
|
160
|
-
2. Write the spec with the `write` tool (**full replacement**) at the spec path.
|
|
161
|
-
Using `edit` at this step is a red flag.
|
|
162
|
-
3. **Immediately after the write**, confirm line 1 of the file is no longer
|
|
163
|
-
`# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` — before
|
|
164
|
-
dispatching lint, critique, council, or summarizer. The phase-tracker commit
|
|
165
|
-
guard is a backstop, not the primary check.
|
|
166
|
-
4. **After the line-1 check**, run the second predecessor pass. Compose a query from
|
|
167
|
-
the spec's H1 terms, then the terms of every H2 that is not a template heading
|
|
168
|
-
(Problem, Acceptance criteria, Design, Errors and edge cases, Tests, Documentation
|
|
169
|
-
impact, Out of scope, Open questions), then the `**Goal:**` line's terms - same
|
|
170
|
-
token rules as the scout, deduplicated, cut at 15. Run
|
|
171
|
-
`(cd <abs worktree path> && node <SPEC_INDEX> --query '<terms>' --limit 5 --exclude <spec path relative to the worktree>)`
|
|
172
|
-
with `<SPEC_INDEX>` resolved as in `gatherer.md`. Take the `live` rows and drop every
|
|
173
|
-
path the draft's `Predecessor:` line(s) named (retained from the step-1 read). Carry
|
|
174
|
-
the remainder to the gate as one adjacent line:
|
|
175
|
-
`New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.`
|
|
176
|
-
or `New predecessor candidates at spec-writing: none.` A non-zero exit degrades to
|
|
177
|
-
`Second predecessor pass unavailable: <first stderr line>`; it never blocks the gate
|
|
178
|
-
or the commit. "yes, <path> is a predecessor" at the gate is a change request that
|
|
179
|
-
adds the `supersedes <path>, <scope>` clause and the banner, then re-presents the gate.
|
|
180
|
-
5. **After the second predecessor pass and before the inline lint**, `edit` any known
|
|
181
|
-
predecessor spec to insert its supersession banner (see
|
|
182
|
-
[Marking superseded specs](reference/superseding.md)). This position is fixed:
|
|
183
|
-
the banner is written after any slug rename, so it always cites the final path.
|
|
184
|
-
|
|
185
|
-
After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](#filename-convention)) and before showing it to the user, run a self-review pass. Read all five bullets first, then act.
|
|
186
|
-
|
|
187
|
-
- **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
|
|
188
|
-
- **Internal consistency.** Does Section 4 contradict Section 2? Are component names and field names consistent throughout? If the spec replaces a prior design, confirm the predecessor carries the supersession banner and its href resolves to this spec's final filename.
|
|
189
|
-
- **Documentation named.** Does the spec name all three classes (feature/user-facing introduced; materially amended; derived/memory invalidated), or an explicit "none" for each? Enforce the materiality bar in `reference/documentation-impact.md` without restating it: each listed doc names the category it clears, none is a code-mirror, amend-over-create was applied, and skill/agent bodies are implementation surface, not doc-impact entries here.
|
|
190
|
-
- **Ticket contract present.** Does `## Acceptance criteria` exist with either verbatim ticket rows plus dispositions or one `none - <reason>` line? Presence is enforced here, at authoring, and nowhere later.
|
|
191
|
-
- **Scope check.** Does every paragraph serve the goal? Cut filler. If something is out of scope, say it's out of scope.
|
|
192
|
-
- **Ambiguity check.** Is every "we should…" backed by a concrete decision? Replace "we could probably" with "we will" or "we won't".
|
|
193
|
-
|
|
194
|
-
The first four are the inline **lint**: run them here and fix what they surface. The last two are the **critique pass**, dispatched per [Spec Council](#spec-council-optional). After it returns, re-run the placeholder scan over the applied spec; if a predecessor banner exists, confirm its `<scope>` still matches and reconcile it; carry any ambiguity the critique could not resolve to the [User Review Gate](#user-review-gate).
|
|
195
|
-
|
|
196
|
-
## Spec Council (Optional)
|
|
197
|
-
|
|
198
|
-
Before dispatching the worker below, resolve `reference/documentation-impact.md` relative to this loaded skill as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value. Pass that value in the worker task; do not add it to the spec.
|
|
199
|
-
|
|
200
|
-
After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**; council **apply mechanics** live in `/skill:roasting-the-spec` (single source of truth - link, don't restate). Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`; also pass the verbatim human input (the original prompt, any ticket AC snapshot - the raw rows under the gather draft's `## Ticket acceptance criteria (verbatim)` heading, never the spec's section, which holds the author's dispositions - and the questionary answers that changed scope) - roasting-the-spec forwards it to members and chair as the `Human input (verbatim; off-limits for over-spec)` block; it applies its apply-set and returns the audit (Applied/Deferred/Rejected). When `verdict` is `"worker"`, dispatch the worker below. If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. The already-applied council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
|
|
201
|
-
|
|
202
|
-
When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
|
|
203
|
-
|
|
204
|
-
```
|
|
205
|
-
subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
|
|
206
|
-
"Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
|
|
207
|
-
"Read the spec at <abs path to doc/specs/...>. Edit ONLY that file.\n" +
|
|
208
|
-
"The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference, and preserve it - never remove it as redundant or replace it with the resolved absolute path.\n" +
|
|
209
|
-
"Apply two checks and fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
|
|
210
|
-
"state out-of-scope explicitly. (2) Ambiguity — is every 'we should' a concrete decision?\n" +
|
|
211
|
-
"Replace 'we could probably' with 'we will'/'we won't'. Also inline any load-bearing\n" +
|
|
212
|
-
"external reference (ticket AC, commit SHA, doc) already given to you in the problem\n" +
|
|
213
|
-
"statement above; if the spec relies on one not provided here, flag it (do NOT fetch) in\n" +
|
|
214
|
-
"your summary. Return a summary of what you changed, and flag any ambiguity you could NOT\n" +
|
|
215
|
-
"safely resolve." })
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
`worker`'s model resolves from `subagents.agentOverrides.worker.model` in `settings.json` (unset → inherits the main loop); the dispatch passes no `model:`.
|
|
219
|
-
|
|
220
|
-
## User Review Gate
|
|
221
|
-
|
|
222
|
-
After self-review and the critique pass (council or worker, both already applied to the spec - see [Spec Council](#spec-council-optional)), dispatch the spec-only summarizer over the **applied** spec, then commit the spec on the worktree branch and stop. The summary is folded into the one human gate, not a new gate.
|
|
135
|
+
Read [Spec Self-Review](reference/spec-finalization.md#spec-self-review-before-user-review-gate) before spec-writing or restored step 8; unreadable -> stop with a blocking error, never reconstruct from memory.
|
|
223
136
|
|
|
224
|
-
|
|
137
|
+
## Spec Council
|
|
225
138
|
|
|
226
|
-
|
|
227
|
-
SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX") # absolute, portable across GNU/BSD mktemp
|
|
228
|
-
```
|
|
139
|
+
Follow [Spec Council](reference/spec-finalization.md#spec-council) for the mandatory critique pass.
|
|
229
140
|
|
|
230
|
-
|
|
231
|
-
subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>",
|
|
232
|
-
output: "<SUMMARY_PATH>", outputMode: "file-only", task:
|
|
233
|
-
"Summarize the spec at <abs path to doc/specs/...> for the user review gate. Read ONLY that file." })
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
`<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
|
|
237
|
-
|
|
238
|
-
Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](reference/superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
|
|
239
|
-
|
|
240
|
-
1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line — the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) — skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
|
|
241
|
-
2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation — take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.
|
|
242
|
-
|
|
243
|
-
**Degrade path** — reach the gate with a one-line "summary generation failed" note; never paraphrase from the file-only reference, never render a stub as the canonical summary.
|
|
244
|
-
|
|
245
|
-
Either way — summary rendered or degraded — then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
|
|
246
|
-
|
|
247
|
-
Paste the summary verbatim, unedited in the template below; use adjacent lines for the audit, unresolved ambiguities, and every gap-footer entry:
|
|
248
|
-
|
|
249
|
-
```
|
|
250
|
-
<spec-only summary read back from the temp file — pasted verbatim, unedited>
|
|
251
|
-
|
|
252
|
-
Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
|
|
253
|
-
|
|
254
|
-
Coverage: <N> of <M> members reported; <slug>: <reason> (line present only when coverage was partial)
|
|
255
|
-
Applied: [<severity>] <cluster> — raised-by: [<slugs>] -> <edit>
|
|
256
|
-
Deferred: [<severity>] <cluster> — raised-by: [<slugs>] -> <where it belongs>
|
|
257
|
-
Rejected: [<severity>] <cluster> — raised-by: [<slugs>] -> <one-line reason>
|
|
258
|
-
(one line per item, exactly as returned by roasting-the-spec - `Applied: none` / `Deferred: none` / `Rejected: none` when a list is empty; omit the audit lines when the worker path ran, not the council)
|
|
259
|
-
|
|
260
|
-
<unresolved ambiguities; every gap-footer entry from the summary>
|
|
261
|
-
New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.
|
|
262
|
-
|
|
263
|
-
Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
If you believe the summary needs correcting, do **not** silently rewrite it — re-dispatch the summarizer or note the discrepancy as an adjacent line beneath the verbatim block.
|
|
267
|
-
|
|
268
|
-
**Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
|
|
269
|
-
|
|
270
|
-
Wait for the user. On a change request (including a revert), revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt (a grant given at or before approval - "approve, auto-apply amends", or a standalone "auto-apply amends" reply earlier at this gate - is first quoted in the spec commit body via `git -C <abs worktree path> commit --amend --no-edit -q --trailer "Amend-grant: <the sentence>"`, so the worktree history shows when the grant began) — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
|
|
271
|
-
|
|
272
|
-
Post-approval changes follow [Amending an approved spec](#amending-an-approved-spec).
|
|
273
|
-
|
|
274
|
-
After approval, mark the brainstorm phase complete:
|
|
141
|
+
## User Review Gate
|
|
275
142
|
|
|
276
|
-
|
|
277
|
-
phase_tracker({ action: "complete", phase: "brainstorm" })
|
|
278
|
-
```
|
|
143
|
+
Follow [User Review Gate](reference/spec-finalization.md#user-review-gate) for summary, commit, approval, and automatic planning.
|
|
279
144
|
|
|
280
145
|
## Amending an approved spec
|
|
281
146
|
|
|
@@ -283,20 +148,16 @@ Execute in place from any later phase; never invoke `/skill:brainstorming` for i
|
|
|
283
148
|
|
|
284
149
|
Classify first. Redraw test: the change alters the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call; the user overrides either way.
|
|
285
150
|
|
|
286
|
-
Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar)
|
|
151
|
+
Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar). Apply its [Standing grants](reference/amendment-surface.md#standing-grants) boundaries.
|
|
287
152
|
|
|
288
153
|
Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "clear" })`, `phase_tracker({ action: "reset" })`, `phase_tracker({ action: "start", phase: "brainstorm" })`, delete the plan file, resume at checklist step 4 with the approved spec as the draft (steps 2-3 skipped). Spec-writing overwrites it; the full gate follows.
|
|
289
154
|
|
|
290
|
-
## Key Principles
|
|
291
|
-
|
|
292
|
-
One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely - all owned by [The Process](#the-process).
|
|
293
|
-
|
|
294
155
|
## Red Flags — STOP
|
|
295
156
|
|
|
296
157
|
- Writes outside the resolved spec dirs ([owner](#hard-constraint)).
|
|
297
158
|
- Draft overwrite without the same-turn full read, or overwrite via `edit` ([owner](#spec-self-review-before-user-review-gate)).
|
|
298
159
|
- Dispatch while line 1 is the context-draft marker ([owner](#spec-self-review-before-user-review-gate)).
|
|
299
|
-
- Inline scope or ambiguity checks ([owner](#spec-council
|
|
160
|
+
- Inline scope or ambiguity checks ([owner](#spec-council)).
|
|
300
161
|
- Gate after failed/skipped critique or before placeholder re-scan ([owner](#spec-self-review-before-user-review-gate)).
|
|
301
162
|
- Gate without summary `Read` last, or with a paraphrased summary ([owner](#user-review-gate)).
|
|
302
163
|
- Human stop between gather and question one ([owner](gatherer.md)).
|
|
@@ -304,7 +165,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
|
|
|
304
165
|
- Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
|
|
305
166
|
- Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).
|
|
306
167
|
- Gate reached without the second predecessor pass ([owner](#spec-self-review-before-user-review-gate)).
|
|
307
|
-
- Approaches
|
|
168
|
+
- Approaches before the premise note states a contradicted claim's correction ([owner](#3-understand-the-idea)).
|
|
308
169
|
- Amend without `reference/amendment-surface.md`; waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
|
|
309
170
|
|
|
310
171
|
## Project overrides
|
|
@@ -36,8 +36,9 @@ Absolute `output:` paths are mandatory: relative paths in parallel mode resolve
|
|
|
36
36
|
against the worktree and would get committed.
|
|
37
37
|
|
|
38
38
|
`<SPEC_INDEX>` is `<directory of this skill's SKILL.md>/../../bin/gauntlet-spec-index.mjs`,
|
|
39
|
-
resolved to an absolute path by the main loop from the
|
|
40
|
-
before pasting the task.
|
|
39
|
+
resolved to an absolute path by the main loop from the loaded brainstorming `SKILL.md` path
|
|
40
|
+
in the command's skill envelope or the absolute path used to read it, before pasting the task.
|
|
41
|
+
Use that SKILL.md directory, never `reference/` as the base.
|
|
41
42
|
|
|
42
43
|
## Task templates
|
|
43
44
|
|
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
# Amendment surface
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Load from `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Only the main loop holding `edit`/`write` authors amendments and human-facing amendment text. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
|
|
4
|
+
|
|
5
|
+
## Standing grants
|
|
6
|
+
|
|
7
|
+
Honor a user sentence in this flow that waives per-diff review for later amends (`auto-apply amends`, `approve, auto-apply amends` at the spec gate, `auto-apply amends, stop only for redraws`, `apply spec fixes without asking`, or the same intent in other words). Apply every later amend-class change without review, scope changes included; redraws always stop and the grant never satisfies the spec gate. Start a new brainstorm or a fresh-session resume with no grant; never infer one from history.
|
|
8
|
+
|
|
9
|
+
Before proceeding to planning, quote a grant given at or before spec approval in the spec commit body via `git -C <abs worktree path> commit --amend --no-edit -q --trailer "Amend-grant: <the sentence>"`, so the worktree history shows when the grant began.
|
|
4
10
|
|
|
5
11
|
## 1. Prepare - never apply yet
|
|
6
12
|
|
|
@@ -18,9 +24,9 @@ Collect every amendment pending at this decision point (same spec-review round,
|
|
|
18
24
|
| `recommended` | `accept` or `alt-n` |
|
|
19
25
|
| `alternatives` | genuinely different spec edits, zero or more |
|
|
20
26
|
|
|
21
|
-
The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (
|
|
27
|
+
The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (`../SKILL.md` redraw path); amend items are held and re-batched after it resolves.
|
|
22
28
|
|
|
23
|
-
**Standing grant active** (
|
|
29
|
+
**Standing grant active** ([boundaries](#standing-grants)): skip steps 2-4, apply every item, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the sentence in the commit body.
|
|
24
30
|
|
|
25
31
|
## 2. Prefilter - no model call
|
|
26
32
|
|
|
@@ -116,11 +116,13 @@ Each entry answers with a doc name, `"none"`, or `"deferred: <trigger>"` (for
|
|
|
116
116
|
example, `CHANGELOG.md - deferred: release`, when a doc changes on a known
|
|
117
117
|
later event and should not be flagged as missing before that event fires).
|
|
118
118
|
|
|
119
|
+
Doc updates ship in the same commit as the code and the conformance gate verifies them against the spec.
|
|
120
|
+
|
|
119
121
|
## Referenced by
|
|
120
122
|
|
|
121
123
|
Keep this list in sync with the skills that cite this doc:
|
|
122
124
|
|
|
123
|
-
- `brainstorming` section 6
|
|
125
|
+
- `brainstorming` section 6 and `brainstorming/reference/spec-finalization.md` self-review and worker dispatch context.
|
|
124
126
|
- `roasting-the-spec` member and chair dispatch context.
|
|
125
127
|
- `brainstorming/reference/amendment-surface.md` amendment-review dispatch context.
|
|
126
128
|
- `writing-plans` - sources doc-update tasks from the spec's Documentation
|
|
@@ -134,4 +136,4 @@ Keep this list in sync with the skills that cite this doc:
|
|
|
134
136
|
This doc is generic. Project-specific doc taxonomy (which docs a given
|
|
135
137
|
project treats as canonical for which topic) lives in the gauntlet
|
|
136
138
|
overrides file (see Project overrides in `brainstorming/SKILL.md`), in a
|
|
137
|
-
`## documentation` section - not here.
|
|
139
|
+
`## documentation` section (guidance only; no settings key) - not here.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Spec finalization
|
|
2
|
+
|
|
3
|
+
## Spec Self-Review (Before User Review Gate)
|
|
4
|
+
|
|
5
|
+
Spec-writing replaces the context draft, in this exact order:
|
|
6
|
+
|
|
7
|
+
1. `Read` the draft in full - **immediately before** the overwrite. Without this, a
|
|
8
|
+
pruned questionary plus a full-replacement `write` destroys the only copy of the
|
|
9
|
+
gathered context at the moment it feeds the spec.
|
|
10
|
+
2. Write the spec with the `write` tool (**full replacement**) at the spec path.
|
|
11
|
+
Using `edit` at this step is a red flag.
|
|
12
|
+
3. **Immediately after the write**, confirm line 1 of the file is no longer
|
|
13
|
+
`# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` - before
|
|
14
|
+
dispatching lint, critique, council, or summarizer. The phase-tracker commit
|
|
15
|
+
guard is a backstop, not the primary check.
|
|
16
|
+
4. **After the line-1 check**, run the second predecessor pass. Compose a query from
|
|
17
|
+
the spec's H1 terms, then the terms of every H2 that is not a template heading
|
|
18
|
+
(Problem, Acceptance criteria, Design, Errors and edge cases, Tests, Documentation
|
|
19
|
+
impact, Out of scope, Open questions), then the `**Goal:**` line's terms - same
|
|
20
|
+
token rules as the scout, deduplicated, cut at 15. Run
|
|
21
|
+
`(cd <abs worktree path> && node <SPEC_INDEX> --query '<terms>' --limit 5 --exclude <spec path relative to the worktree>)`
|
|
22
|
+
with `<SPEC_INDEX>` resolved as in `../gatherer.md`. Take the `live` rows and drop every
|
|
23
|
+
path the draft's `Predecessor:` line(s) named (retained from the step-1 read). Carry
|
|
24
|
+
the remainder to the gate as one adjacent line:
|
|
25
|
+
`New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.`
|
|
26
|
+
or `New predecessor candidates at spec-writing: none.` A non-zero exit degrades to
|
|
27
|
+
`Second predecessor pass unavailable: <first stderr line>`; it never blocks the gate
|
|
28
|
+
or the commit. "yes, <path> is a predecessor" at the gate is a change request that
|
|
29
|
+
adds the `supersedes <path>, <scope>` clause and the banner, then re-presents the gate.
|
|
30
|
+
5. **After the second predecessor pass and before the inline lint**, `edit` any known
|
|
31
|
+
predecessor spec to insert its supersession banner (see
|
|
32
|
+
[Marking superseded specs](superseding.md)). This position is fixed:
|
|
33
|
+
the banner is written after any slug rename, so it always cites the final path.
|
|
34
|
+
|
|
35
|
+
After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](../SKILL.md#filename-convention)) and before showing it to the user, run a self-review pass. Read all six bullets first, then act.
|
|
36
|
+
|
|
37
|
+
- **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
|
|
38
|
+
- **Internal consistency.** Does Section 4 contradict Section 2? Are component names and field names consistent throughout? If the spec replaces a prior design, confirm the predecessor carries the supersession banner and its href resolves to this spec's final filename.
|
|
39
|
+
- **Documentation named.** Does the spec name all three classes (feature/user-facing introduced; materially amended; derived/memory invalidated), or an explicit "none" for each? Enforce the materiality bar in `documentation-impact.md` without restating it: each listed doc names the category it clears, none is a code-mirror, amend-over-create was applied, and skill/agent bodies are implementation surface, not doc-impact entries here.
|
|
40
|
+
- **Ticket contract present.** Does `## Acceptance criteria` exist with either verbatim ticket rows plus dispositions or one `none - <reason>` line? Presence is enforced here, at authoring, and nowhere later.
|
|
41
|
+
- **Scope check.** Does every paragraph serve the goal? Cut filler. If something is out of scope, say it's out of scope.
|
|
42
|
+
- **Ambiguity check.** Is every "we should..." backed by a concrete decision? Replace "we could probably" with "we will" or "we won't".
|
|
43
|
+
|
|
44
|
+
The first four are the inline **lint**: run them here and fix what they surface. The last two are the **critique pass**, dispatched per [Spec Council](#spec-council). After it returns, re-run the placeholder scan over the applied spec; if a predecessor banner exists, confirm its `<scope>` still matches and reconcile it; carry any ambiguity the critique could not resolve to the [User Review Gate](#user-review-gate).
|
|
45
|
+
|
|
46
|
+
## Spec Council
|
|
47
|
+
|
|
48
|
+
Before dispatching the worker below, resolve `documentation-impact.md` relative to this loaded reference as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value. Pass that value in the worker task; do not add it to the spec.
|
|
49
|
+
|
|
50
|
+
After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**; council **apply mechanics** live in `/skill:roasting-the-spec` (single source of truth - link, don't restate). Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`; also pass the verbatim human input (the original prompt, any ticket AC snapshot - the raw rows under the gather draft's `## Ticket acceptance criteria (verbatim)` heading, never the spec's section, which holds the author's dispositions - and the questionary answers that changed scope) - roasting-the-spec forwards it to members and chair as the `Human input (verbatim; off-limits for over-spec)` block; it applies its apply-set and returns the audit (Applied/Deferred/Rejected). When `verdict` is `"worker"`, dispatch the worker below. If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. The already-applied council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `../../verification-before-completion/reference/settings-precedence.md`.
|
|
51
|
+
|
|
52
|
+
When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
|
|
56
|
+
"Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
|
|
57
|
+
"Read the spec at <abs path to doc/specs/...>. Edit ONLY that file.\n" +
|
|
58
|
+
"The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference, and preserve it - never remove it as redundant or replace it with the resolved absolute path.\n" +
|
|
59
|
+
"Apply two checks and fix what you find in place: (1) Scope - does every paragraph serve the goal? Cut filler;\n" +
|
|
60
|
+
"state out-of-scope explicitly. (2) Ambiguity - is every 'we should' a concrete decision?\n" +
|
|
61
|
+
"Replace 'we could probably' with 'we will'/'we won't'. Also inline any load-bearing\n" +
|
|
62
|
+
"external reference (ticket AC, commit SHA, doc) already given to you in the problem\n" +
|
|
63
|
+
"statement above; if the spec relies on one not provided here, flag it (do NOT fetch) in\n" +
|
|
64
|
+
"your summary. Return a summary of what you changed, and flag any ambiguity you could NOT\n" +
|
|
65
|
+
"safely resolve." })
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`worker`'s model resolves from `subagents.agentOverrides.worker.model` in `settings.json` (unset -> inherits the main loop); the dispatch passes no `model:`.
|
|
69
|
+
|
|
70
|
+
## User Review Gate
|
|
71
|
+
|
|
72
|
+
After self-review and the critique pass (council or worker, both already applied to the spec - see [Spec Council](#spec-council)), dispatch the spec-only summarizer over the **applied** spec, then commit the spec on the worktree branch and stop. The summary is folded into the one human gate, not a new gate.
|
|
73
|
+
|
|
74
|
+
Mint an absolute temp path outside the worktree (so it is never committed), then dispatch the summarizer on a fresh context, reading only the spec, writing to that path via file-only output (no `model:` - it inherits the main loop unless a preset sets `subagents.agentOverrides.spec-summarizer.model`):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX") # absolute, portable across GNU/BSD mktemp
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>",
|
|
82
|
+
output: "<SUMMARY_PATH>", outputMode: "file-only", task:
|
|
83
|
+
"Summarize the spec at <abs path to doc/specs/...> for the user review gate. Read ONLY that file." })
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
|
|
87
|
+
|
|
88
|
+
Then commit the spec - staging any predecessor spec edited per [Marking superseded specs](superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
|
|
89
|
+
|
|
90
|
+
1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line - the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) - skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
|
|
91
|
+
2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation - take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.
|
|
92
|
+
|
|
93
|
+
**Degrade path** - reach the gate with a one-line "summary generation failed" note; never paraphrase from the file-only reference, never render a stub as the canonical summary.
|
|
94
|
+
|
|
95
|
+
Either way - summary rendered or degraded - then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
|
|
96
|
+
|
|
97
|
+
Paste the summary verbatim, unedited in the template below; use adjacent lines for the audit, unresolved ambiguities, and every gap-footer entry:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
<spec-only summary read back from the temp file - pasted verbatim, unedited>
|
|
101
|
+
|
|
102
|
+
Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
|
|
103
|
+
|
|
104
|
+
Coverage: <N> of <M> members reported; <slug>: <reason> (line present only when coverage was partial)
|
|
105
|
+
Applied: [<severity>] <cluster> - raised-by: [<slugs>] -> <edit>
|
|
106
|
+
Deferred: [<severity>] <cluster> - raised-by: [<slugs>] -> <where it belongs>
|
|
107
|
+
Rejected: [<severity>] <cluster> - raised-by: [<slugs>] -> <one-line reason>
|
|
108
|
+
(one line per item, exactly as returned by roasting-the-spec - `Applied: none` / `Deferred: none` / `Rejected: none` when a list is empty; omit the audit lines when the worker path ran, not the council)
|
|
109
|
+
|
|
110
|
+
<unresolved ambiguities; every gap-footer entry from the summary>
|
|
111
|
+
New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.
|
|
112
|
+
|
|
113
|
+
Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
If you believe the summary needs correcting, do **not** silently rewrite it - re-dispatch the summarizer or note the discrepancy as an adjacent line beneath the verbatim block.
|
|
117
|
+
|
|
118
|
+
**Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
|
|
119
|
+
|
|
120
|
+
Wait for the user. On a change request (including a revert), revise the spec and re-present - mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt; first read [Standing grants](amendment-surface.md#standing-grants) (stop if unreadable) and record any grant. The plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
|
|
121
|
+
|
|
122
|
+
Post-approval changes follow [Amending an approved spec](../SKILL.md#amending-an-approved-spec).
|
|
123
|
+
|
|
124
|
+
After approval, mark the brainstorm phase complete:
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
phase_tracker({ action: "complete", phase: "brainstorm" })
|
|
128
|
+
```
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Ticket Handling
|
|
2
|
+
|
|
3
|
+
A ticket is guidance, not sole truth. Fetch it; propose scope, approach, or acceptance changes when code disagrees, and record deviations in the spec. Implied requirements in the ticket body (Context, Problem, Idea) land in the spec body as any other requirement; the ticket's explicit acceptance criteria land verbatim in the section below.
|
|
4
|
+
|
|
5
|
+
**Extract the ticket's ACs.** When the ticket body has a heading matching `/acceptance criteria/i`, every list item under it until the next heading is an AC (numbered, bullet, or checkbox) and no other list in the body is. When there is no such heading, every top-level checkbox row in the body is an AC, except rows under a `Post-deployment housekeeping`, `Out of scope`, or `Follow-up` heading. Otherwise the ticket has no ACs. A nested list under an AC row rides with its parent as one row; an AC heading holding prose and no list makes each paragraph one row. Carry checked and unchecked rows alike, all written `- [ ]`. Take the rows from the gather draft's `## Ticket acceptance criteria (verbatim)` heading; when the ticket was not fetched, the gate summary shows the `none` line so the user can paste the rows, which then become rows.
|
|
6
|
+
|
|
7
|
+
**Write the section in every spec**, after `## Problem`:
|
|
8
|
+
|
|
9
|
+
```markdown
|
|
10
|
+
## Acceptance criteria
|
|
11
|
+
|
|
12
|
+
Ticket <ref>, <heading or "checkbox list">, rows verbatim:
|
|
13
|
+
|
|
14
|
+
- [ ] <row text copied verbatim>
|
|
15
|
+
<disposition>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The heading `## Acceptance criteria` names the ticket contract only; the spec's own requirements stay in Design. Disposition is exactly one of `in-scope`, `deviates: <why>`, `deferred: <where>`, `venue: <env> - <observation>`; default `in-scope`. Never edit the row text: a wrongly stated row is `deviates: <why>`, an ambiguous row stays `in-scope` with the chosen reading written as a Design clause. Name a `venue:` row's enabling change in Design. An `in-scope` row is a requirement as written; disposition reasons are never normative for the plan or the reviewer, so a `deviates:` reason that adopts part of a row restates that part as a Design clause. Defer a row only when the shipped change operates without it - cost is never a reason; a hard but direct AC stays `in-scope` and ships. Ask a `deviates:`/`deferred:` decision only when it changes what the user observes once the change ships, offering the dispositions themselves as the options (`A) in-scope B) deviates: <why> C) deferred: <where>`); a deviation caused by a workflow artifact (spec, plan, changelog, telemetry file) or a moved path is stated in the disposition, not asked. Name every disposition in the gate summary; `venue:` states where the observation can happen and is not a scope decision. A disposition changes in any later phase - a reviewer finding `recommended: rescope` at the finish gate, a wrong row noticed mid-implementation, or a ticket edited after approval when the user asks - through [Amending an approved spec](../SKILL.md#amending-an-approved-spec) (`amendment-surface.md`); the row text still never changes. With no ticket, or a ticket without ACs, the section body is the single line `none - no ticket`, `none - ticket has no acceptance criteria`, or `none - ticket not fetched (<reason>)`. Never author acceptance criteria on the ticket's behalf; that is `/skill:shape-ticket`'s job.
|
|
@@ -277,7 +277,7 @@ any handoff:
|
|
|
277
277
|
- File a ticket chosen -> shape-ticket runs its own gate first -> draft the
|
|
278
278
|
response citing the new ticket link -> gate 2 -> done.
|
|
279
279
|
- Brainstorm now chosen -> draft the response first ("confirmed, investigating
|
|
280
|
-
now - fix to follow") -> gate 2 -> **then** hand off to `/skill:brainstorming
|
|
280
|
+
now - fix to follow") -> gate 2 -> **then** hand off to [`/skill:brainstorming`](../brainstorming/SKILL.md).
|
|
281
281
|
- Hotfix now chosen -> hand off to `hotfix.md` first; on completion, draft the
|
|
282
282
|
response citing `fixed in <SHA>` or the PR link -> gate 2 (`send it`) -> done.
|
|
283
283
|
Gate 2 fires once. On abort, `hotfix.md` returns to the step-4 menu; step 5
|
|
@@ -343,7 +343,7 @@ action renders the verdict as a **summary to the human**, then the skill ends
|
|
|
343
343
|
shape-ticket is cancelled at its gate, render the summary without a ticket
|
|
344
344
|
link.
|
|
345
345
|
- Brainstorm now chosen -> render the summary -> **then** hand off to
|
|
346
|
-
`/skill:brainstorming
|
|
346
|
+
[`/skill:brainstorming`](../brainstorming/SKILL.md).
|
|
347
347
|
- Hotfix now chosen -> hand off to `hotfix.md`; on completion render the
|
|
348
348
|
summary citing `fixed in <SHA>` or the PR link -> done. On abort, return to
|
|
349
349
|
the step-4 menu.
|
|
@@ -101,7 +101,7 @@ checks 2, 4, 5 do not apply.
|
|
|
101
101
|
|---|---|
|
|
102
102
|
| brief with `## Process state` | process-state restore - `reference/brief-contract.md` "Process-state restore" |
|
|
103
103
|
| brief without process state, `## Skills loaded` names `chase-bug` | hotfix route below, before any artifact reconstruction, no tracker calls |
|
|
104
|
-
| brief without process state, `worktree: no` |
|
|
104
|
+
| brief without process state, `worktree: no` | offer `/skill:brainstorming` with `## Intent` as the idea and wait for explicit selection; then invoke [`/skill:brainstorming`](../brainstorming/SKILL.md) in the current directory; resume creates no worktree - brainstorming's own Worktree First applies (a plain handoff is a new flow) |
|
|
105
105
|
| brief without process state, worktree present | `reference/reconstruction.md`, with `## Intent` and `## Decisions` carried into every confirmation prompt |
|
|
106
106
|
| bare worktree | `reference/reconstruction.md`; prompts state that no brief context is available (never invent Intent/Decisions) |
|
|
107
107
|
| spec seed | `reference/seed.md` |
|
|
@@ -120,7 +120,7 @@ owning skill **without** its reset-bearing entry:
|
|
|
120
120
|
|
|
121
121
|
| Active after restore | Continue in | Entry point |
|
|
122
122
|
|---|---|---|
|
|
123
|
-
| brainstorm | brainstorming checklist | on-disk state decides the step: draft marker on line 1 of the spec file -> step 4; spec title -> step 8. Never `/skill:brainstorming` entry (it resets both trackers) |
|
|
123
|
+
| brainstorm | [brainstorming checklist](../brainstorming/SKILL.md#checklist) | on-disk state decides the step: draft marker on line 1 of the spec file -> step 4; spec title -> step 8. Never `/skill:brainstorming` entry (it resets both trackers) |
|
|
124
124
|
| plan | writing-plans body | skip its `start plan` call (already in_progress) |
|
|
125
125
|
| implement | subagent-driven-development | re-validate `<task>` first (re-run its `Tests:`), then the task loop from the first non-complete task |
|
|
126
126
|
| verify | verification-before-completion | full conformance gate; nothing carried over |
|
|
@@ -52,14 +52,17 @@ plan commit; treat every task as `pending`.
|
|
|
52
52
|
|
|
53
53
|
## Spec without plan
|
|
54
54
|
|
|
55
|
-
Ask exactly one question: is this spec approved
|
|
55
|
+
Ask exactly one question: is this spec approved, or do you select `/skill:brainstorming`
|
|
56
|
+
with this unapproved spec as the draft? Show the spec path (and the brief's
|
|
56
57
|
`## Intent`/`## Decisions` when present).
|
|
57
58
|
|
|
58
59
|
- Approved: `start brainstorm`; `skip brainstorm resume: <spec path>`; `start plan`;
|
|
59
60
|
continue in writing-plans (its own `start plan` is skipped - plan is already
|
|
60
61
|
in_progress).
|
|
61
|
-
-
|
|
62
|
-
using-git-worktrees Step 0 detects the existing
|
|
62
|
+
- Selected unapproved-draft brainstorming handoff: invoke [`/skill:brainstorming`](../../brainstorming/SKILL.md) with
|
|
63
|
+
the spec as the draft; arm nothing. using-git-worktrees Step 0 detects the existing
|
|
64
|
+
worktree and creates none. A bare "not approved" answer is not consent; wait for
|
|
65
|
+
explicit handoff selection.
|
|
63
66
|
|
|
64
67
|
## Spec with plan
|
|
65
68
|
|
|
@@ -28,7 +28,7 @@ Before drafting the plan, check `phase_tracker({ action: "status" })`. If `plan`
|
|
|
28
28
|
| `doc/specs/2025-05-26-PROJ-1234-foo.md` | `doc/plans/2025-05-26-PROJ-1234-foo.md` |
|
|
29
29
|
| `<service>/doc/specs/<name>.md` | `<service>/doc/plans/<name>.md` |
|
|
30
30
|
|
|
31
|
-
If no spec exists,
|
|
31
|
+
If no spec exists, recommend `/skill:brainstorming` and await the user's explicit choice before invoking [`/skill:brainstorming`](../brainstorming/SKILL.md). Do not invent a plan without a spec.
|
|
32
32
|
|
|
33
33
|
## Boundaries
|
|
34
34
|
|