Portal cards

The form and the three Cs become useful when real stories are written in them — so write the Portal vision as cards, each with a confirmation.

The Portal vision is one line: a platform where a learner can find, take, and finish a course. Each verb becomes a capability, attached to a role and a benefit — one card per verb. Each card carries a confirmation written to foreshadow the Given/When/Then of A2.04. Switch the verb on the right to read the card it becomes.

From a vision to cards The confirmation foreshadows A2.04 On the Portal References

One verb of the vision → one card · switch the verb

find → As a learner, I want to browse the catalogue, so that I can choose a course. One verb of the vision becomes one card.

From a one-line vision to cards

The Portal vision is one sentence: a learning platform where a learner can find, take, and finish a course. A backlog is built by turning each verb of the vision into a capability, attached to a role and a benefit. Find becomes browse the catalogue; take becomes enrol; the implicit study becomes open a lesson; finish becomes track progress. Four verbs, four cards — each a Connextra sentence and each a unit of value on its own.

The cards are written against the established Portal surfaces only. The id authority, for instance, is Portal.ID.generate/1 and Portal.ID.decode/1; the OTP internals behind them are the subject of the companion Functional Programming course, cited here, not re-taught. A card names what a learner can do and why — the how is settled in the conversation when the rung is built.

find: As a learner, I want to browse the catalogue, so that I can choose a course.
take: As a learner, I want to enrol in a course, so that I can study it.
open: As a learner, I want to open a lesson, so that I can learn its content.
finish: As a learner, I want to track my progress, so that I can see what is left.

Each verb of the vision is one card; each card is one rung of the backlog the rest of A2 orders into a value ladder.

The confirmation foreshadows A2.04

The third C, the Confirmation, is the acceptance check that says when a card is done. Written in the shape “given a state, when an action, then an observable result”, it is already the skeleton of an A2.04 Given/When/Then scenario. The card states the promise of value; the confirmation states how both sides agree it is delivered.

Switch the card below to read its confirmation split into its given, when, and then parts. The split is what A2.04 turns into an executable acceptance test — the same words, in Gherkin form. Writing the confirmation in this shape now means the acceptance criteria are not invented later; they grow from the card.

A card and its confirmation, split · switch the card

browse · confirmation: given courses exist, when the learner opens the catalogue, then every published course is listed. The confirmation is already a Given/When/Then skeleton (A2.04).

A confirmation written as given / when / then is the seed of the acceptance test — the card grows its own A2.04 scenario.

The four Portal cards

The Portal vision splits into four learner cards, each a Connextra sentence with a confirmation. Together they are the first rungs of the backlog the rest of A2 tests with INVEST (A2.03), turns into Given/When/Then (A2.04), splits when too big (A2.05), and orders into a value ladder (A2.06).

# browse
"As a learner, I want to browse the catalogue, so that I can choose a course."
# confirm: given courses exist, when the catalogue is opened, then every published course is listed

# enrol
"As a learner, I want to enrol in a course, so that I can study it."
# confirm: given a learner not enrolled, when they enrol, then they are enrolled exactly once

# open
"As a learner, I want to open a lesson, so that I can learn its content."
# confirm: given an enrolment, when a lesson in that course is opened, then its content is shown

# track
"As a learner, I want to track my progress, so that I can see what is left."
# confirm: given lessons completed, when progress is viewed, then the completed count is shown

The principle

A vision becomes a backlog by writing each unit of value as a card with a confirmation; the confirmation, in given/when/then shape, is the seed of the acceptance test.

On the Portal

The Portal vision splits into four learner cards — browse, enrol, open, track — each carrying a confirmation A2.04 turns into a scenario the Author builds to and the Operator accepts against.

Write the vision as cards in the form, each with a confirmation — and the backlog, and the seeds of its acceptance tests, are already on the table.

Recap — the vision, written as cards

A2.02 closes with real Portal stories in the Connextra form: the one-line vision split into four learner cards — browse, enrol, open, track — each a sentence with a confirmation, and each confirmation written as a Given/When/Then skeleton the next module turns into an acceptance test. The form gives a story its sentence; the three Cs make it a promise plus a conversation; the cards put both to work on the Portal. The chapter continues with INVEST, the test of whether each of these is a good story.

Back to A2.02 · The Connextra form and the three Cs. Next in the chapter: A2.03 · INVEST — the six tests a well-formed story should pass, and A2.04 turns each confirmation into Given/When/Then.

References

Primary sources for writing stories in the form and the confirmation as acceptance, and where it connects in the course.

Sources

Cohn, M. — User Stories Applied — writing real stories in the form and the confirmation.
Adzic, G. — Specification by Example — the confirmation as a concrete, executable example.
Agile Alliance — User Story Template — the Connextra form each card is written in.

Related in this course

A2.02 · The Connextra form and the three Cs — the module hub.
A2.02.2 · Card, Conversation, Confirmation — the previous dive.
A1.04.2 · The spec layer — the spec the cards' confirmations pin to.
Companion · Functional Programming in Elixir — the Portal's OTP internals.
A2 · Decomposition — the chapter.