Syllabus Module 7 · From brief to release
NSW 3011 / 32
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)
Module 72 / 32

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.
Module 73 / 32

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.
Module 74 / 32

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.
Module 75 / 32

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.
Module 76 / 32

7.1 The five parts of the brief

  1. A goal more ambitious than your first instinct.
  2. A few concrete use cases.
  3. The feature's place in the existing code, with design considerations.
  4. The test of success, stated as observable evidence that the feature works.
  5. Stated permission for the agent to go beyond the brief.
Module 77 / 32

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
Module 78 / 32

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.
Module 79 / 32

7.1 The brief at task scale

FieldWhat it states
WhyThe purpose of the task
DoneThe finished state
AccessThe tools and accounts needed
WhoAgent or person
Module 710 / 32

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.
Module 711 / 32

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
Module 712 / 32

7.2 Gated phases from orient to plan

PhaseArtifactGate
OrientA project index that agents consult in place of rereading filesNone
SpecifyWritten requirements, collected one question at a timeHuman approves
ArchitectData flow, failure handling, retries, idempotencyHuman approves
PlanSmall test-first tasks with exact file pathsHuman approves
Module 713 / 32

7.2 Gated phases from build to ship

PhaseArtifactGate
BuildFirst a failing test, then the code, then a refactorAutomated checks
ReviewTwo passes: one against the specification, one for soundness of the codeSerious findings block merge
ShipDeployment with rollback and monitoring, after a staged or paper-mode runHuman approves
Module 714 / 32

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.
Module 715 / 32

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
Module 716 / 32

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.
Module 717 / 32

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.
Module 718 / 32

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.
Module 719 / 32

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
Module 720 / 32

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.
Module 721 / 32

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.
Module 722 / 32

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.
Module 723 / 32

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.
Module 724 / 32

7.5 Supervising by structure

outer   [ui]       risk low
          |
        [service]  risk HIGH
          |        mutation low
inner   [domain]   risk low
          |
          +--> [ui]   flagged:
               inner depends on outer
Module 725 / 32

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.
Module 726 / 32

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.
Module 727 / 32

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.
Module 728 / 32

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.
Module 729 / 32

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.
Module 730 / 32

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.
Module 731 / 32

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.
Module 732 / 32

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.