@colmbyrne/specflow - npm Package Compare versions

Comparing version

0.8.1

0.8.2

+37

templates/loops/teardown-walkthrough-mandate.md

		# teardown-walkthrough-mandate@v1

		Static, versioned method for the daily-use-teardown's investigate and deep-dive stages. The walker references this file by id — it never inlines instructions, and the author's expectations of "what should work" have no place in it. Same pattern as `adversary-mandate@v1`: changing the method is a deliberate, reviewable act (bump to `@v2`, don't edit `@v1`).

		## Persona construction (investigate stage) — JTBD-grounded, not demographic

		A persona here is a job, not a profile. For each proposed persona, state:
		1. The job-to-be-done — what outcome are they hired-by-the-user to achieve today? ("clear the overnight alert queue before 9am", not "Sarah, 34, likes efficiency").
		2. Frequency + stakes — daily/weekly? what breaks if they fail?
		3. Their entry point and exit condition — where do they start, and what does "done" look like to them?
		Propose 2–4. The human confirms or corrects them at the sign-off — a wrong persona walks the wrong day.

		## The walk (deep-dive stage) — a cognitive walkthrough, not a tour

		For each journey × persona, at every step ask the four cognitive-walkthrough questions:
		1. Does the persona know what they're trying to do at this step?
		2. Is the right action visible? (discoverability)
		3. Will they connect the action to their goal? (does the label/affordance say what it does?)
		4. After acting, does feedback confirm progress? (or are they guessing whether it worked?)

		A "no" on any question = a stall → screenshot (URL bar visible) + note which question failed. That's what makes a CONFUSING verdict actionable instead of vibes.

		## Naming findings — use the vocabulary, it sharpens the do-list

		- discoverability — the control exists but the persona can't find it
		- affordance — found it, but it doesn't look actionable / doesn't say what it does
		- feedback — acted, but no confirmation; the persona can't tell if it worked
		- mental-model mismatch — the app's flow contradicts how the persona thinks the task works
		- slip vs mistake — mis-click on a known path (slip) vs wrong path chosen confidently (mistake — the dangerous one)
		- dead end — no route from here to the goal without backtracking

		## Output discipline

		- Verdict per journey: WORKS / CONFUSING / BROKEN. CONFUSING is always [hypothesis] — you are a simulation of a user, not a user. Name the failed walkthrough question + the vocabulary term.
		- BROKEN = the journey cannot achieve its purpose (correctness), with the step + evidence.
		- Observations only — never propose the fix (that's the PRD's job, behind the adversary).
		- Every claim has a screenshot under `evidence/`, referenced from the finding. No evidence, no finding.

+8

-0

CHANGELOG.md

		@@ -9,2 +9,10 @@ # Changelog

		## 0.8.2 (2026-06-10)

		Teardown gets a method: `teardown-walkthrough-mandate@v1` (JTBD personas + cognitive walkthrough).

		The investigate/deep-dive stages now reference a versioned UX method by id (same pattern as the adversary's mandate): personas are constructed as JTBD jobs, not demographic profiles; every walk step answers the 4 cognitive-walkthrough questions (knows the goal? action visible? action↔goal connection? feedback?); findings are named with a fixed vocabulary (discoverability / affordance / feedback / mental-model / slip-vs-mistake / dead-end) — so a CONFUSING verdict says which question failed instead of vibes. A richer local UX skill may exceed this floor; it never replaces the output discipline. Ships via `specflow init`.

		---

		## 0.8.1 (2026-06-10)
		@@ -11,0 +19,0 @@

+1

-1

package.json

		{
		"name": "@colmbyrne/specflow",
		"version": "0.8.1",
		"version": "0.8.2",
		"description": "Specs that enforce themselves. Contract tests, journey hooks, and agent orchestration for LLM-driven development.",
		@@ -5,0 +5,0 @@ "license": "MIT",

+14

-3

templates/loops/daily-use-teardown.yaml

		@@ -43,2 +43,9 @@ # daily-use-teardown.yaml — the front door for products ALREADY BUILT.

		walk_mandate: teardown-walkthrough-mandate@v1 # the METHOD for investigate + deep_dive: JTBD persona
		# construction, the 4 cognitive-walkthrough questions,
		# findings vocabulary. Referenced by id, never inlined —
		# same pattern as the adversary's mandate. A richer local
		# UX skill (e.g. a jtbd-ux-designer) may EXCEED this floor,
		# never replace its output discipline.

		stages:
		@@ -49,3 +56,4 @@ - id: investigate # what ARE the journeys?
		parseable line "- J: <id> — <purpose>" (what is a user trying to achieve here?), with entry
		points and who uses it. Propose the personas if not supplied, and state the env (URL +
		points and who uses it. Propose the personas if not supplied — constructed per the
		walk_mandate (JTBD: a persona is a job, not a profile) — and state the env (URL +
		backend) the walk will use. Output: a ONE-PAGE journey map a human can review in five
		@@ -72,4 +80,7 @@ minutes. No judgments yet — inventory, not critique.
		For each CONFIRMED journey × persona: walk the CONFIRMED env via a COMMITTED Playwright
		script (walk_script — reproducible, not narrated) as that persona doing their normal task.
		Judge BOTH: (a) clarity — where does the persona stall, squint, mis-click? and (b)
		script (walk_script — reproducible, not narrated) as that persona doing their normal task,
		applying the walk_mandate's method: at EVERY step, the 4 cognitive-walkthrough questions
		(knows the goal? action visible? action↔goal connection? feedback?), findings named with
		its vocabulary (discoverability / affordance / feedback / mental-model / slip-vs-mistake /
		dead end). Judge BOTH: (a) clarity — where does the persona stall, squint, mis-click? and (b)
		correctness — does the journey achieve its purpose, doing the right thing? Capture a
		@@ -76,0 +87,0 @@ screenshot at every stall/surprise/dead-end, URL BAR VISIBLE, saved under evidence/ and

		# teardown-walkthrough-mandate@v1

		Static, versioned method for the daily-use-teardown's investigate and deep-dive stages. The walker references this file by id — it never inlines instructions, and the author's expectations of "what should work" have no place in it. Same pattern as `adversary-mandate@v1`: changing the method is a deliberate, reviewable act (bump to `@v2`, don't edit `@v1`).

		## Persona construction (investigate stage) — JTBD-grounded, not demographic

		A persona here is a job, not a profile. For each proposed persona, state:
		1. The job-to-be-done — what outcome are they hired-by-the-user to achieve today? ("clear the overnight alert queue before 9am", not "Sarah, 34, likes efficiency").
		2. Frequency + stakes — daily/weekly? what breaks if they fail?
		3. Their entry point and exit condition — where do they start, and what does "done" look like to them?
		Propose 2–4. The human confirms or corrects them at the sign-off — a wrong persona walks the wrong day.

		## The walk (deep-dive stage) — a cognitive walkthrough, not a tour

		For each journey × persona, at every step ask the four cognitive-walkthrough questions:
		1. Does the persona know what they're trying to do at this step?
		2. Is the right action visible? (discoverability)
		3. Will they connect the action to their goal? (does the label/affordance say what it does?)
		4. After acting, does feedback confirm progress? (or are they guessing whether it worked?)

		A "no" on any question = a stall → screenshot (URL bar visible) + note which question failed. That's what makes a CONFUSING verdict actionable instead of vibes.

		## Naming findings — use the vocabulary, it sharpens the do-list

		- discoverability — the control exists but the persona can't find it
		- affordance — found it, but it doesn't look actionable / doesn't say what it does
		- feedback — acted, but no confirmation; the persona can't tell if it worked
		- mental-model mismatch — the app's flow contradicts how the persona thinks the task works
		- slip vs mistake — mis-click on a known path (slip) vs wrong path chosen confidently (mistake — the dangerous one)
		- dead end — no route from here to the goal without backtracking

		## Output discipline

		- Verdict per journey: WORKS / CONFUSING / BROKEN. CONFUSING is always [hypothesis] — you are a simulation of a user, not a user. Name the failed walkthrough question + the vocabulary term.
		- BROKEN = the journey cannot achieve its purpose (correctness), with the step + evidence.
		- Observations only — never propose the fix (that's the PRD's job, behind the adversary).
		- Every claim has a screenshot under `evidence/`, referenced from the finding. No evidence, no finding.

@colmbyrne/specflow - npm Package Compare versions

Improved metrics