The brief, and what 'done' means

Someone says: build me something to track my reading. You know enough JavaScript now to start typing immediately, and that is exactly the trap. Two hours later you have four functions, none of which you can say is finished, because nobody wrote down what finished means. You keep going because stopping feels like giving up, and the thing grows in every direction at once.

Everything you have built in this course so far came with the target already drawn: the exercise told you what the function had to return. Real work does not arrive that way. It arrives as a sentence, and the first job — before data shapes, before functions, before tests — is to turn that sentence into a short list of statements that are either true of your code or not.

This lesson has no exercise for the sandbox to grade, and that is honest rather than lazy: the deliverable is a written plan. It is still work. Do it badly and the next four lessons have nothing to aim at.

An acceptance criterion says what a named function does with a named input, in terms someone else can observe. 'summarise of an empty list reports zero pages' is a criterion: you can run it and see. 'The library should be easy to use' is not — two reasonable people will never agree on whether it is met, so it can never be ticked off.

The test for a criterion is simple and mechanical: can you imagine the two outcomes? If you cannot describe what failing it would look like, it is a wish, not a criterion. Rewrite it until you can. 'Easy to use' becomes 'every public function takes one argument and returns a value; none of them needs to be called in a particular order'. That one you can check.

Criteria are also where you say what happens when things go wrong, because that is the half beginners forget. 'An invalid entry is rejected with a message naming the field that is wrong' is a promise about failure, and lesson 4 is nothing but the code that keeps it.

Here is the sentence: 'I want to keep a log of my reading sessions and see what it adds up to.' That is the whole brief, and it is typical — short, friendly, and nowhere near enough to code from.

Turned into criteria, it becomes this. One entry arrives from a form as messy text and must become one clean record. A list of records must produce a summary: how many sessions, how many pages, how many minutes, which books. The pages must be totalled per tag, so 'how much fiction did I read' has an answer. An entry that is not sensible must be rejected with a message naming the field. A whole list with some rubbish in it must still load the good entries and report the bad ones by position. And the finished thing must produce one line of report text.

That is six public functions: toSession, summarise, pagesByTag, validateSession, createSession, loadSessions, and report — seven, counting report. You will build every one of them across lessons 2 to 5, and review the lot in lesson 6. Nothing else gets added. When you catch yourself thinking 'it would be nice if it also…', that thought belongs in the out-of-scope list, not in the code.

The out-of-scope list is the fence around the work. For readlog v1 it says: no dates (a session has minutes, not a calendar), no saving or loading files, no printing to the screen from inside the library, no fetching anything, no reading anything the caller did not hand in. Some of those are choices; some are the sandbox's limits, stated plainly rather than discovered later.

Useful way to think about it: every feature you promise is a promise to keep it working forever. A small library that does six things perfectly is worth more than a large one that does twenty things you are afraid to touch. Scope is not a limitation you accept reluctantly, it is the thing that makes finishing possible.

And an out-of-scope list is a kindness to whoever reads your code next, including you in three weeks. Without it, every missing feature looks like a bug or an oversight. With it, the absence is a decision someone made on purpose.

Builders put up the frame of a house before a single wall is finished. You can walk the frame, see how big the rooms are and notice that the kitchen has no door, long before anything is plastered. Code has the same move, and it is called a walking skeleton: write every public function with the right name and the right arguments, and have each one throw an error saying it is not implemented yet.

This costs about ninety seconds and buys two real things. You see the whole surface at once, so a badly named or missing function is obvious now rather than after you have written its body. And every call fails loudly, in the way lesson 7 argued for: nobody can accidentally use a half-built function and get a quietly wrong answer, because a stub that throws cannot be mistaken for one that works.

The stubs come down one at a time as the lessons go on. When the last throw is gone and every criterion is ticked, v1 is done — not perfect, done.

In module 11 you wrote your own assertion helper: something that compares what happened with what should have happened and prints PASS or FAIL. That helper is the bridge between the plan and the code. One criterion, one call to it, one line of output.

Writing the checks straight from the criteria — before the bodies exist — means every one of them fails at first, and that is the point. A list of red checks is a to-do list that cannot lie to you about how far you have got. When all of them are green, and only then, the brief has been met.

The third worked example below writes three of them by hand. Two pass because they lean on JavaScript you have already met, and one fails on purpose, so you can see what a criterion looks like in the moments before it is true.

The most common bad criterion sounds professional and means nothing: 'the code should be clean', 'the library must be performant', 'errors should be handled properly'. Each one feels like a standard and none can be checked, so each becomes an argument later, when arguing is most expensive.

The fix is to replace the adjective with an observation. 'Performant' becomes 'summarise handles a thousand sessions without the page freezing'. 'Errors handled properly' becomes 'no public function returns undefined when given an invalid entry; it either returns a reported failure or throws'. 'Clean' becomes 'no function is longer than about twenty lines and none needs a comment to say what it does'.

If you cannot make an adjective observable, cut it. A criterion that can never fail is not a low bar, it is no bar at all.

A brief is a sentence; acceptance criteria are the checkable statements you turn it into, including the ones about failure. A criterion you cannot imagine failing is a wish — rewrite it. The out-of-scope list is written down with the same care as the scope, because it is what lets you finish. A walking skeleton gives you every function name up front, each one throwing until it is real. Every criterion becomes exactly one check, red first, and v1 is done when they are all green.