practice · stories & scope

Holding amigos

Forty-five minutes. Three roles. One story. The smallest unit of shared meaning in the chain. Without amigos, the story produces three different features in three different heads — and they meet for the first time in PR review.

TL;DR

Amigos is a 45-minute session that takes one ready story and produces a named Gherkin set. Three roles are mandatory: PO (holds the brief), Developer (holds the system), QA (holds the failure imagination). Two roles is not amigos. The session produces three or more Gherkin scenarios including at least one negative. If 45 minutes is not enough, the story is too large; split it.

What it is

Amigos is the session named in What We Shape · Amigos & Gherkin. It sits between story writing and code. Its output is a Gherkin set that constrains implementation without prescribing it.

Distinguish from

Planning — pulling stories into the sprint; amigos makes stories ready, planning pulls them. Code review — reviews implementation; amigos reviews behaviour. Kickoff — opens an Epic; amigos opens a story. See Confusable with at the foot.

Why it matters

Without amigos:

• Three roles ship three features. The PO's intent, the developer's interpretation, and the QA's tests diverge silently.
• Negative cases arrive late. QA writes them after merge; the developer has to patch them in.
• Stories that should be split, don't. Amigos is the discipline that surfaces "this is two stories" in 45 minutes, not in a five-day spike.
• The trio's shared vocabulary decays. Each amigos is also vocabulary maintenance — the team re-anchors on what queue, grader, normalised name mean this week.

How to do it

Step 1 — Pull a ready story

Only one story per amigos (two if small). The story must pass Story · DoR before amigos. Amigos is not for surfacing every DoR gap — it is for producing Gherkin from a story whose moment, journey reference, states, and ACs are already named.

Step 2 — Open with the PO reading the story aloud (5 min)

The journey reference is on screen. The PO reads the as–I want–so that and walks the J-step. The trio sees the moment.

Step 3 — Walk the states section together (10 min)

For each state — empty, loading, success, error, edges — the trio asks: what does this look like for the named person? States either refine a scenario or surface a new one.

Step 4 — Write Gherkin collaboratively (15 min)

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

Role leadership at amigos:

• PO leads the Given — they hold the person's situation.
• Developer leads the When — they hold what the system does.
• QA leads the Then — they hold what gets observed.

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

Step 5 — Attack each scenario (10 min)

For each one: where else does this break? what else should we test? This is QA's lead but everyone contributes. The negative scenario is born here.

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

Step 6 — Sign off (5 min)

The trio signs. Three signatures or the story is not amigos-complete.

What amigos surfaces

Three honest outcomes happen at amigos:

1. The story is ready. Sign and proceed.
2. The story is too large. Split it; both halves return to amigos next.
3. The brief is wrong. Send the story back to the Feature Brief level. This is rare and important. The amigos session is the corpus's last cheap discovery checkpoint before code.

See Canon · When amigos surfaces a problem.

Evidence

Across our cycles, amigos that produced durable scenarios shared three properties.

1. The negative scenario was not generic. 401 on bad auth is generic and skip-able by all three roles. Unicode form not in supported set falls back gracefully and grade still submits is moment-specific.
2. All three roles had read the brief before amigos. Sessions where one role was reading the brief during amigos ran 1.5× longer and produced 30% fewer scenarios.
3. The session was bounded at 45 minutes. Sessions that ran 60+ minutes produced more scenarios but lower-quality ones — the trio drifted from the moment.

Anti-patterns

Pattern	What it looks like	Where to fix
Two-amigos	The QA didn't show; trio is two	Reschedule. Two-role amigos is not amigos.
Amigos as planning	Stories get pulled into the sprint here	Wrong meeting. Planning happens after amigos.
Amigos as code review	Trio debates implementation	Scenarios constrain behaviour, not the implementation choice. Hand the how back to the developer.
Rubber-stamping	All scenarios are happy paths; QA brings no anti-flow	The trio has stopped pushing back. Re-read Canon · When amigos surfaces a problem
45 minutes is never enough	Every session runs an hour	The stories are too large. Split before amigos.
Gherkin in system-state language	Given the user has a session token…	Rewrite Given lines from the person's vantage

Confusable with

This	Not this	Difference
Amigos	Planning	Amigos = ready; planning = pulled
Amigos	Kickoff	Kickoff = the Epic begins; amigos = the story is ready
Gherkin	Test cases	Gherkin = behaviour, named from the person; test cases = implementation of the behaviour
Negative scenario	Validation test	Validation is generic; negative scenarios are moment-specific

Further reading

• Canon — What We Shape · Amigos & Gherkin · Story Writing
• Practice — Story writing
• Template — Gherkin scenario set
• Checklist — Amigos 45-minute agenda · Story · DoR
• Clinic — A story without a state
• Skill path — PO foundations · Step 6 · QA foundations · Step 3 · Developer foundations · Step 6
• Reference — Area · Amigos · Area · Gherkin