ProjekinAja. Software Engineering Stage 1 · Foundations Lesson 1.9
● Stage 1 · Lesson 1.9

TraceLab v0: The Project Brief and the Wrong Solution

Define the product, scope it honestly, then deliberately build the wrong version — a single script whose pain is the syllabus for the next five stages.

⏱ ~18 min read 📋 Requirements engineering 🧱 TraceLab milestone

🎯 By the end you'll understand

How to write requirements as testable, falsifiable statements — who TraceLab serves, what it must do, and (harder) what it must not do. You'll place v0's features through a scope triage process, experience scope creep as a kinesthetic sensation, then write the scruffy CSV script and formally catalog every debt it carries. Those debts are not bugs to fix now — they are the structured curriculum for Stages 2–4.

KEY INSIGHTMost project failure is requirements failure

The code was correct. It just solved the wrong problem, for a user who didn't exist, with features nobody asked for, and shipped six months late because nobody said no to anything.

You've spent eight lessons dismantling the magic from execution, memory, processes, shells, data representation, cost models, networking, and the OS. Now we build something real. Not to build a perfect system — deliberately to build an imperfect one, so the pain it produces is specific, personal, and instructive.

🔑 Hold onto this

A requirement is a statement that can be falsified by a test. "The system should be fast" is not a requirement — it's a wish. "A query for any single run completes in under 100 ms on a 100,000-row file" is a requirement: you can write a benchmark and it either passes or it doesn't. The gap between "fast" and "100 ms on 100 k rows" is where projects quietly go wrong, and scope creep fills that gap with good ideas nobody budgeted for.

CORE CONCEPTRequirements as testable statements

Good requirements have a structure you can check. The canonical form is: given a context, when a trigger, then a measurable outcome. This is deliberately similar to how you'd write a test — and that's the point. If you can't write a test for a requirement, the requirement isn't done yet.

Let's ground this in TraceLab. The product brief in one paragraph:

📖 TraceLab v0 — product brief

Who it serves: a single researcher (you) running ML training jobs and robot experiments from the command line on one machine. Not a team. Not a dashboard for a manager. Not an API consumed by another service — yet.

What it must do: record the fact that a run happened, with a timestamp, a name, and arbitrary key-value metrics; retrieve a past run by name; do this from the shell in under five seconds of setup on a fresh clone.

What it must not do (v0): handle multiple concurrent writers, migrate old data when the schema changes, serve a web UI, authenticate users, or guarantee metric precision beyond what Python's default float gives you. Explicitly out of scope.

Turn those paragraphs into requirement rows. Notice the column structure: each row states a condition, specifies a user action, and ends with a measurable pass criterion — the test you'd write on day one.

IDGiven / whenPass criterionPriority
R1a training script calls log_run(name, metrics)a new row appears in runs.csv within 50 ms; row contains timestamp, name, and all key-value pairsmust-have
R2the user runs python tracelab.py find <name>the exact row for that run is returned; a non-existent name prints nothing and exits 0must-have
R3no Python or pip install is available beyond the standard librarythe script runs without error on CPython 3.10+must-have
R4the user runs the script on a file with 10,000 rowsa find query returns in under 2 s — not fast, but finitenice
R5two processes write simultaneouslyout of scope for v0 — documented, not fixedlater
R6a value contains a commaknown fragility — documented as debt, not a crashlater

R5 and R6 look like bugs. They are — but writing them into the spec as known, deferred is different from ignoring them. You are saying: "I know this breaks here. The consequence is this. The fix costs that. We will not pay for it now." That's engineering judgment, not sloppiness. Sloppiness is when they are omitted entirely and bite you in production at 2 a.m.

The other thing these rows do: they make scope creep visible. Every time someone says "it would be nice if TraceLab also did X," X either maps to an existing row, or it's a new row with a priority. If X is must-have and nobody flagged it, that's a missing requirement. If X is nice-to-have, now you can have an honest conversation about whether it belongs in v0. Without the table, the conversation is vibes. With it, it's tradeoffs.

CORE CONCEPTNon-goals matter more than goals

Every experienced engineer will tell you the same thing: the non-goals section is where projects live or die. Goals are easy — everyone wants the system to be fast, reliable, secure, scalable, and easy to use. Saying yes to all of them simultaneously in v0 is how you ship nothing.

Non-goals do three things. First, they protect the team's attention — a card on the board reading "multi-user auth" with the explicit label never-for-v0 is a card that generates zero design debates this week. Second, they establish a promise to stakeholders: "we are not going to surprise you with these limitations because we wrote them down on day one." Third, they create the debt ledger — the list of known shortcuts that will eventually be repaid, on a schedule, with eyes open.

💡 The word "later" is doing real work

"Never" and "later" are different buckets. "Never" means the cost/benefit never closes — web UI for a one-person CLI tool, for instance. "Later" means the cost is real but the current user base doesn't demand it yet — concurrent writers, metric precision, schema migration. "Later" items go into the debt ledger with an explicit trigger: "repay when we have more than one machine logging simultaneously." Without that trigger, "later" becomes "never heard of it."

Scope creep operates on exactly this ambiguity. It starts with a feature that sounds like it belongs — "well, if we're already logging metrics, we should probably also track system CPU usage" — and it sneaks in through the non-goals column, which is empty because nobody wrote it. Each individual feature seems cheap. The aggregate is a six-month delay. The widget below is about building the muscle to say no before agreeing to yes.

SEE ITScope triage board

Below are 25 candidate features for TraceLab. Drag each card into one of the three buckets: must-have for v0, later (real value, but not now), or never-for-v0 (out of scope permanently or indefinitely). When you place a card, it reveals the honest cost — measured in lessons of this course you'd need to finish before implementing it correctly. Watch the scope-creep meter as you add things to the must-have column.

There is no single correct answer, but the course's canonical allocation is stored and you'll see how yours compares at the end.

📋 Interactive · TraceLab Scope Triage Board

Click a card to place it, then click again on a column to move it. Cards flip to reveal their honest implementation cost once placed.

Scope-creep meter 0 must-haves
Place cards to see the scope pressure build.
Unsorted cards — click a card, then click a column to place it:
Must-have v0 (0)
Later (0)
Never for v0 (0)

If your must-have column grew past five or six items, you've just felt scope creep. That feeling — "but each one is so small!" — is exactly what kills timelines. The scope-creep meter goes red not because each feature is wrong, but because together they represent weeks of work on top of the core. Every feature in the "later" column is a feature that will be built better once you have the infrastructure Stage 2 through 4 provide. Deferring isn't failure — it's prioritization with evidence.

TRACELABTraceLab v0 — the formal spec

With the triage done, write the spec in a form that's small enough to fit in a README and precise enough to settle disputes. This is the actual v0 spec for TraceLab, written as you'd write it on day one of a project:

SPEC.md (v0, TraceLab)the contract
# TraceLab v0 — Product Spec

## Users
One researcher. One machine. Command-line only.
Not a team product. Not yet.

## Must-have (v0 ships only when these pass)
- R1: log_run(name, **metrics) appends one row to runs.csv in <50 ms
- R2: find_run(name) returns the exact row or None; no crashes on miss
- R3: zero dependencies beyond Python 3.10+ stdlib

## Known limitations (documented, not fixed)
- Values containing commas corrupt the row (CSV escaping omitted)
- float metrics stored as str; round-trip precision not guaranteed
- find_run does a full file scan: O(n) per query, O(n²) across a workflow
- No locking: concurrent writers will interleave rows
- No schema: column order depends on dict insertion order

## Out of scope for v0 (never-for-now)
- Web UI, REST API, auth, multi-user access
- Schema migration, query language, aggregations
- Metric precision guarantees, typed storage
- Distributed logging, message queue integration

## Trigger to revisit
When a second machine needs to write, or when find_run takes > 1 s,
open the debt ledger and repay the appropriate item.

Notice what this spec does not contain: architecture decisions. No "we will use SQLite," no "the API will be REST," no technology choices at all. Specs say what the system does for its users. Architecture says how. Mixing them locks you into implementation decisions before you've built anything — and those decisions age badly, because you know the least about the problem at the beginning.

💡 The trigger condition is the most important line

The spec above ends with a trigger: "when a second machine needs to write, or when find_run takes > 1 s." This is not a date — it's a condition. Date-based deadlines for technical debt repayment are almost always wrong, because the trigger is workload-dependent. Condition-based triggers are honest: you will repay this debt when the pain exceeds the cost of repair, and you have written down in advance what "pain" looks like.

TRACELABBuilding v0 — the deliberately wrong solution

Now write it. The goal is the simplest thing that passes R1, R2, R3 — nothing more. Resist every temptation to add error handling, validation, or "while we're here" features. Those are precisely the things the spec says we are not doing. This is the TraceLab v0 canonical script — born deliberately scruffy, so its pain is legible:

tracelab.pyv0 — canonical, 21 lines, intentionally flawed
# tracelab.py — v0: log experiment runs to a CSV. It works. (It has debts.)
import sys, time

def log_run(values):
    f = open("runs.csv", "a")              # no encoding, no lock
    row = time.strftime("%Y-%m-%d %H:%M")
    for v in values:
        row = row + "," + v                # hope nobody passes a comma
    f.write(row + "\n")
    f.close()

def find_run(name):
    for line in open("runs.csv"):          # full scan, every single call
        if name in line:                   # substring match — what could go wrong
            return line.strip()

if __name__ == "__main__":
    if sys.argv[1] == "log":
        log_run(sys.argv[2:])
    else:
        result = find_run(sys.argv[2])
        if result:
            print(result)

Usage: python tracelab.py log exp042 loss=0.31 reward=12.7, then python tracelab.py find exp042. It passes R1, R2, R3. It fails R5, R6, and it will fail R4 the moment you hit tens of thousands of rows.

Now apply the technique from Lesson 1.1: trace one line all the way down. Take f.write(row + "\n"). The tokenizer emits NAME OP NAME OP STRING OP. The parser builds an Expr → Call node with a BinOp argument. The compiler emits LOAD_NAME f, LOAD_ATTR write, LOAD_NAME row, LOAD_CONST "\n", BINARY_OP +, CALL 1. The VM executes them, calling into the io module's C code, which buffers the bytes. At close() the buffer flushes via a write() syscall (from Lesson 1.3); the kernel copies bytes to the page cache; the disk scheduler decides when they hit the platter. That one line of Python touched the shell (Lesson 1.4), the process boundary, the file descriptor table, the kernel buffer, and eventually the storage controller. No magic, at any layer.

f.write(…) Python bytecode io module (C) user-space buffer close() write() syscall kernel boundary page cache kernel buffer fsync / scheduler disk / SSD durable storage Lesson 1.1 Lesson 1.3 Lesson 1.3 Lesson 1.3 Lesson 1.7 one Python line · every mechanism you've learned in Stage 1
Every layer f.write(row + "\n") touches. No layer is magic. Stage 1 is the right to say that sentence about your own code.

TRACELABThe debt ledger — v0's sins, cataloged

The discipline is: write down every limit you can feel, assign a mechanism to each one, and link it to where the fix lives. This is not shame — it's a schedule. Every senior engineer you'll ever respect maintains a version of this list, usually in a README or a FIXME with context. The ones who don't, maintain it in their heads and hand it to you as a surprise at 2 a.m.

Debt in v0Mechanism (what you learned)The day it bitesRepaid in
open() with no encoding=; values joined with + OS locale determines the encoding; the file is a byte stream, not text (Lesson 1.5) a robot experiment named café-3 turns to mojibake; a comma in a value silently corrupts the row Lesson 1.5
metrics stored as strings; floats round-trip through str() IEEE 754 representation (Lesson 1.5); str(0.1 + 0.2) != str(0.3) aggregated losses drift; two "equal" runs compare unequal Lesson 1.5
find_run scans the whole file; name in line is substring match O(n) scan, O(n²) across a workflow; substring match has false positives (Lessons 1.6–1.7) exp4 returns exp42; lookups slow from milliseconds to seconds on large files Lessons 1.6–1.7
no history — edits are permanent, no diff, no rollback the file system has no transaction log; the shell has no undo (Lesson 1.4) "which version of the script logged these runs?" has no answer Stage 2 (git, testing)
no locking — concurrent writers interleave the OS write() syscall is not atomic at the file level (Lesson 1.3) two robots log at once; rows shear mid-line; data is silently corrupt Stage 3 (processes, concurrency)
the CSV "schema" lives in nobody's head no contract between writer and reader; any column reorder breaks all consumers after 10,000 runs, you need to add a column — the migration is a one-day project Stage 4 (data modeling, SQL)

Look at the "Repaid in" column. It is the curriculum for the next five stages. These debts were not chosen arbitrarily — they were chosen because they exercise exactly the mechanisms each stage builds. When you implement proper encoding in Lesson 1.5, the fix is two characters: open("runs.csv", "a", encoding="utf-8"). When you add locking in Stage 3, you'll understand why you need it, because you wrote the code that breaks without it. Debt-first learning is intentional.

🔑 The v0 canon is frozen

The 21-line script above is now fixed. Every future lesson that touches TraceLab advances from this exact baseline. When a later lesson says "fix the encoding bug," it means line 5 of this script. When it says "replace the O(n) scan," it means find_run. The script's flaws are a syllabus, not an accident.

WEAKNESSWhere requirements and scope engineering go wrong

✗ Confusing wishes for requirements

"Fast," "secure," "scalable," and "reliable" are not requirements — they are marketing words. Every project that shipped late or wrong had a spec full of adjectives and empty of numbers. When you write "the system should respond quickly," you guarantee a future argument about whether 800 ms is "quick." The fix is always the same: add a unit. "Responds in under 200 ms at the 99th percentile under 500 concurrent users" is a requirement. A number you can't measure yet is still better than no number — you can always revise it.

✗ Treating the non-goals section as optional

Teams skip the non-goals section because it feels political — saying "we will not build X" invites someone to argue about X. But an empty non-goals section is not neutral: it is an implicit promise that X will be considered whenever anyone asks for it. Scope creep doesn't break projects all at once; it breaks them one "reasonable request" at a time. The non-goals section is the only structural defense against that. If writing it feels uncomfortable, that discomfort is information — it means the stakeholder expectations are not aligned, and you'd rather learn that now than at the first demo.

✗ Building the "right" solution on day one

The temptation when you know about databases, message queues, and distributed locks is to reach for them immediately. Don't. A SQLite backend for TraceLab v0 would have solved two debts (encoding, schema) but added a dependency, a setup cost, and a migration story before you understood what the tool was actually used for. The principle — "make it work, then make it right, then make it fast" — is not a beginner heuristic. It is a strategy for learning what "right" actually means before you pay for it. You cannot spec what you don't understand. v0 is how you learn what to spec.

KEY INSIGHTHow this connects

  • The Shell Is a Programming Language (1.4) — TraceLab v0 is invoked from the shell; the argv parsing, the exit code convention, and the pipe-friendly output design all come from shell semantics established in Lesson 1.4.
  • How Data Is Actually Represented (1.5) — the first two debts in the ledger (encoding fragility, float drift) are directly attributable to the mechanisms Lesson 1.5 explains. The fix is two characters once you understand the mechanism.
  • 2.1 · Code Is Read 10× More Than It's Written — Stage 2 opens with the craft layer. The v0 script is your specimen: every Stage 2 lesson will improve a piece of it, against the spec you wrote today.

This lesson is the pivot. Everything in Stage 1 was about mechanism — how code runs, how memory works, what the shell is, what data really is, what the network does, what cost looks like. That foundation exists for a reason: to make the debts in v0 legible. You know why the encoding is fragile (bytes and text are different things). You know why the scan is slow (cost model, O(n)). You know why concurrent writes corrupt data (the OS write semantics). Stage 2 begins the repair, armed with that understanding.

GLOSSARYKey terms introduced

Requirement
A testable statement about system behavior: given a context, when a trigger, then a measurable outcome. Not a wish, not an adjective.
Non-goal
An explicitly out-of-scope feature or property. Writing non-goals is not admitting defeat; it is making implicit promises explicit so they can be managed.
Scope creep
The gradual accumulation of features beyond the original scope, each individually defensible, collectively fatal to timeline and quality.
Technical debt
A deliberate shortcut with a known cost. Debt is not bad code — it is code whose limitations are understood, documented, and scheduled for repayment. Unacknowledged debt is the dangerous kind.
Debt ledger
An explicit catalog of known limitations, their mechanisms, and the condition that will trigger repayment. The difference between technical debt and technical negligence.
Minimum viable product (MVP)
The smallest artifact that can be built and tested to validate a core assumption. Not "simple" — specifically scoped to answer the most important open question, and no more.
Trigger condition
The observable event or threshold that will cause a deferred decision (debt, non-goal) to be revisited. Makes "later" into a real schedule item rather than a polite deferral.

ACTIVE RECALLCheck your understanding

Answer in your own words first, then reveal.

1What distinguishes a requirement from a wish? Give a concrete example using TraceLab.›

A requirement is falsifiable by a test. A wish is an adjective that can mean anything. "TraceLab should be fast" is a wish — you can argue indefinitely about what "fast" means. "A find query on a 10,000-row file returns in under 2 s" is a requirement — you can write a benchmark. For TraceLab, R1 through R3 are requirements; "easy to use" is not. A useful heuristic: if you can't write the test first, the requirement isn't done yet.

2Why is the non-goals section of a spec more important than the goals section?›

Goals are usually obvious — everyone agrees the system should work. The dangerous ambiguity lives in what's not being built. Without explicit non-goals, every "reasonable request" is on the table. Scope creep operates through that ambiguity: each feature seems cheap; the aggregate is catastrophic. Non-goals also do stakeholder alignment work — writing "multi-user auth is out of scope for v0" forces the conversation before the implementation, not after. Empty non-goals sections are implicit unlimited-scope promises.

3TraceLab v0 uses a substring match in find_run: if name in line. What are the two problems with this, and which lessons explain their mechanisms?›

First, correctness: "exp4" in "2024-01-01,exp42,loss=0.31" is True — so querying for exp4 returns exp42's row. This is a false positive from substring matching, not prefix/exact matching. Second, performance: the function opens and scans the entire file on every call. One call is O(n); calling it for every run in a workflow is O(n²) total. Lesson 1.6 builds the cost model that makes O(n²) concrete, and Lesson 1.7 shows the data structures that replace linear scans with indexed lookups.

4What is a trigger condition, and why is it better than a date for scheduling technical debt repayment?›

A trigger condition is an observable event that signals the cost of the debt now exceeds the cost of repayment — for example, "when a second machine needs to write simultaneously" for the locking debt. Dates are wrong because the need is workload-dependent, not calendar-dependent. If you fix concurrent-write locking on January 1 but you don't have two writers until June, you've paid the repair cost six months early for no benefit. Conversely, if you've had two writers since October and the repayment date is January, you're running with known-corrupted data for three months. The trigger condition aligns the repair with the actual pain, which is the only honest reason to do the work.

Next: Stage 2 begins — Code Is Read 10× More Than It's Written →