diff --git a/skills/spec-grill/SKILL.md b/skills/spec-grill/SKILL.md index 943c0f4..8add0be 100644 --- a/skills/spec-grill/SKILL.md +++ b/skills/spec-grill/SKILL.md @@ -81,7 +81,7 @@ Use this as a bloat check before the per-capability flow. A large feature-first For each capability, walk the user through this order; do not skip ahead: -1. **Goal** — one sentence: what the user can observe when this works. Diagnosis-side framing belongs in the charter; capability Goal is the observable outcome. +1. **Goal** — one sentence: what the user can observe when this works. Diagnosis-side framing belongs in the charter; capability Goal is the observable outcome. Do not run Goals through the 3-axis predicate test; use plain-language observability instead. 2. **In-scope / Out-of-scope** — what this capability owns, and the boundary it deliberately respects. Out-of-scope prevents creep. 3. **Expected Behaviors** — three verifiable predicates. Each one must pass the 3-axis test below. Reject and rewrite until it does. 4. **Hard Constraints** — two bright-lines this capability never crosses, even if asked. Adversarial-Goodhart defenses live here. @@ -98,10 +98,12 @@ Every Behavior and Hard Constraint must pass all three axes before it is committ A predicate that passes all three is committable. A predicate that fails any axis is rewritten or split, never rubber-stamped. +Classify positive normal outcomes as Expected Behaviors. Classify bright-line negations and anti-Goodhart guards as Hard Constraints. When both forms fit, prefer the Hard Constraint only when the negative form protects against an optimization or data-loss shortcut. + ## Writing Rules On first run, copy `templates/capabilities.md` to `spec/capabilities.md` at the repo root, then walk the interview for one capability. On rerun, edit only the named capability block and leave the rest of the file untouched. -After applying an accepted change, do not bump a revision number on `spec/capabilities.md`; `git blame` is the source of truth. Note in the conversation which capability was edited. +After applying an accepted change, do not bump a revision number on `spec/capabilities.md`; `git blame` is the source of truth. Note in the conversation which capability was edited. Echo charter Decisions at capability level only when they explain a Behavior or Hard Constraint; promote cross-cutting capability Decisions through `spec-charter amend`. See `references/capabilities.md` for additional grill heuristics and [`../spec-charter/SKILL.md`](../spec-charter/SKILL.md) for the project-wide charter layer. diff --git a/skills/spec-grill/references/capabilities.md b/skills/spec-grill/references/capabilities.md index b9fa1fa..cee1a0c 100644 --- a/skills/spec-grill/references/capabilities.md +++ b/skills/spec-grill/references/capabilities.md @@ -42,6 +42,8 @@ Bad Goal lines usually describe diagnosis, implementation, or an internal tool. Move diagnosis-side framing to the charter Problem. Move scripts and file names to In-scope unless the script is the user-visible surface. +Goals are not 3-axis predicates. Use a lighter check: can a user or operator observe the outcome in plain language without instrumentation? If yes, the Goal is committable. If no, sharpen the outcome, but do not force authority / distributional / manipulability wording into the Goal. + ## Behavior vs. Hard Constraint Use Behaviors for expected positive outcomes. Use Hard Constraints for bright lines that remain true even when a user asks for the tempting shortcut. @@ -55,6 +57,19 @@ Use Behaviors for expected positive outcomes. Use Hard Constraints for bright li Avoid "never do X unless asked" as a Hard Constraint. The phrase "unless asked" is a loophole. If explicit user consent is valid, make it a Behavior with the consent condition. +Tie-breaker: + +- Positive normal outcome -> Expected Behavior. +- Bright-line negation or anti-Goodhart guard -> Hard Constraint. +- If both are valid, prefer the Hard Constraint only when the negative form blocks an optimization shortcut, silent mutation, or data-loss shortcut. + +Example pair: + +| Same intent | Better placement | Why | +|---|---|---| +| "Default triage is advisory and mutations require `--apply`." | Expected Behavior | It describes the ordinary user-visible flow and valid consent path. | +| "Never close, relabel, or comment on an issue without `--apply`." | Hard Constraint | It protects the GitHub source of truth against silent mutation. | + ## 3-Axis Test Examples ### Manipulability failure @@ -112,6 +127,25 @@ It must not touch: If a rerun discovers a cross-cutting decision, append it to the relevant Decisions table or promote it to `spec/charter.md` via amend mode. Do not rewrite old Decisions rows. +## Decisions Seeding + +Capability-level Decisions should explain local contract choices, not duplicate the charter. + +Use this rule: + +- Echo a `spec/charter.md` Decision at capability level only when its rationale is needed to understand a Behavior or Hard Constraint in that capability. +- Leave Decisions empty when the charter row is merely historical context; the cross-cutting record already lives in `spec/charter.md`. +- Put capability-only Decisions in that capability block. +- Promote any capability Decision that affects more than one capability through `spec-charter amend`; append a new charter Decision instead of rewriting old rows. + +Examples: + +| Situation | Placement | +|---|---| +| "Alignment Check is prompt-driven" explains why `triage-grooming` has no `triage-align.js`. | Echo at `triage-grooming` level. | +| "New charter files live under `spec/`" affects multiple spec skills. | Keep/promote in `spec/charter.md`; echo only where it explains a constraint. | +| "`sync-pull --update` preserves non-machine-managed bodies." | Capability-only Decision under `backlog-sync`. | + ## Capability Count Guidance Capability count is a readability budget, not a feature count. Keep the single-file `spec/capabilities.md` while it stays compact enough for an agent to read at session start.