expectations-checklist

Files (2)

• SKILL.md
• deferral-phrases.txt

SKILL.md (first lines)

# Expectations Checklist

> **Why this exists.** The init-task file (see `init-task-persistence.md`)
> preserves the operator's *prompt*. The expectations file preserves the
> operator's *acceptance test* — what the operator wants to verify when the
> work comes back. Each item is one human-readable wish: "did this aspect of
> the task come out the way I asked?" Without it, agents run their own
> `/dr-qa` checks against PRD acceptance criteria, which are an agent's
> paraphrase of operator intent and can drift silently.
>
> Expectations are written in the resolved artifact language, one bullet per wish, with a verifiable success
> criterion and an advisory cross-link to a PRD acceptance criterion when
> one exists. `/dr-qa` and `/dr-compliance` assign each item a status
> (`met` / `partial` / `missed` / `n-a` / `deleted`); `partial` or `missed`
> without an operator-supplied override blocks the pipeline and routes work
> back to `/dr-do` with the offending wish-ids in focus.

## File location and naming

```
datarim/tasks/{TASK-ID}-expectations.md
```

One file per task. Same `{TASK-ID}` as the corresponding
`{TASK-ID}-task-description.md` and `{TASK-ID}-init-task.md`. The three
artefacts form a sibling triad:

| File | Author | Purpose |
|------|--------|---------|
| `{ID}-init-task.md` | operator (verbatim) | the original prompt |
| `{ID}-task-description.md` | planner | the agent's interpretation + implementation notes |
| `{ID}-expectations.md` | architect (L3+) / planner (L2 no PRD) | the operator's acceptance test |

## When the file is created

| Complexity | Stage | Agent | Trigger |
|-----------:|-------|-------|---------|
| L3, L4 | `/dr-prd` | architect | after PRD acceptance criteria are finalised |
| L2 (no PRD) | `/dr-plan` | planner | after plan acceptance is finalised |
| L1 | — | — | not required (optional; soft window applies) |

Expectations are **canonical first**, **append-merge after**. The first write
creates the file from PRD/plan AC plus the operator's init-task brief. Later
edits (operator amendments, new AC, scope changes) append new items at the
bottom; existing items are not rewritten — instead a History entry records
the transition.

## Artifact schema

Required YAML frontmatter (closed schema):

```yaml
---
task_id: <TASK-ID>          # ^[A-Z][A-Z0-9]{1,9}-[0-9]{4}$ — required
artifact: expectations      # literal — required
schema_version: 4           # integer — required (current: 4; legacy: 1-3)
captured_at: <YYYY-MM-DD>   # date of first write — required
captured_by: /dr-init       # /dr-init | /dr-prd | /dr-plan — required
status: canonical           # canonical | amended — required (flips on first append)
agent: planner              # architect | planner — recommended
parent_init_task: <path>    # relative path to init-task file — recommended
parent_prd: <path>          # relative path to PRD file when one exists
---
```

**Schema v4 (current default):** requires exactly one
`customer_derived: true | false` field on every wish. The obsolete
`customer_binding_from` marker is rejected because a movable prefix can exempt
previously governed wishes. See § Customer-requirement binding.

**Schema v3 (legacy, accepted):** adds optional per-wish `verification_mode` and
`evidence_artifact` fields distinguishing a one-off manual check from a
reproducible/wired check. See § `verification_mode` axis. Only active when the
file declares `schema_version: 3` or `4`; all sub-v3 files are unchanged.

**Schema v2 (legacy, accepted):** adds required `evidence_type` field per wish item
(enum: `empirical | static | measurement`). Validator
(`"${DATARIM_RUNTIME:?}/dev-tools/check-expectations-checklist.sh"`) rejects items without
`evidence_type` in v2 mode.

**Schema v1 (legacy):** accepted by validator until **2027-05-23** (12 months
from the v1→v2 migration archive). Deprecation warning emitted on every validator
invocation. Migration recipe: add `evidence_type: empirical` (or
`static`/`measurement`) to each wish; bump `schema_version: 2`.

**Migration note — author new files at v4.** `/dr-prd` (and `/dr-plan` for the
L2-no-PRD path) MUST create new expectations files at `schema_version: 4`.
v1-v3 remain accepted for read and verification without customer-binding
fields, but MUST NOT receive new wishes. Before the first append, perform an
explicit metadata-only migration: preserve every existing body, title, history,
order, and `wish_id`; add `evidence_type` where v1 lacks it; add
`customer_derived` to every wish and the conditional binding quartet to each
`true` wish; then bump to schema v4, set `status: amended`, and record the
migration in the append-log. Only then append the new wish. v1 keeps its
**2027-05-23** sunset and deprecation warning.

## Body shape

English presentation is the template default. Localize prose/title/section labels
in the resolved artifact language. Keep field keys and status enums below stable.
Use `<!-- datarim:expectations -->` on a translated Expectations H2. Legacy
Russian field/heading aliases remain readable without rewriting history.
Historical English labels are also accepted: `Operator expectations`,
`Status history`, `Current status`, `How to verify (success criterion)` and
`Related AC from PRD`. Both validators normalize only these known labels to
the canonical keys. New files keep the canonical ASCII keys; arbitrary heading
translations use the Expectations marker below. A wish may link to several
acceptance criteria, and every link must resolve in the spec graph. Wishes in
the exact `Append-log (operator amendments)` and `PRD append-merge` sections
receive the same structural and status validation as the initial checklist.


```markdown
# {TASK-ID} — Operator expectations

## Expectations <!-- datarim:expectations -->

- **<N>. <Plain-language title ending with a period>**
  - wish_id: <stable ASCII kebab-slug; preserve existing legacy IDs>

From Arcanada-one/datarim, MIT.

More from Arcanada-one/datarim