Chapter 9 · Part 3: Building

From Requirements to Release, with Engineering and Design

“Simplicity, the art of maximizing the amount of work not done, is essential.”

— Manifesto for Agile Software Development

The forty-page specification

Brindlepath’s first attempt at the ownership queue began the old way. A product manager on the struggling team, eager to get it right, wrote a forty-page specification. It covered every screen, every field, every edge case she could imagine. It took six weeks to write and two more to review. By the time engineering started, the design had changed twice, the pilot customer had changed its discharge workflow, and two of the edge cases had turned out not to exist.

The second attempt began with a two-page brief: the problem, the outcome measure, what was known and unknown, what was out of scope, and the open questions. The trio sketched three approaches together on the first afternoon, tested the most promising with four navigators that week, and had a working slice in a pilot customer’s hands within a month. The brief grew as the team learned, and by launch it was a clear record of what had been built and why.

The difference was not that the second team skipped the thinking. It was that they did the thinking together, in small steps, with customers in the loop, instead of alone, up front, in a document.

Requirements are a conversation, not a contract

A requirements document exists to create shared understanding across the team: what problem we are solving, for whom, how we will know it worked, and what constraints we must respect. It is not a contract between product and engineering, and it is not a substitute for talking.

The best requirements documents I have seen share five traits:

  1. They start with the problem and the outcome, not the solution.
  2. They separate what is known from what is assumed, and say how the assumptions will be tested.
  3. They state what is out of scope, as explicitly as what is in scope.
  4. They are short at the start and grow with learning, rather than being complete before work begins.
  5. They are written for the whole team, in plain language, not for a review committee.

Figure 9.1 shows the structure Brindlepath now uses for every significant piece of work. The full template is in the Appendix. The brief is the start of the conversation. User stories, designs, technical designs and test plans follow from it, written by the people closest to each.

User stories and acceptance criteria

For day-to-day work, many teams express requirements as user stories: short descriptions of something a user needs, written from their point of view. The classic form is: As a [type of user], I want [some goal] so that [some reason].

“As an outpatient navigator, I want to see which newly discharged patients are assigned to me so that I can contact the highest-risk ones first.”

A story is a placeholder for a conversation, not a complete specification. It becomes buildable through acceptance criteria: the specific conditions that must be true for the story to be done. Good acceptance criteria are concrete and testable:

  • Patients discharged in the past 24 hours appear in the queue within two hours of discharge.
  • Each patient shows risk level, discharging unit and inpatient contact.
  • The queue is sorted by risk level, then by discharge time.
  • Only patients assigned to the signed-in navigator, or to their team, are visible.
  • Every view of a patient record is logged for audit.

That last criterion is easy to forget and impossible to add cheaply later. In regulated products, privacy and audit requirements belong in acceptance criteria from the first story, not in a separate compliance phase.

Working with design

Design is not decoration applied at the end. It is the discipline of making the product understandable, usable and coherent, and it starts at the first customer conversation.

Involve design in discovery. Designers who hear customers firsthand make better decisions than designers who receive a summary. Brindlepath’s head of design, Lena Park, joined the navigator interviews in Chapter 3; her sketches from those sessions became the first prototype.

Explore before converging. Ask for several directions before choosing one. The first idea is rarely the best, and comparing options is the fastest way to find out what really matters to users.

Test with real users, early and cheaply. A paper sketch tested with three navigators teaches more than a polished mock-up reviewed by the leadership team.

Respect the design system. A shared library of components and patterns makes the product consistent, accessible and faster to build. Deviations should be deliberate, not accidental.

Design for the real environment. Brindlepath’s navigators worked on aging hospital computers, often with a headset on and a phone ringing. Small fonts, low-contrast text and multi-step workflows failed in that setting even when they tested well in a quiet conference room. Accessibility, which Chapter 11 covers, is part of this: design for the full range of people who will use the product.

Working with engineering

The relationship between product and engineering defines whether a team ships well. In healthy teams, product brings the why and the what, engineering brings the how, and both argue productively about the trade-offs.

Bring engineers in early. The best solutions often come from engineers who know what the technology can do cheaply that the product manager assumed was hard, or vice versa. Dev Raman’s suggestion to build the first version of the ownership queue on the hospital’s existing discharge feed, rather than a new integration, cut two months from the timeline.

Talk in outcomes and constraints, not tasks. “We need navigators to see new patients within two hours of discharge, and it must work with these two record systems” invites better solutions than “build a polling job that runs every five minutes.”

Make trade-offs visible. Every project trades scope, time, quality and cost. When something has to give, decide together what it will be, and write it down.

Protect quality. Pressure to ship always pushes against testing, security and reliability. A product leader who trades quality for speed without saying so is borrowing against the team’s future. Chapter 5’s capacity allocation exists so this trade-off is made deliberately.

Respect estimates as forecasts, not promises. Estimates are useful for sequencing and trade-offs. Treating them as commitments teaches teams to pad them.

From idea to release: the delivery flow

Most product teams today use some form of agile delivery: small increments of work, frequent releases, and regular reflection. The ceremonies vary, whether two-week sprints, continuous flow or something in between. The underlying flow is similar.

A few practices make the biggest difference.

Slice thin. Deliver the smallest piece of value that can be tested with real users, then grow it. The first slice of Brindlepath’s ownership queue showed only patient name, risk level and discharge time for one hospital unit. It was enough to learn whether navigators would use it every morning.

Release often. Small, frequent releases are less risky than large, infrequent ones, because each change is easier to understand, test and undo. Research by the DevOps Research and Assessment program, summarized in Accelerate, found that teams with high delivery performance deploy more often and have lower change failure rates: speed and stability go together rather than against each other.1

Separate deployment from release. Feature flags let teams deploy code without exposing it, then turn it on for one customer, one unit or a small percentage of users. In healthcare, where a change to a clinical workflow may require training or approval at the customer, this is invaluable.

Define “done” to include quality. A story is not done when the code is written. It is done when it is tested, secure, accessible, documented and measurable in production.

Measure delivery, but not just speed. The four delivery measures from Accelerate, deployment frequency, lead time for changes, change failure rate and time to restore service, balance speed with stability. Use them to improve the system, never to compare or rank individuals.

Launch readiness

A release is not a launch. A release puts code in production; a launch puts value in customers’ hands, with everything they need to use it. For significant changes, especially in regulated settings, a launch readiness review a week or two before launch saves a great deal of pain. It covers:

  • Product: acceptance criteria met, measures instrumented, known issues documented.
  • Quality and security: testing complete, security review done, privacy impact assessed.
  • Customers: release notes, training materials, and, for clinical workflows, any customer approvals required.
  • Support: support team trained, help articles ready, escalation paths clear.
  • Sales and marketing: positioning and messages agreed, as covered in Chapter 13.
  • Rollback: a clear plan to turn it off if something goes wrong.

The full checklist is in the Appendix.

After the release: learning

The work is not finished at launch. For every significant change, the team should know in advance which measure it expects to move, and look at it after launch. Did navigators confirm ownership faster? Did missed follow-ups fall? If not, why not?

Two practices help. A launch review a few weeks after release compares the result with the expectation and decides what to do next: iterate, expand, or stop. A blameless post-incident review after anything goes wrong asks what in the system allowed the failure, not who caused it. Both feed the team’s learning and, over time, its judgment.

Brindlepath in practice: thin slices

The ownership queue was delivered in five slices over three months, each one in a pilot customer’s hands within two weeks of the last.

Slice 1. For one hospital unit: patient name, risk level and discharge time, with a button to confirm ownership. No reassignment, no filtering, no reporting. The question it answered: will navigators open this every morning?

Slice 2. All units at the pilot hospital, with the discharge summary and inpatient contact attached. The question: does having the context in one place change how quickly navigators call?

Slice 3. Reassignment between navigators and teams. The question: how often does ownership change, and why?

Slice 4. Audit logging visible to the customer, role-based access by team, and the accessibility fixes found in testing. These were in the acceptance criteria from the start but were completed and verified here, before the second customer went live.

Slice 5. Outcome measures for the customer’s managers: owner within 24 hours, by team and by day.

Each slice was released behind a feature flag and turned on for the pilot customer when its navigators were ready. Two slices changed significantly because of what the previous one taught. After slice 2, the team learned that navigators wanted to see whether the patient had a follow-up appointment already booked, which moved up the roadmap. After slice 3, they learned that most reassignments happened on Monday mornings for weekend discharges, which led directly to the bulk reassignment feature.

The forty-page specification from the first attempt would have built none of those changes, and several things nobody needed.

Common mistakes

Writing the whole specification up front. A complete document before any learning guarantees that parts of it will be wrong, and that the team will feel bound to build them anyway.

Leaving non-functional requirements out. Privacy, audit, accessibility, performance and security are the requirements most often forgotten and most expensive to add later.

Treating estimates as promises. Teams that are punished for missed estimates learn to pad them, and the organization loses the information it needed.

Releasing big batches. Large, infrequent releases are harder to test, harder to understand when something breaks, and harder to roll back.

Calling it done when the code is written. Work is done when it is tested, secure, accessible, documented, measurable and in customers’ hands.

Never checking the result. A launch without a review of the measure it was meant to move teaches the team nothing about whether its judgment is improving.

Try this

Take the next significant piece of work your team will start and write a one-page brief using the template in Figure 9.1 and the Appendix, with the whole trio in the room, in under an hour. Pay special attention to two sections: “out of scope” and “must include.” Then write the acceptance criteria for the first story, and check that privacy, audit and accessibility appear in them. If writing the brief together surfaces a disagreement, you have saved weeks of rework by finding it now.

How AI changes this

AI drafts the paperwork. An assistant can turn a product brief into draft user stories and acceptance criteria, generate test cases from them, write release notes from merged changes, and keep the brief up to date as decisions are made. Review everything. AI-generated acceptance criteria often miss exactly the non-functional requirements, privacy, audit, accessibility and performance, that matter most in regulated products.

AI changes how code is written. AI coding assistants now write a large share of first-draft code in many teams. That makes prototyping and slicing faster, and puts more weight on code review, testing and architecture. A product leader should expect engineering to spend more time reviewing and less time typing, and should protect time for that review.

Prototypes get real. With AI design and coding tools, a working prototype connected to sample data can be built in a day. That blurs the line between discovery and delivery. Be explicit about which prototypes are throwaway experiments and which are the start of production code, because the quality bar is very different.

Requirements for AI features are different. An AI feature’s acceptance criteria are statistical: “summaries contain no fabricated facts in at least 99 percent of an evaluation set of 500 real discharge summaries, reviewed by a clinician.” They need evaluation sets, quality thresholds and monitoring in production. Chapter 17 covers this in depth.

Keep humans on the gates. AI can help at every stage of the delivery flow, but the quality gates, security review, clinical safety review and launch readiness, need accountable people.

Chapter checklist