diff --git a/skills/super-board/references/design-preflight.md b/skills/super-board/references/design-preflight.md new file mode 100644 index 00000000..ddb51cae --- /dev/null +++ b/skills/super-board/references/design-preflight.md @@ -0,0 +1,49 @@ +# Design preflight + +Compare two designs before an unsettled choice creates a new ownership boundary, +new/changed public interface, or architecture expensive to reverse. Labels alone do not +trigger this step. Ordinary bugs and mechanical refactors keep the normal path. + +## Establish the decision + +1. Read the current flow and its owners/callers, `PROJECT.md` and `CONTEXT.md` when present, + and applicable specs/ADRs. Name the question and the constraints with source references. +2. Follow an applicable recorded decision when it answers the question. Finish here rather + than reopening it to produce options. +3. Confirm who may choose. Interactive lint proposes a choice to the user in the existing + per-issue loop. Workers compare only authorized technical forks at rung 3 of the + [decision policy](../../super-build/references/decision-policy.md). Ambiguous product + intent, an unauthorized auth/trust change or a public-contract break takes its human gate. + +## Compare and choose + +Use `mattpocock-skills:codebase-design` for module depth and interfaces. Reach +`mattpocock-skills:domain-modeling` only when terminology or an ADR needs work. Workers +recheck [conditional skill readiness](skills-readiness.md) before activating either helper. + +Sketch two genuinely different arrangements of callers and modules. For each, record: + +- **Owner and interface:** who owns state/behavior, which callers use it, and what they pass/get. +- **Constraints:** how it satisfies the recorded requirements and existing contracts. +- **Module depth:** what useful work it hides behind how much caller knowledge. +- **Blast radius:** which callers, data or contracts change. +- **Migration and reversal:** how existing callers move and what undoing the choice costs. +- **Verification:** the observable behavior and project checks that would prove it. +- **Deletion test:** what capability or complexity vanishes if the module is removed. + +Renaming the same arrangement is not a second design. Sketches are enough; build only the +chosen design unless the ticket already authorizes a prototype. Choose the minimal design +that meets the constraints, then state why it wins and the main tradeoff. + +## Retain the choice + +Interactive lint shows the comparison and proposed choice, then saves only the exact issue +edit approved in its existing loop. Put a compact decision and rationale in Context, or +link an applicable spec/ADR. Its local-write boundary remains unchanged. A worker records +its rung-3 choice in the existing commit decision trailer, with the evidence reference. +Keep existing ticket sections, lanes and human gates. + +Done means the applicable recorded design was followed, or both sketches and a justified +choice are available to the next worker/reviewer. An unresolved human choice stays blocked. +Design quality remains agent judgment; format and installer checks do not prove the sketches +are distinct or the selected design is good. diff --git a/skills/super-board/references/lint.md b/skills/super-board/references/lint.md index 73df9be5..8e600d40 100644 --- a/skills/super-board/references/lint.md +++ b/skills/super-board/references/lint.md @@ -79,7 +79,7 @@ PHASE 7 — Final summary + session-reset nudge --- -## Lint criteria — 18-criterion table +## Lint criteria — 19-criterion table An issue is flagged if any of these apply. An issue can fail multiple criteria; all firing criteria are surfaced in Phase 4. @@ -103,6 +103,11 @@ An issue is flagged if any of these apply. An issue can fail multiple criteria; | 16 | Ticket sections missing (writing-standard.md § 3): `## Problem`, `## Context`, `## Fix`, `## Risk` — and `## Evidence` (the folded 12-row table) on a bug | Body has "What to build" and ACs only | Rewrite into the ticket format; draft Problem/Fix from the body, ask for Who and Risk | | 17 | Acceptance Criteria not a checklist | ACs as prose or plain `-` bullets | Rewrite as `- [ ] `, one per line | | 18 | Context steps not lettered under Where, more than one step per line, or chained with arrows | "Where: /x — sign in → open Receipts → drop file" | Rewrite as `- **Where:** …` then ` - a. Sign in` / ` - b. …`, one per line; embed the screenshot (raw URL pinned to a sha), never link it | +| 19 | Unsettled new ownership boundary, new/changed public interface, or architecture expensive to reverse; no adequate applicable design record | Two callers could each own the new shared state, with no recorded choice | Follow [design preflight](design-preflight.md); compare two sketches and propose a choice in Context | + +Criterion 19 is conditional. Read the current flow, owners/callers and applicable specs/ADRs +before flagging it. Labels alone do not trigger it. Ordinary bugs, mechanical refactors and +choices already settled by an applicable design record keep the normal path. --- @@ -169,9 +174,14 @@ ticket closes, or becomes the first slice, once the user approves the split. | Issue with multiple interpretations (criterion #12) | `mattpocock-skills:grilling` | | Ticket too big (criterion #15) | `/to-tickets` (split into vertical slices) | | Ticket format (criteria #16–18) | Inline rewrite into `ticket-format.md` (sub-agent in lint itself) | +| Unsettled expensive design (criterion #19) | [Design preflight](design-preflight.md) with `mattpocock-skills:codebase-design`; `mattpocock-skills:domain-modeling` only for terminology/ADR work | | Catch-all (none of above) | Inline draft (sub-agent in lint itself) | One sub-agent per issue. User stays in control of pacing. +When criterion 19 fires, propose the two sketches, choice and short rationale within that +issue's existing loop. +Save the exact approved edit in Context (or a link to an applicable spec/ADR). No separate +local design file or extra save permission; unresolved human choices remain blocked. --- @@ -262,7 +272,7 @@ Before declaring lint complete, the worker MUST verify all three: - [ ] `docs/super-board/pre-flight.md` exists and lists every credential / tool / env signal encountered while scanning issues + PROJECT.md. - [ ] Every issue in active-pipeline columns (Ready, Building, QA, Review) either: - - has a populated `## Acceptance Criteria` section that passes all 18 criteria, OR + - has a populated `## Acceptance Criteria` section that passes all 19 criteria (conditional #19 only when triggered), OR - was dropped on purpose (closed as not planned, Done, `🤷 dropped` comment), OR - carries a `🛡 Blocked` comment naming the human-gated blocker. - [ ] No issue is left in an in-between state (flagged but not resolved, partially edited, or awaiting user input that never came). diff --git a/skills/super-board/references/ticket-format.md b/skills/super-board/references/ticket-format.md index e13956e3..2f6662be 100644 --- a/skills/super-board/references/ticket-format.md +++ b/skills/super-board/references/ticket-format.md @@ -47,3 +47,7 @@ and prior failing input/action; Evidence cites the prior PRs/findings. Fix names prevention, not an implementation plan. An AC requires the retained behavioral witness: old failure for the reported reason, corrected pass and behavior-preserving refactor survival. See [correction prevention](../../super-collect/references/correction-prevention.md). + +When an unsettled design triggers [design preflight](design-preflight.md), keep the +approved choice and short rationale in Context, or link its applicable spec/ADR there. +Keep the same sections. Lint saves only the exact issue edit the user approves. diff --git a/skills/super-board/references/writing-standard.md b/skills/super-board/references/writing-standard.md index 0fc1903c..41ec2433 100644 --- a/skills/super-board/references/writing-standard.md +++ b/skills/super-board/references/writing-standard.md @@ -214,6 +214,10 @@ under Risk. | `## Risk` | 🟢/🟡/🔴 level + one line | yes | | `## Blocked by` | `- #N — why` bullets, or exactly `- None.` | yes | +When an unsettled design triggers [design preflight](design-preflight.md), retain the +approved choice and short rationale in the existing Context, or link its applicable +spec/ADR there. Keep the same sections. Lint saves only the exact issue edit the user approves. + Example: ``` diff --git a/skills/super-build/references/decision-policy.md b/skills/super-build/references/decision-policy.md index 2848eed9..3de3dc2e 100644 --- a/skills/super-build/references/decision-policy.md +++ b/skills/super-build/references/decision-policy.md @@ -166,6 +166,14 @@ touches fewer files, adds no public surface, and can be reverted by dropping one commit. When two options tie on blast radius, take the one an existing test already constrains. +For an authorized, unsettled technical rung-3 fork that introduces a new ownership boundary, +new/changed public interface, or architecture expensive to reverse, follow +[design preflight](../../super-board/references/design-preflight.md). An applicable supplied +design/spec/ADR answers the question at an earlier rung; follow it. Labels alone, ordinary +bugs and mechanical refactors do not trigger a comparison. Recheck conditional helper +readiness before use. Record the choice in the existing decision trailer below. +The comparison does not settle ambiguous product intent or waive any hard human gate. + **One technical check is still mandatory before the final commit:** run `mattpocock-skills:code-review` against your own working diff, passing the merge-base as the fixed point (`git merge-base HEAD origin/`). It never