Chapter 1 · Session 2

The decision, not the dashboard

Plant software usually starts from a screen someone has seen somewhere else. This session starts from the one decision your plant makes badly today, and writes it on one page before anyone writes code.

25 min1 page6 partsWorked example: a stamping plant

By the end of this chapter you can

Explain why a platform built around a decision beats one built around a dashboard.
Name the six parts of the one-page intent and what each must say.
Tell a decision from a wish, a report or a project title.

Why start with a decision

A dashboard shows data. A decision changes what happens next: a lot is held, a technician goes to line 3, a die is pulled for repair. If the first thing you build does not change a decision, it becomes one more screen that people stop opening after a month.

Systems engineering has said the same for decades: you agree what the system must do, and for whom, before you design it. ISO/IEC/IEEE 29148 calls this stakeholder requirements, and NIST's guide to engineering trustworthy systems puts it before every design step ^[1]^[2]. On a plant floor the stakeholder is usually one person with a clipboard, and the requirement is one decision they make every shift.

The intent drives every later session. The schema stores what the decision needs, the role matrix decides who sees it, the screens show it and the tests prove it. When a test fails, the question is always: built wrong, or written wrong?

The one-page intent

Every Foundation platform starts from a single page with six parts. It is short on purpose. If it takes two pages, you have two problems; pick one.

The one-page intent. Write the parts in order. The first three describe the decision; the last three keep the project honest.

Part	What it must say	A sign it is not ready
1. The decision	The choice made, and the options chosen between	It names a screen or a system instead of a choice
2. Who and how often	One role, and the rhythm: each shift, each hour, each event	"Everyone" or "management"
3. The data it needs	Three to five items, and where each lives today	"All the data"
4. What changes	One or two numbers: today's value and the target	"Better visibility"
5. Not building	What is left out on purpose, with the reason	The list is empty
6. Rules and sign-off	Safety limits, who approves changes, and the decider's agreement	Nobody on the floor has read it

A worked example

The example used through Sessions 2 to 4 is a mid-size metal stamping plant: six presses, two shifts, parts for automotive and appliance customers. Today, first-piece inspection results are written on paper at the press and carried to the quality office. When a first piece fails, the lot keeps running until someone reads the sheet.

docs/INTENT.md: the stamping plant's first intent

THE DECISION
  Hold or release a lot after first-piece and hourly inspection.

WHO AND HOW OFTEN
  The quality lead on shift, at every die change and every hour a press runs.

THE DATA IT NEEDS                       WHERE IT LIVES TODAY
  First-piece result per press         paper sheet at the press
  Gauge readings (key dimensions)      handheld gauge, written down
  Open nonconformances for the part    quality system (spreadsheet)
  Die change log                       whiteboard by press 4
  Customer complaints for the part     email folder

WHAT CHANGES
  Minutes from failed first piece to hold:  today about 95, target 15.
  Lots held with no reason recorded:        today about 40 a quarter, target 0.

NOT BUILDING (YET)
  Full SPC charts, supplier quality, ERP integration, automatic holds.

RULES AND SIGN-OFF
  A person decides every hold; the system never releases a lot by itself.
  Agreed by: quality lead (day shift), quality lead (night shift), plant manager.

Why one decision and not five

The first platform has to work on real shifts, with real people, within weeks. One decision done well earns the trust that gets you the second. Five decisions half done earn a reputation. Lean practice makes the same point with the A3 report: one problem, one sheet of paper, agreed by the people who do the work ^[3].

Knowledge check

Which of these is a decision you could build Session 3's tables from?

Knowledge check

The 'Not building' list on an intent page is empty. What does that usually mean?

References

ISO/IEC/IEEE 29148:2018, Systems and software engineering: requirements engineering. https://www.iso.org/standard/72089.html
NIST SP 800-160 Vol. 1 Rev. 1: Engineering Trustworthy Secure Systems. https://csrc.nist.gov/pubs/sp/800/160/v1/r1/final
Lean Enterprise Institute lexicon: A3 report. https://www.lean.org/lexicon-terms/a3-report/

Chapter 2 · Go and see

Find the decision on the floor

The decision is not found in a meeting room. It is found at the press, in the hands of the person who makes it, with the paper, the whiteboard and the workarounds they use today.

25 min30-minute walk5 questions1 data map

By the end of this chapter you can

Run a short walk and interview with the person who makes the decision.
Map each piece of data to where it lives today and how far it can be trusted.
Measure decision latency: the time from event to decision.

Go and see

Lean manufacturing calls the place where work happens the gemba, and the habit of going there to understand a problem genchi genbutsu: go and see for yourself ^[1]^[2]. For an intent, that means standing next to the quality lead during a die change, not asking about it in an office.

Five questions for the decider

Walk me through the last time you made this decision. Ask for a real one, from this week. Write down every piece of paper, screen and person involved.
What did you wish you had known at that moment? This is the data list.
How long after the event did you find out? This is the latency (below).
What goes wrong when the decision is late or wrong? This is the cost, and usually the measure. Ask "why?" again until you reach a cause, not a symptom ^[3].
What must the system never do on its own? This is the safety rule. In quality, the answer is almost always: never release a lot without a person.

Map where the data lives

For each item on the data list, write where it lives today. Four places cover almost everything on a plant floor: a system of record (ERP, MES, maintenance system), a spreadsheet, a whiteboard or paper sheet, and someone's memory. The further right on that list, the less the data can be trusted and the later it arrives.

The stamping plant's data map. Only two of five items live in a system of record. The die change log is on a whiteboard; first-piece results are on paper until someone types them in.

Data item	Lives today	Who keeps it	Late by	Trust
First-piece result	Paper sheet at the press	Press operator	Up to 2 hours	Medium: legible, sometimes missing
Gauge readings	Handheld gauge, then paper	Press operator	Up to 2 hours	Medium
Open nonconformances	Shared spreadsheet	Quality engineer	A day	Medium: edited by several people
Die change log	Whiteboard by press 4	Setter	Minutes, if you walk there	Low: wiped each week
Customer complaints	Email folder	Quality manager	Days	High, but hard to find

Measure decision latency

Decision latency is the time from the event (a first piece fails) to the decision (the lot is held). It is the easiest thing to measure before you build, and the clearest thing to show afterwards. Time it on three real events with a watch, not from memory.

Decision latency at the stamping plant, to scale. Today a failed first piece reaches the quality lead after about 110 minutes. The target is 10.

Exercise · Walk the decision30 minutes on the floor

You need: A notebook or a phone, a watch, and permission from the area supervisor

Do this with the person who makes the decision you picked, during a real shift. Follow the plant's safety rules for visitors to the floor: eye and ear protection, walkways only.

1. Ask the area supervisor for permission and agree a time when the decision is likely to happen.
2. Stand with the decider and ask the five questions above; write their words, not your summary.
3. List every piece of data they look at, and where each one lives today.
4. Time one real event from the moment it happens to the moment the decision is made.
5. Photograph (where the plant allows it) any workaround: a sticky note, a whiteboard, a private spreadsheet.
6. Read your notes back to the decider and correct anything they disagree with.

Outcome: A data map with five or fewer items, one measured latency, and the decider's own words for what goes wrong.

Knowledge check

Where is the decision for the intent best understood?

Knowledge check

A key data item lives only on a whiteboard that is wiped each week. What does the data map tell you?

References

Lean Enterprise Institute lexicon: gemba. https://www.lean.org/lexicon-terms/gemba/
Lean Enterprise Institute lexicon: genchi genbutsu. https://www.lean.org/lexicon-terms/genchi-genbutsu/
ASQ: What is root cause analysis?. https://asq.org/quality-resources/root-cause-analysis

Chapter 3 · From page to repository

Measure it, scope it, commit it

An intent becomes useful when it has a number to beat, a list of what it will not do, and a home in the repository where every person and every AI agent reads it before they build.

25 min1 measure1 scope listdocs/INTENT.md

By the end of this chapter you can

Write a measure with today's value and a target, and say how it will be counted.
Write the 'not building' list and the safety rule.
Commit the intent to the repository and point every agent brief at it.

A number to beat

"Better quality" cannot be checked. "Minutes from failed first piece to hold: today about 95, target 15" can. A good measure is one the decider already cares about, can be counted from the data the platform will hold, and moves when the decision gets better. Plan-Do-Check-Act needs a Check, and the Check needs a number ^[1]^[2].

The stamping plant's measures, today and target, drawn to scale. The second and third will be counted straight from the tables built in Session 3.

Test	Question	Stamping plant answer
Owned	Does the decider already care about it?	Yes: suspect parts shipped are their worst week
Countable	Can it be counted from the platform's own data?	Yes: failure time and hold time are both recorded
Moved by the decision	Does it improve when the decision improves?	Yes: faster holds mean fewer suspect parts
Baselined	Do you know today's value, measured, not guessed?	Timed on three events this week

The scope, and the safety rule

Version one does one job. Everything else goes on the 'not building' list with its reason, so that when someone asks for it in week three, the answer is already written and agreed.

Version one, and what it leaves out. Each item on the right has a reason. 'Automatic holds' is out because a person decides; that is also the safety rule.

Commit it where agents will read it

The intent goes into the repository as docs/INTENT.md, through a pull request like any other change ^[4]. You can do it in the browser: open the repository on GitHub, choose Add file, then Create new file, type the path and paste the page ^[5]. From then on, every brief you give an AI coding agent starts with the same line: read docs/INTENT.md first; this change must serve it.

From the intent page to a merged change. The intent is committed once; every agent brief points at it; nothing reaches main without CI and a person's review.

Many coding agents also read a standing instructions file at the root of the repository on every task (AGENTS.md is an open convention several tools follow) ^[6]. Put one line there pointing at the intent, so no agent can start work without reading it.

AGENTS.md: the intent, read on every task

# AGENTS.md (excerpt)
Before any task, read docs/INTENT.md. Every change must serve the decision written there.
If a request does not serve it, stop and ask; do not build it.
Never release a quality hold automatically: a person decides every hold and release.

Exercise · Write and commit your intent25 minutes

You need: Your notes from the floor walk, a browser signed in to your company's GitHub organisation

Use the decision you walked in chapter 2. Keep it to one page.

1. Write the six parts: decision, who and how often, data with where it lives, what changes, not building, rules and sign-off.
2. Give the measure today's value from your timed events and a target the decider agrees with.
3. Write at least three items on the 'not building' list, each with its reason.
4. In GitHub, choose Add file, then Create new file, name it docs/INTENT.md, paste the page, and choose 'Create a new branch and start a pull request'.
5. Ask the decider to read the page in the pull request (or printed) and say yes or what to change.
6. Merge the pull request once the decider agrees, and add their name and the date to the sign-off line.

Outcome: docs/INTENT.md on main, one page, with a measured baseline, a target, a 'not building' list and the decider's agreement.

Knowledge check

Which is a measure the platform can be checked against?

Knowledge check

Where should the intent live so AI agents follow it?

References

ASQ: The Plan-Do-Check-Act (PDCA) cycle. https://asq.org/quality-resources/pdca-cycle
The W. Edwards Deming Institute: PDSA cycle. https://deming.org/explore/pdsa/
CISA: Secure by Design. https://www.cisa.gov/securebydesign
GitHub Docs: About pull requests. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
GitHub Docs: Creating new files. https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files
AGENTS.md: an open format for guiding coding agents. https://agents.md/

Chapter 4 · 12 questions · 80% passes

Final assessment

Twelve questions across the element. Score 80% (10 of 12) to pass. Your LMS records your score and each answer; you can review the chapters and try again.

15 min12 questions≈ 15 minutesRetake allowed

Choose one answer for each question, then submit. You will see the right answer and why for every question.

1. What does the first part of the one-page intent name?

AThe decision: what is chosen, between which optionsBThe screens to buildCThe database to useDThe deadline

2. Which role statement is ready to build from?

AEveryone in qualityBManagementCThe quality lead on shiftDWhoever is available

3. Why keep the first intent to a single decision?

ADatabases can hold only one table at firstBAI agents cannot handle moreCAuditors require itDOne decision done well on real shifts earns the trust for the next; five half done do not

4. In lean practice, what does genchi genbutsu ask you to do?

AGo to where the work happens and see for yourselfBWrite a business caseCAutomate the processDHold a kaizen event

5. A data item lives only in one setter's memory. On the data map it is:

AThe most trusted sourceBA system of recordCLeast trustworthy and often late: true only while that person is on shiftDNot data at all

6. What is decision latency?

AHow long the platform takes to loadBThe time from an event to the decision it should triggerCThe time to build the first versionDHow often the decision is made

7. How should today's value for the measure be found?

AEstimated in a meetingBTaken from the vendor's case studyCLeft blank until go-liveDTimed or counted on real events before you build

8. Which measure passes the four tests (owned, countable, moved by the decision, baselined)?

ABetter visibilityBNumber of screens builtCMinutes from failed first piece to hold, today 95, target 15DUser satisfaction

9. Why write a 'not building' list?

ATo make the page longerBSo requests that would grow the scope already have an agreed answer, with its reasonCBecause IT asks for itDTo list bugs

10. For a quality hold platform, which is the right safety rule?

AThe system releases lots when results look goodBOperators may delete resultsCHolds expire after one hourDA person decides every hold and release; the system never releases a lot by itself

11. Where does the intent live once it is agreed?

Adocs/INTENT.md in the repository, merged through a pull requestBIn a chat with the AI agentCOn the quality office whiteboardDIn the project manager's inbox

12. An AI agent proposes a change that does not serve the intent. What should happen?

AMerge it if the tests passBIt is sent back: every brief says the change must serve docs/INTENT.mdCRewrite the intent to match the changeDLet the agent decide

By the end of this chapter you can

Why start with a decision

The one-page intent

A worked example

Why one decision and not five

References

By the end of this chapter you can

Go and see

Five questions for the decider

Map where the data lives

Measure decision latency

References

By the end of this chapter you can

A number to beat

The scope, and the safety rule

Commit it where agents will read it

References

Intent Before Code: the One-Page Decision Your Platform Serves