edd

Files (19)

• SKILL.md
• acceptance.feature
• expected.md · self-test/01-offramp-all-checkable/
• manifest.json · self-test/01-offramp-all-checkable/
• expected.md · self-test/02-classify-bias-to-offramp/
• manifest.json · self-test/02-classify-bias-to-offramp/
• existing-wizard-transcript.txt · self-test/03-gate-evidence-exists/
• expected.md · self-test/03-gate-evidence-exists/
• manifest.json · self-test/03-gate-evidence-exists/
• expected.md · self-test/04-gate-commission-new/
• manifest.json · self-test/04-gate-commission-new/
• expected.md · self-test/05-reject-narration/
• manifest.json · self-test/05-reject-narration/
• narrated-claim.txt · self-test/05-reject-narration/
• expected.md · self-test/06-blocked-done/
• manifest.json · self-test/06-blocked-done/
• expected.md · self-test/07-living-docs-gate-ran-only/
• manifest.json · self-test/07-living-docs-gate-ran-only/
• README.md · self-test/

SKILL.md (first lines)

# EDD — Expectation-Driven Development

Run Andrea Laforgia's Expectation-Driven Development protocol over a developer's intent: write the
**expectations**, hand the build to the fitting engine, gather **executed evidence** that each one
holds, and put that evidence to the developer, who decides. The protocol's source:
<https://a4al6a.substack.com/p/expectation-driven-development-a>.

This is the **expectation-driven sibling to `phil:work`**, the general contractor for invisible work
(preserve behaviour and hit a checkable goal). Each step reads the standard it applies, where it
applies it.

> **The full flow.** CAPTURE (intent → expectations, checked for coverage, size and risk) → CLASSIFY
> (which kind of evidence) → OPT-OUT (trust the tests for the checkable ones this run?) → BUILD
> (delegate to one engine, inherit its oracle) → EVIDENCE (executed, producer ≠ builder, for every
> expectation not opted out) → REVIEW (an independent adversary, its findings judged) → ADJUDICATE
> (the developer accepts, rejects, challenges or stops) → STABILIZE (pin each accepted expectation;
> review the code) → FINDINGS (clear each blocking finding) → REPAIR (the advisories, by their owners)
> → DOCUMENT (every run that built).

---

## The two lines to hold

1. **A green suite the builder wrote is not proof.** Every expectation gets executed evidence by
   default, with two exceptions, each the developer's call and each recorded explicitly: they may
   trust the tests for a run's checkable expectations, and they may spot-check by hand an expectation
   no agent can run here, or one the agent has twice failed to run. Leave both calls to the developer.
2. **Someone other than the builder grades the work.** Evidence an agent returns must be **executed**
   (a real run or render captured verbatim, not a description) and produced by an agent that is
   **not** the builder; the **developer** adjudicates. A hand spot-check is the one description
   allowed: the developer's own observation, never an agent's.

---

## Every ask

Every question this skill puts to the developer — CAPTURE's confirmation, OPT-OUT, BUILD's
cannot-meet, EVIDENCE's spot-check, ADJUDICATE, FINDINGS, REPAIR's offer, and DOCUMENT's apply and
fitness asks — follows `${CLAUDE_PLUGIN_ROOT}/skills/shared/decision-request.md`.
Load it before the first ask. On top of that standard:

- **Every ask offers `stop`.** A stop before BUILD starts ends the run and writes nothing; a stop once
  BUILD has started writes the trail as it stands and reports the run not done.
- **Unanswered.** An ambiguous or empty reply is unanswered, and two consecutive unanswered asks end
  the run, reported not done. This overrides the standard's "treat it as a decline", which means
  nothing for most of these asks. OPT-OUT alone treats an ambiguous reply as a no.
- **Caps.** Every "second" cap in this skill — a second red oracle, narrated return, cannot-run, fix
  round, prose fix round, reject or challenge — means the second and every one after it.
- **Free text is the developer's.** Every free-text answer is recorded labelled `you wrote` — a
  reject's reason, a challenge's scenario, a waiver's or a drop's reason, a reworded expectation, a
  spot-check's observation. An answer that needs words — a challenge's scenario, a reject's or a
  waiver's reason — comes through the ask's "Other" field or one follow-up ask; an empty follow-up is
  unanswered.
- **The developer's words stay theirs.** Quote a `you wrote` line word for word in the context block;
  in the counted ask, describe it in plain terms, so a path or identifier in it never trips the ask's
  rules.

---

## Parse the argument

| Pattern | Action |
|---|---|
| `"<intent>"` | Run CAPTURE on the intent, then the flow below. |
| No argument | Ask for an intent. No-argument **resume** of an in-flight loop does not exist. |

Derive a kebab-case `<slug>` from the intent for the trail path `docs/edd/<slug>/`. Create it only when
DOCUMENT writes the trail, once BUILD has started.

---

## CAPTURE — intent → expectations

Restate the intent as a list of discrete **expectations**, each a single statement of something the
developer expects to be true when the work is done. Surface qualitative ones explicitly (tone,
clarity, ergonomics, "helpful", "feels X").

Before showing the list, check it the way the article asks:

- **Coverage.** Name each of these categories that no expectation covers, and suggest one for each
  gap:
  - the **happy path**;
  - **past edge cases** — the bugs this area has had before. Ask the developer, or search the
    history (`git log`, the issue tracker, tests that pin old bugs); never invent a past bug;
  - **non-functional requirements** the intent implies — performance, error handling, security, limits;
  - behaviour that **must not happen** — breaking existing behaviour, losing or leaking data, acting
    unasked. An expectation that existing behaviour stays unchanged covers this category.
- **Size.** One expectation is one behaviour the developer could explain to a colleague in a single
  breath. Propose splitting any that takes more than one breath — its parts will classify and route
  differently — and expanding any too thin to test.
- **Risk.** Order the list by risk, worst first, ranked by what a miss would cost: how many users it
  hits, and how hard it is to undo. Evidence and adjudication follow this order, so the developer's
  attention goes where a miss would cost most.

Label every line with its provenance:

- `you wrote` — the developer's words, kept exactly as written; never edit one to fit a standard;
- `composed` — a restatement, suggestion or split this skill wrote;
- `you edited` — a composed line the developer then changed; their edit stands as written.

When splitting a `you wrote` line, keep the original `you wrote` line in the record beside the
halves: the halves are `composed` and live, the original records what the developer said. Read
`${CLAUDE_PLUGIN_ROOT}/rules/writing.md` before composing, and write every composed line to it —
active voice, no needless words, one behaviour per line.

Ask the developer to confirm the list, with the list itself in the context block so the counted ask
stays under its ceiling. The developer may confirm, edit, accept or decline each suggestion, or stop.
Proceed only once the list is confirmed.

---

## CLASSIFY — which kind of evidence

Classification decides what each expectation's evidence must show.

- **checkable** — the target engine's native oracle can produce a pass/fail result at reasonable
  cost:
  - **nwave** (user-facing behaviour) → an acceptance test can assert it (deterministic observable
    output: stdout, response, exit code, state).

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin