Unit 16 · lesson

Specification Before Generation

Core path: 25 minutes

How do we describe a software system clearly enough that a human and an AI can build toward the same target?

Week 15 focused on reviewing a bounded feature. Week 16 moves one level higher:

Specification first. Generation second.

An idea is not a specification

Build a robot monitor.

That leaves critical questions unanswered. What is a robot record? What counts as low battery? Does the project require networking? Authentication? Saving data?

When requirements are missing, a human or AI has to invent assumptions. That is a failure mode, not creativity we should silently accept.

Define the system boundary

PROJECT
Robot Fleet Console

PURPOSE
Track simulated robots and battery status.

CORE FEATURES
1. Add robot
2. View robots
3. Update battery
4. Identify low-battery robots
5. Save fleet to JSON
6. Load fleet on startup

OUT OF SCOPE
- real hardware
- authentication
- database
- networking

Requirements and constraints

A functional requirement describes required behavior. A constraint limits how the system is built.

Requirement: identify robots at or below 20% battery.
Constraint: Python standard library only.

Acceptance criteria make claims testable

GIVEN rover-01 has battery 20
WHEN low-battery status is checked
THEN the result is True

Guided example: turn one vague phrase into a testable boundary

Vague:

Warn when the battery is low.

Question the phrase:

What exact threshold means low?
Is 20 included?
What should the function return?

Specification:

battery <= 20 is low
battery > 20 is not low

Test before generation:

def test_battery_20_is_low():
    robot = Robot("rover-01", 20)
    assert robot.is_low_battery() is True


def test_battery_21_is_not_low():
    robot = Robot("rover-01", 21)
    assert robot.is_low_battery() is False

Now generation does not get to redefine the threshold after seeing the tests.

Specification is a control surface

A specification will not prevent every bug. It gives reviewers something concrete to compare the implementation against. Without that baseline, "looks good" becomes the acceptance criterion, which is useless.

Vocabulary lab

Flip the idea, not just the card

Explain the term before you reveal the back. Then compare your explanation with the definition, example, and warning.

Read all terms without animation

Specification: A written description of required system behavior, boundaries, and constraints. Example: A project document defining features and out-of-scope work. Do not confuse it with: A vague idea such as build a robot monitor.
Functional Requirement: A statement describing behavior the system must provide. Example: The system must identify robots at or below 20 percent battery. Do not confuse it with: A constraint describing how the solution may be built.
Constraint: A rule limiting implementation choices or scope. Example: Use the Python standard library only. Do not confuse it with: A user-visible feature requirement.
Acceptance Criteria: Observable conditions used to determine whether a requirement is satisfied. Example: Battery 20 returns low-battery True. Do not confuse it with: A general statement that the feature should work correctly.
Boundary Value: An input at the exact edge of a rule where incorrect comparison logic often appears. Example: Battery 20 when the threshold is <= 20. Do not confuse it with: An arbitrary normal value far from the threshold.