part five · amigos & gherkin

Amigos & Gherkin

The trio session that produces shared meaning before code begins.

Amigos is a 45-minute session where the trio — PO, Developer (often Tech Lead), QA — takes one story and produces named Gherkin scenarios. It is the smallest unit of shared meaning between phases. Without it, the story produces three different features in three different heads, and they meet for the first time in PR review.

The session

Time	What happens
0–5 min	The PO reads the story aloud. The journey reference is on screen.
5–15 min	The trio walks the states section. Each state surfaces or refines one or more scenarios.
15–30 min	The trio writes Given/When/Then scenarios collaboratively. QA leads the Then. Developer leads the When. PO leads the Given.
30–40 min	The trio attacks each scenario. Where else does this break? What else should we test?
40–45 min	Sign-off. The story is ready for code.

The session is bounded. It does not run long. If 45 minutes is not enough, the story is too large; split it.

What the trio produces

For each story, a named set of Gherkin scenarios. Three or more, including at least one negative.

Scenario: Hebrew name renders correctly on first load
  Given Gal is logged in as a grader
    And there is a submission from a student named "Yael Rosenberg-Hayut"
  When Gal opens the grading queue
  Then the student's name is displayed as "Yael Rosenberg-Hayut"
    And no encoding warnings are present in the application log

Scenario: Hebrew name with mixed forms renders correctly
  Given Gal is logged in as a grader
    And there is a submission from a student named "אריאל שמעון-לוי"
  When Gal opens the submission
  Then the student's name renders correctly in both the queue and review screens
    And the right-to-left layout is applied to the name field

Scenario: Name with rare unicode form falls back gracefully
  Given Gal is logged in as a grader
    And a submission contains a unicode form not in the supported set
  When Gal opens the submission
  Then the name is displayed with the unicode-fallback character
    And a system warning is logged for review
    And Gal can still grade the submission without re-typing

The scenarios are written from the person's vantage. Given Gal is logged in — not Given the user has a session token. Gherkin that loses the person becomes Gherkin that the QA cannot defend.

Why the trio

Each role brings something the others cannot.

• The PO holds the brief and the prediction. They keep the scenarios pointed at what the cycle is checking.
• The Developer holds the system. They surface what is implementable and what would require unscoped work.
• The QA holds the failure imagination. They surface the negative cases, the edge cases, the what if the network drops questions.

Amigos with two roles is not amigos. The third role is what catches the gap the other two would have shipped.

What amigos is not

• Not a planning meeting. Stories are not pulled into the sprint here; they are made ready here. Pulling happens at sprint planning.
• Not a code review. The scenarios describe behavior, not implementation. Implementation is the developer's later choice — the scenarios constrain it, not the reverse.
• Not a workshop. 45 minutes. One story. Two stories per amigos session, max, if both are small.

When amigos surfaces a problem

Common problems and their fixes.

What surfaces	Fix
The story is missing a state	Story goes back to the PO; rewrite, return to amigos
The story is too large	Split. Sometimes here in the session; sometimes the PO takes it away
A technical assumption is wrong	Story is paused. Spike opened. ADR may be needed
The Gherkin keeps drifting into UI	The story is pointed at the wrong moment; rewrite
Three scenarios isn't enough	Add more until the trio agrees the story is defensible

After amigos

The Gherkin scenarios live next to the story, not in a separate document. They are linked from the brief. They become the test scenarios in Volume IV — sometimes lightly edited for technical fit, but the names and the Then statements stay.

Amigos that produces good scenarios produces a story that the developer can build, the QA can verify, the PO can accept — without further conversation.

Part 6 — Architecture Decision Records →