Software Engineering with Language Models
Module 7 · From brief to release
- Class time
- 60 minutes
- Slides
- 32, each with teacher’s notes
- Goes with
- Laboratory 3; Assignment 3 (Part IV)
Where this module sits
- In Module 6 you configured the harness: an instruction file, a skill, a hook and permissions.
- In this class you take one feature through that harness, from idea to verified release.
- You hand each phase a written artifact from the phase before.
- A phase is finished when it passes its approval gate.
- The last section asks what limits a team once building is fast.
- Module 8 then teaches how to check the evidence at each gate.
Objectives
- Write a one-page brief with its five parts.
- Give any task four fields: Why, Done, Access and Who.
- Run a feature through the seven phases of 7.2 and their gates.
- Isolate parallel agents in separate Git worktrees.
- Use four audit prompts, each aimed at a structural source of bugs.
- Identify the constraint on a team once building is fast.
Agenda
- 13 min: the brief at feature scale and at task scale.
- 11 min: gated phases and the toolkit example.
- 4 min: parallel agents and isolation.
- 12 min: four audit prompts and one reachable invalid state.
- 12 min: review, ownership and where the constraint moves.
- 8 min: mistakes, Laboratory 3, Assignment 3 and recap.
7.1 When building is cheap
- When building is cheap, the quickest test of an idea is often to build it.
- You count planning in rounds of building and reviewing.
- About three rounds is typical.
- The planning document shrinks to one page.
- The page has five parts.
7.1 The five parts of the brief
- A goal more ambitious than your first instinct.
- A few concrete use cases.
- The feature's place in the existing code, with design considerations.
- The test of success, stated as observable evidence that the feature works.
- Stated permission for the agent to go beyond the brief.
Worked example: a one-page brief
GOAL Export any table in the app
as a file a spreadsheet opens
USE Accountant exports a month
of invoices; support exports
one customer's orders
FIT Table component; reuse the
existing download route
DONE 40-row table exports 40 rows;
reopened file matches screen
ROOM May add formats if cheap
7.1 The build and review cycle
- The build runs unattended.
- You review the build the next morning.
- Discard freely, then send the work back.
- Expect a mixed result: some parts good, some parts poor, and some parts showing that the idea was wrong.
- The method leaves out review cost, integration and the maintenance of a larger scope.
7.1 The brief at task scale
| Field | What it states |
|---|---|
| Why | The purpose of the task |
| Done | The finished state |
| Access | The tools and accounts needed |
| Who | Agent or person |
In-class exercise: four fields for one task
- Take one real task from your feature or your tracker.
- Write Why, Done, Access and Who in under two minutes.
- Swap with a neighbour.
- The neighbour decides whether an agent could start without asking a question.
- Rewrite any field the neighbour could not use.
7.2 Thinking separated from typing
orient
specify -> human approves
architect -> human approves
plan -> human approves
build -> automated checks
review -> serious findings
block the merge
ship -> human approves
7.2 Gated phases from orient to plan
| Phase | Artifact | Gate |
|---|---|---|
| Orient | A project index that agents consult in place of rereading files | None |
| Specify | Written requirements, collected one question at a time | Human approves |
| Architect | Data flow, failure handling, retries, idempotency | Human approves |
| Plan | Small test-first tasks with exact file paths | Human approves |
7.2 Gated phases from build to ship
| Phase | Artifact | Gate |
|---|---|---|
| Build | First a failing test, then the code, then a refactor | Automated checks |
| Review | Two passes: one against the specification, one for soundness of the code | Serious findings block merge |
| Ship | Deployment with rollback and monitoring, after a staged or paper-mode run | Human approves |
Worked example: the legacy-modernisation toolkit
- Each command writes a named artifact: intent file, preflight report, topology map, rule cards, phased brief.
- Business rules are Given/When/Then cards with file and line citations.
- Nothing is built before the brief is approved.
- A person holds six gates, and no gate is ever ticked automatically.
- The legacy source is linked read-only, and new code goes in its own directory.
- The toolkit lists instructions it finds in the analysed code and does not follow them.
7.3 Parallel agents and worktrees
repository
|- worktree A agent 1, task X
|- worktree B agent 2, task X
|- worktree C agent 3, task Y
each agent: its own files,
its own branch,
control scoped to
its own workspace
7.3 Fleet supervision and residue
- You see each agent's state at a glance: working, finished or waiting for input.
- You are notified when an agent needs attention.
- Each agent works in its own worktree.
- Scoped control keeps each agent inside its own workspace.
- Agent tooling leaves residue: stale sessions, abandoned worktrees, background processes and old skills.
- Schedule a cleanup that reports first and deletes only after review.
7.4 Audit prompt 1 for state machines
- Find every state machine, explicit and implicit.
- Explicit state machines are enumerations and status columns.
- Implicit state machines are combinations of flags and nullable timestamps.
- Write the states, the invariants and a transition table into one file.
- Report invalid states the code can reach, each with a concrete path.
- Rank the invalid states by impact, fix each with a regression test and keep the document current.
In-class exercise: implicit states of an order row
- An order row has two flags: paid and cancelled.
- It has one nullable timestamp: shipped_at.
- There is no status column.
- List every combination of the three fields.
- Mark each combination valid or invalid, and state the invariant it breaks.
Worked example: a reachable invalid state
1 order created; payment
event delivery fails paid=F canc=F
2 user cancels paid=F canc=T
3 event is replayed;
handler sets paid paid=T canc=T
4 shipping job picks
paid, unshipped shipped_at set
result: cancelled AND shipped
7.4 Audit prompt 2 for compensating code
- Find code that exists only to make up for a flaw elsewhere.
- The kinds are workarounds, retries, defensive checks and adapter layers.
- For each piece of code, identify the flaw it compensates for.
- Propose a redesign under which that code would never have been written.
7.4 Audit prompts 3 and 4
- You run prompt 3 on each new model, and the agent reads the whole project.
- The agent looks for what is broken, inconsistent, inefficient or unused.
- The agent fixes what it is sure of and lists the rest for review.
- You can use the same prompt to compare models on your own code.
- In prompt 4 the agent reads a named best-practice reference.
- The agent then ranks the most valuable improvements this codebase could make now.
Ask the room: the pull-request dispute
- One side calls the pull request obsolete: several models checking repeatedly catch more than one human reviewer usually does.
- It adds that agents can run the full suite before pushing.
- It also says continuous integration first meant integrating into the trunk all the time.
- The other side says unreviewed changes accumulate into systems nobody understands.
- Take a side and state what evidence would change your mind.
7.5 Ownership and attention routed by risk
- Both sides accept two points, and this course adopts them.
- Code is judged on its merits, whoever or whatever wrote it.
- Every change has a named person accountable for it.
- Route human attention by risk.
- Every change gets automated review and a risk score.
- Human review goes where the score or the blast radius is high.
7.5 Supervising by structure
outer [ui] risk low
|
[service] risk HIGH
| mutation low
inner [domain] risk low
|
+--> [ui] flagged:
inner depends on outer
7.6 Where the constraint moves
- Once a team has mastered fast building, the bottleneck sits on both sides of the build step.
- Upstream the constraints are product capacity, too few good ideas and rigid process.
- Downstream the constraints are review capacity, verification and getting the result to customers.
- A downstream obstacle propagates upstream: people who cannot ship ideas stop having them.
- Two remedies are engineers owning more of the requirements and automated review with risk routing.
- Two more remedies are preview environments with tool-equipped agents and a leader willing to reorganise.
7.6 Software factories
- A software factory is a structured multi-stage pipeline.
- A factory raises the floor for a large organisation and may leave the ceiling for its best engineers unchanged.
- Fix the fundamentals first: repository readiness, fast checks and previews.
- Start with a narrow factory for bugs, security or interface polish.
- Measure every component. Do not rebuild a general coding agent.
- Borrow three concepts from manufacturing: limited work in progress, stopping the line on a defect and standardised work.
7.6 Quick internal tools
- A quickly built internal tool puts a cost on whoever has to check it.
- One example is a dashboard that copies the system of record and is not trusted.
- Users verify the dashboard against the record by hand, so the work is done twice.
- Capture the domain's constraints before building.
- Treat a demonstration as a demonstration.
- Give every tool an owner.
Common mistakes
- The brief names no evidence of success. Write part 4 before the run.
- A poor build is kept because it exists. Discard it and send it back.
- An agent ticks a human gate. Reserve those gates for a person.
- Parallel agents share one working directory. Give each agent its own Git worktree.
- Invalid states are listed with no path. Require a concrete reachable path.
- A demonstration is treated as a tool. Capture constraints and name an owner.
Laboratory 3
- Take one feature through 7.1 and 7.2.
- Hand in the one-page brief.
- Hand in the three approved artifacts.
- Hand in the diff and a review record.
- Then run audit prompts 1 and 2 on the same repository.
- The state-machine document needs at least one reachable invalid state and its fix.
Assignment 3 (Part IV): the warm-up and the staged build
- In the warm-up you write examples for first_failing(results) before any code.
- You then make one example wrong, and the run must fail.
- The staged build has five stages, each with one brief, one session, one commit and one check.
- The stages are the static scene, one moving object, input, collisions and the rules with LIVES = 3.
- No stage starts until the previous stage's check passes.
- Hand in the five checks run again on the final commit.
Recap
- A one-page brief has five parts, and part 4 names the evidence of success.
- A task has four fields: Why, Done, Access and Who.
- A person approves four of the seven phases: specify, architect, plan and ship.
- Each agent has one worktree, and the cleanup reports before it deletes.
- An audit finding needs a reachable path, a fix and a regression test.
- A named person is accountable for every change, and human attention goes where risk is high.
Before next class
- Write the one-page brief for your Laboratory 3 feature.
- Do the Assignment 3 warm-up: write the examples first, then make one example deliberately wrong.
- Read Module 8, sections 8.1 to 8.7.
- Choose twenty tests from a project you know.
- Bring one test you suspect only restates the implementation.