feat(TASK-001): add rigor/surfaces declaration layer to planning skills
design-session: Quality bar round in Step 2 (rigor/surfaces proposal, per-surface confirm/drop, other:<label> lane, autonomous fallback), rigor+surfaces frontmatter and Quality bar section in the Step 3 PLAN template, poc-dodge anti-pattern. task-tracking: optional per-task surfaces key (inherits the plan's list); rigor stays run-level only. plan-gatekeeping: manifest category 11 (Quality bar) with FRICTION/BLOCKING severity guidance.
This commit is contained in:
@@ -31,6 +31,18 @@ Produce a structured proposal (iterate with the user when interactive — load t
|
|||||||
- **Open questions** — ONLY questions the codebase cannot answer (business rules, priority calls). If none, say "No open questions."
|
- **Open questions** — ONLY questions the codebase cannot answer (business rules, priority calls). If none, say "No open questions."
|
||||||
- **Task breakdown** — see below.
|
- **Task breakdown** — see below.
|
||||||
|
|
||||||
|
## Quality bar round (closes Step 2)
|
||||||
|
|
||||||
|
The last round of Step 2 sets the plan's quality bar. It is grilling-compatible — run it as numbered questions, each carrying a recommended answer, like any other frontier round:
|
||||||
|
|
||||||
|
1. **Propose `rigor`** — one of `poc | prototype | production` (default `production`). Infer the recommended value from the design doc's own language: "spike"/"demo" → `poc`; "iterate"/"internal" → `prototype`; otherwise `production`. Rigor calibrates which review-finding severities BLOCK downstream work: 🔴-critical findings block at EVERY rigor; at `poc`, suggestion/nitpick-level (🟢/💡) convention findings may be dropped from reports entirely. Anything a lower rigor defers is tracked as a follow-up — never silently dropped.
|
||||||
|
2. **Propose `surfaces`** — zero or more of the closed enum: `rest-api`, `cli`, `library`, `worker`, `iac`, `db-migration`, `frontend`, `ci-cd` (`grpc`/`graphql` are aliases for `rest-api`), plus the escape hatch `other:<label>` for anything outside it. Infer from the approach: an HTTP handler → `rest-api`, a schema change → `db-migration`, and so on.
|
||||||
|
3. **Per-surface confirm/drop** — for each accepted surface, present the headline best practices its reviewers will enforce and let the user confirm or drop each one. Every drop demands a one-line reason and lands in the plan's `## Quality bar` section — a dropped practice without a recorded reason WILL be re-litigated by a reviewer.
|
||||||
|
|
||||||
|
For an `other:<label>` surface no reviewer checklist exists, so the lane is: a librarian lookup distills an authoritative best-practice checklist for the label; the user confirms or drops each item; accepted items become task acceptance criteria where possible, otherwise they live under `## Quality bar → Long-tail criteria`. (The architect drives the lookup; this skill documents the shape the results take in the plan.)
|
||||||
|
|
||||||
|
Autonomous runs (no user to grill): take the inferred values, drop nothing, and note "quality bar inferred, not user-confirmed" in the plan.
|
||||||
|
|
||||||
## Task breakdown rules
|
## Task breakdown rules
|
||||||
|
|
||||||
| Rule | Why |
|
| Rule | Why |
|
||||||
@@ -51,6 +63,8 @@ Write `PLAN-<slug>.md` (kebab-case slug from the topic; verify no collision) to
|
|||||||
slug: <slug>
|
slug: <slug>
|
||||||
status: draft # draft | active | implemented
|
status: draft # draft | active | implemented
|
||||||
created: YYYY-MM-DD
|
created: YYYY-MM-DD
|
||||||
|
rigor: production # poc | prototype | production; omitted = production
|
||||||
|
surfaces: [] # from the closed enum and/or other:<label>; omitted = []
|
||||||
---
|
---
|
||||||
|
|
||||||
# <Title>
|
# <Title>
|
||||||
@@ -60,6 +74,7 @@ created: YYYY-MM-DD
|
|||||||
## Approach
|
## Approach
|
||||||
## Alternatives considered
|
## Alternatives considered
|
||||||
## Constraints and risks
|
## Constraints and risks
|
||||||
|
## Quality bar
|
||||||
## Open questions
|
## Open questions
|
||||||
## Task breakdown
|
## Task breakdown
|
||||||
|
|
||||||
@@ -67,6 +82,8 @@ created: YYYY-MM-DD
|
|||||||
|---|------|------|-----------|-------|
|
|---|------|------|-----------|-------|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`## Quality bar` records the quality-bar round in human-readable form: the rigor line with its one-line reason, the surfaces line, the dropped-practices list (each entry with its one-line reason and the date it was decided), and the long-tail criteria block (`none`, or the distilled checklist for each `other:<label>` surface).
|
||||||
|
|
||||||
The plan is the implementers' entire context. Write for the "sealed container" standard: every question an implementer will hit is either answered inline or delegated via a pointer to the exact file/doc that answers it (where infra code goes, what DB tech, which layout to mirror, exact test commands). Paste short code snippets for load-bearing patterns — a path alone forces re-exploration; a stale claim fails the executor mid-implementation.
|
The plan is the implementers' entire context. Write for the "sealed container" standard: every question an implementer will hit is either answered inline or delegated via a pointer to the exact file/doc that answers it (where infra code goes, what DB tech, which layout to mirror, exact test commands). Paste short code snippets for load-bearing patterns — a path alone forces re-exploration; a stale claim fails the executor mid-implementation.
|
||||||
|
|
||||||
## Anti-patterns
|
## Anti-patterns
|
||||||
@@ -77,3 +94,4 @@ The plan is the implementers' entire context. Write for the "sealed container" s
|
|||||||
- Acceptance criteria describing implementation ("uses a for loop") instead of behavior.
|
- Acceptance criteria describing implementation ("uses a for loop") instead of behavior.
|
||||||
- Open questions the code could have answered — grep first, ask last.
|
- Open questions the code could have answered — grep first, ask last.
|
||||||
- Unrecorded decisions — every settled fork carries its reason.
|
- Unrecorded decisions — every settled fork carries its reason.
|
||||||
|
- Declaring `rigor: poc` to dodge review findings the user never agreed to drop.
|
||||||
|
|||||||
@@ -31,9 +31,12 @@ Walk EVERY category. For each, ask: "when the implementer hits this, does the pl
|
|||||||
| 8 | **Config, secrets & environments** | New env vars/config keys — where are they declared and injected? Secrets — vault/parameter store conventions? Staging vs production differences that affect implementation? |
|
| 8 | **Config, secrets & environments** | New env vars/config keys — where are they declared and injected? Secrets — vault/parameter store conventions? Staging vs production differences that affect implementation? |
|
||||||
| 9 | **Scope boundaries** | Is Out of scope present and specific? Are "tempting adjacent fixes" explicitly deferred? |
|
| 9 | **Scope boundaries** | Is Out of scope present and specific? Are "tempting adjacent fixes" explicitly deferred? |
|
||||||
| 10 | **Settled decisions** | Are choices that were debated recorded WITH their one-line reason ("RDS over in-cluster Postgres because ops owns backups")? An unrecorded decision WILL be re-litigated by the implementer. |
|
| 10 | **Settled decisions** | Are choices that were debated recorded WITH their one-line reason ("RDS over in-cluster Postgres because ops owns backups")? An unrecorded decision WILL be re-litigated by the implementer. |
|
||||||
|
| 11 | **Quality bar** | Are `rigor` and `surfaces` declared (or the plan explicitly generic)? Is every dropped best practice recorded WITH a one-line reason? Does every `other:<label>` surface carry non-empty long-tail criteria? |
|
||||||
|
|
||||||
Not every category applies to every plan (a docs-only plan has no data layer). Mark inapplicable categories as such — silently skipping one is how leaks survive.
|
Not every category applies to every plan (a docs-only plan has no data layer). Mark inapplicable categories as such — silently skipping one is how leaks survive.
|
||||||
|
|
||||||
|
For category 11 specifically: a missing Quality bar declaration is FRICTION when the plan is plausibly `surfaces: []` (a docs-only or pure-refactor plan), BLOCKING when the plan self-evidently builds an enum surface (an HTTP API, a CLI, migrations…) but declares none.
|
||||||
|
|
||||||
## Pointer verification (do not trust, verify)
|
## Pointer verification (do not trust, verify)
|
||||||
|
|
||||||
For every pointer the plan offers:
|
For every pointer the plan offers:
|
||||||
|
|||||||
@@ -28,6 +28,7 @@ points: 1.0 # engineer-days; ~1.0 per the sizing rule
|
|||||||
plan: PLAN-<slug>.md
|
plan: PLAN-<slug>.md
|
||||||
blocked_by: [] # TASK ids that must be complete first
|
blocked_by: [] # TASK ids that must be complete first
|
||||||
created: YYYY-MM-DD
|
created: YYYY-MM-DD
|
||||||
|
surfaces: [] # this task's surfaces; omitted = inherit the plan's list
|
||||||
---
|
---
|
||||||
|
|
||||||
## What
|
## What
|
||||||
@@ -47,6 +48,8 @@ One paragraph: what this task produces, named concretely (files, symbols, behavi
|
|||||||
|
|
||||||
Status lives in frontmatter — there are no lifecycle directories. `status: complete` plus all boxes checked IS done.
|
Status lives in frontmatter — there are no lifecycle directories. `status: complete` plus all boxes checked IS done.
|
||||||
|
|
||||||
|
`surfaces` come from the plan's `## Quality bar`; rigor is run-level only — there is no per-task rigor.
|
||||||
|
|
||||||
## log.md conventions
|
## log.md conventions
|
||||||
|
|
||||||
Append-only. Each entry is an H2: `## YYYY-MM-DD — <short label>` (`created`, `started`, `implemented`, `diverged`, `completed`, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.
|
Append-only. Each entry is an H2: `## YYYY-MM-DD — <short label>` (`created`, `started`, `implemented`, `diverged`, `completed`, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.
|
||||||
|
|||||||
Reference in New Issue
Block a user