Story smells

INVEST is also a diagnostic. When a story fails its readiness gate, it fails in one of a few recurring ways — a smell that names the letters and the rewrite.

Four smells cover most failures: too big, untestable, coupled, and purely technical. Pick one on the right to highlight the INVEST letters it fails and read the one-line repair. The smell is the symptom; the letters are the diagnosis; the rewrite is the cure.

The four smells The rewrite On the Portal References

Diagnose a smell · the INVEST letters it fails

Too big — fails S (Small) and E (Estimable), and drags I (Independent) down. Repair: split into thinner stories that each ship value.

The four smells

Most stories that fail INVEST fail in one of four recurring shapes. Naming the shape is the fast path to the diagnosis: the smell points at the failing letters, and the letters point at the rewrite.

too big: Fails S and E, and usually drags I down. Spans many turns; no one can estimate it. Repair: split into thinner stories (A2.05).
untestable: Fails T. No concrete confirmation of done — “improve the experience”. Repair: state the observable behaviour that proves it.
coupled: Fails I. Cannot ship until another story is finished. Repair: invert the order, stub the dependency, or merge the inseparable pair.
purely technical: Fails V and T as a unit of value. Names work, not a change a user can do. Repair: name the capability it serves; build the work on the way.

A story can carry more than one smell — “manage the whole catalogue” is too big and so partly coupled. The diagnosis is still the same procedure: read the letters, follow them to the rewrite.

The rewrite is not cosmetic

The hero diagnoses; this view proves the cure changes the score. Take the purely-technical case — “add the courses DB table” — and switch between the smelly sentence and its rewrite. The figure recomputes the INVEST pass count for each. The rewrite moves two letters, V and T, from fail to pass: it is a different story, not a reworded one.

The rewrite names the user-visible capability the work serves — “browse the catalogue” — and lets the table fall out as part of building the rung. The table is still built; it is a means now, not the goal. That single move is what turns a task into a story.

Smelly vs rewritten · the INVEST pass count moves

add the courses DB table — passes 3 / 6 (V and T fail). A task, not a story.

A rewrite that moves V and T from fail to pass is not cosmetic — it turns a task into a story.

The rewrite on the Portal

On the Portal, the most common smell is the purely-technical one, because work is easy to name and value is easy to forget. “Add the courses DB table” fails Valuable — no learner gains anything when it lands — and fails Testable as a unit of value, because a green migration is not a behaviour anyone can be shown. It is a task wearing a story's clothes.

Rewrite it to the story it serves: “As a learner, I can browse the catalogue so that I can see what courses exist.” Now Valuable passes — the learner can do something new — and Testable passes — the catalogue list contains the seeded courses. The table is built as part of the rung, a means rather than the goal. Same work, a story instead of a task.

# Smelly: a task in story clothing.
#   "add the courses DB table"  → V fail, T fail  (3 / 6)

# Rewrite to the capability it serves; the table falls out of building it.
#   "browse the catalogue"      → 6 / 6
# Acceptance is now a demonstrable behaviour, not a schema check:
#   Given the catalogue holds the three seeded courses,
#   when a learner opens the catalogue,
#   then all three are listed.            (T passes — the behaviour is checkable)
# The courses table is built on the way — a means, not the goal.

The principle

A failing story has a smell; the smell names the INVEST letters it fails, and the letters name the rewrite.

On the Portal

“Add the courses DB table” smells purely technical (V, T fail); rewritten to “browse the catalogue” it passes both, and the table is built on the way.

Name the smell, read the failing letters, rewrite to the capability the work serves — and the table is built on the way.

Recap — symptom, diagnosis, cure

Four smells — too big, untestable, coupled, purely technical — cover most stories that fail INVEST. The smell is the symptom; the INVEST letters are the diagnosis; the rewrite is the cure, and it is not cosmetic — on the Portal, rewriting “add the courses DB table” to “browse the catalogue” moves two letters from fail to pass. The too-big smell points at a tension inside INVEST itself: making a story Small can break Independent. The next dive draws that tension and resolves it.

Next in A2.03: A2.03.3 · Small and independent — the tension between the two letters, and how splitting along value satisfies both.

References

The story-quality and example-driven sources behind the smells, and where they connect in the course.

Sources

Wake, B. — INVEST in Good Stories, and SMART Tasks — the tests a smell fails against.
Cohn, M. — User Stories Applied — the failure shapes and how to repair them.
Adzic, G. — Specification by Example — making a vague story testable through concrete examples.

Related in this course

A2.03 · INVEST — the module hub.
A2.03.1 · The six tests — the previous dive.
A2.03.3 · Small and independent — the next dive.
A1.04 · Two layers: roadmap and specs — the spec a rewritten story feeds.
A2 · Decomposition — the chapter.
Companion · Functional Programming in Elixir — the Portal's internals.