jonnifyagile agents
jonnify / Agile Agent Workflow / A4 · Spec / A4.3 / A4.3.2 · The five Ws

A4.3 · Anatomy of a spec · dive 2

The five Ws

The Rationale section answers five questions — why, what, who, when, where — fixing a rung's reason before its definition.

Each W is a single bold bullet: why the rung is built, what lands, who it serves, when it depends on, and where the code lives. The five Ws keep a spec honest about intent, so an Author never has to invent it. Pick a W on the right to read its answer verbatim from the Portal's real spec rung .

The five questions Match a fact to its W On the Portal References

Pick a W · read its answer on f6.1.md

Why — the reason it is built What — what lands Who — whom it serves When — what it depends on Where — where the code lives
Why · the reason it is built · verbatim: "F5 produced a correct engine but no way for a human to reach it over HTTP".

The five questions

The Rationale is the spec's second section, and it answers the reason for a rung in five bold bullets — Why, What, Who, When, Where. Why states the problem; What states the increment; Who names the roles it serves; When fixes the dependency and position in the ladder; Where names the place in the codebase. Together they pin intent before the spec defines anything, so an Author reading the rung never has to guess at the reason it exists.

The hero figure reads each W's answer. Below, each is named with a verbatim phrase from the Rationale — the exact words, because intent stated loosely is intent an Author will fill in wrong.

Why
The problem, verbatim: “F5 produced a correct engine but no way for a human to reach it over HTTP. The platform needs a web front door…”.
What
The increment, verbatim: “a running Phoenix endpoint wired into the existing supervision tree, serving one facade-backed page and a liveness route…”.
Who
The roles, verbatim: “Operators (run and serve the platform), Visitors (load a page and see real data), Developers (keep the domain core untouched…)”.
When
The position, verbatim: “the first rung of the F6 value ladder; depends only on the F5.08 / F5.09 handoff…”.
Where
The place, verbatim: “a new umbrella app apps/portal_web”.

The What names the one facade call this rung makes — Portal.courses_of/1, which returns the courses a user is enrolled in. The Rationale states the intent; it shows no code.

Match a fact to its W

Every sentence in a Rationale answers exactly one of the five Ws. That is the discipline that keeps the section tight: a fact about a dependency belongs under When, not Why; a fact about a file belongs under Where, not What. Reading a spec well means asking, of each line, which W is this answering?

The figure below holds five facts drawn from the Rationale and asks which W each one answers. The move is the inverse of the hero: there you pick a W and read its answer; here you read a fact and place it under its W.

Which W does this fact answer? · pick a fact

"depends only on the F5.08 / F5.09 handoff" Why What Who When Where each fact answers exactly one W · a dependency is When, a file is Where
"depends only on the F5.08 / F5.09 handoff" · answers When — it fixes the rung's dependency and its position in the ladder.

Each W answers one question, and each Rationale fact answers exactly one W — a dependency is When, a file is Where.

The five Ws on the Portal

On the Portal — the learning platform this course builds — the real Rationale is the second section of , the spec for standing the engine up as a Phoenix app. Its five bullets are the reason for the rung: Why there was no HTTP front door; What lands (a Phoenix endpoint serving one facade-backed page and a liveness route); Who it serves (Operators, Visitors, Developers); When it sits (first rung of F6, on the F5 handoff); and Where the code lives (a new umbrella app apps/portal_web).

The fragment below is the five bullets, verbatim, with each W's question in a comment. It is markdown prose, not code — the Rationale's job is to state intent in words an Author cannot misread. Read it and the reason for the rung is fixed before a single deliverable is named.

# f6.1.md — Rationale (5W), verbatim bullets; the question each answers in comment.

# Why  — the reason it is built
"F5 produced a correct engine but no way for a human to reach it over HTTP."

# What — what lands
"a running Phoenix endpoint wired into the existing supervision tree."

# Who  — whom it serves
"Operators ... Visitors ... Developers."

# When — what it depends on, where in the ladder
"the first rung of the F6 value ladder; depends only on the F5.08 / F5.09 handoff."

# Where — where the code lives
"a new umbrella app apps/portal_web."
the principle

The Rationale answers five Ws — why, what, who, when, where — fixing a rung's intent before its definition, so the reason for the work is never left to inference.

on the Portal

The Rationale names all five, verbatim. An Author reads them and builds the rung without inventing the reason it exists or whom it serves.

The five Ws fix a rung's intent in five bullets — why, what, who, when, where — before the spec defines a single deliverable.

Recap — five bullets, one reason

The Rationale answers five questions — Why, What, Who, When, Where. Each is a single bold bullet, and each Rationale fact answers exactly one of them: a dependency is When, a file is Where. Read on the Portal's real , the five Ws pin a rung's intent before its definition, so the Author never invents the reason for the work. With the reason fixed, the closing dive draws the line every section holds: constrain the build without over-specifying the solution.

Next in A4.3: A4.3.3 · Constrain, not over-specify — the rule that a spec states what must be true, never how to write the code.

References

The sources behind the five-Ws rationale, and where it connects in the course.

Sources

Related in this course