Construction Phase — Building It for Real

The Inception Document for the Class Library Loan Tracker is Approved. It's no longer just an idea — from this point on, it's the blueprint everyone (including Robo) builds against.

Phase 2 of 3: Construction Goal: turn the approved plan into real, working, tested software — one small piece at a time.

From Plan to Code: What Is Construction?

Construction doesn't mean "build the entire app in one giant sitting." Remember the last stage of Inception — breaking the design into small units of work? Construction takes each one, fully, before moving to the next: first (if the unit needs it) a quick round of design — the business logic, any performance or security needs, how it maps to real infrastructure — and only then the actual code. For a unit as small as one acceptance criterion, Robo often decides the design steps aren't needed and goes straight to building; for something bigger, it'll design first and show you each piece before writing a line of code.

flowchart TD
    S["Pick ONE item from the\nInception doc's Acceptance Criteria"] --> W["Robo writes the code"]
    W --> T["Robo writes tests for it"]
    T --> R["Tests run"]
    R -->|"pass"| H["Quick human review"]
    R -->|"fail"| W
    H -->|"looks good"| M["Merge it in"]
    H -->|"needs a fix"| W
    M --> S

    classDef done fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    class M done;

This loop repeats — one unit of work per acceptance criterion — until every item in the Inception doc has matching, working, tested code.

Do We Create Files in a "Construction" Folder?

Yes — and there's a very clean rule for it: application code goes at the very top of your project; planning documents live in one dedicated folder, aidlc-docs/, and the two never mix.

For our Library Loan Tracker, the project folder ends up looking like this:

library-loan-tracker/                         <- application code lives here
├── aidlc-docs/                                <- documentation ONLY, never app code
│   ├── aidlc-state.md                         <- tracks progress across every stage
│   ├── audit.md                               <- a timestamped log of every decision
│   ├── inception/
│   │   └── requirements/                      <- from the last lesson
│   └── construction/
│       ├── plans/
│       │   └── code-generation-plan.md        <- checkbox plan for this unit (see below)
│       └── build-and-test/
├── src/
│   ├── models/
│   │   ├── book.py
│   │   ├── student.py
│   │   └── loan.py
│   └── api/
│       └── routes.py
└── tests/
    ├── test_book.py
    └── test_loan.py

The file worth calling out is code-generation-plan.md — before Robo writes a single line, it writes out a numbered, checkbox-tracked plan of every file it's about to create or change, for you to approve first:

# Code Generation Plan: Loan Model

- [x] Create `src/models/loan.py` with `create_loan()`
- [x] Handle "book already on loan" case
- [ ] Handle "student already has 2 books" case
- [ ] Create `tests/test_loan.py` with matching test cases

Each box only gets checked once that exact piece is actually done. Alongside it, aidlc-state.md tracks the bigger picture — which stages of the whole project are done, in progress, or skipped — so anyone (a teammate, or a future Robo session) can look at one place and instantly know how far along things are, without reading every line of code.

Walking Through One Unit of Work: "Block Loan If Already Borrowed"

Let's zoom into a single unit of work so you can see the shape of it. It maps directly to this line from the Inception document:

GIVEN a book is already on loan, WHEN someone tries to borrow it again, THEN the app blocks it and shows who has it.

Step 1 — Robo writes the code:

# src/models/loan.py

class BookAlreadyOnLoanError(Exception):
    pass

def create_loan(book, student, active_loans):
    existing = next((l for l in active_loans if l.book == book), None)
    if existing:
        raise BookAlreadyOnLoanError(
            f"'{book.title}' is already borrowed by {existing.student.name}"
        )
    if len([l for l in active_loans if l.student == student]) >= 2:
        raise ValueError(f"{student.name} already has 2 books on loan")
    return Loan(book=book, student=student)

Step 2 — Robo writes a test for it:

# tests/test loan.py

def test_cannot_borrow_a_book_thats_already_on_loan():
    book = Book(title="Charlotte's Web")
    alice = Student(name="Alice")
    bob = Student(name="Bob")
    active_loans = [Loan(book=book, student=alice)]

    with pytest.raises(BookAlreadyOnLoanError, match="Alice"):
        create_loan(book, bob, active_loans)

Step 3 — Tests run. If they pass, it moves to a quick human review. If they fail, Robo revises the code and tries again — this loop happens before a human even needs to look at it.

Step 4 — Human review. This is quick, because the scope is tiny (one acceptance criterion) — you're just checking: does this actually do what the Inception doc said? Anything surprising? Robo presents exactly two options, always the same two, no matter the stage: Request Changes, or Continue to Next Stage. No third option, no guessing what to say — you either send it back with what's wrong, or you approve it.

Step 5 — Merge. The checkboxes in code-generation-plan.md flip to done, aidlc-state.md updates, and the next unit of work begins.

The Human's Job During Construction

Notice what the human didn't do: type out create_loan line by line. The human's job during Construction is:

• Reviewing, not typing every line — checking each unit of work actually satisfies what was approved in Inception.
• Catching drift — if Robo starts building something that quietly goes beyond (or misses) what the Inception doc says, redirecting it back to the plan.
• Approving small pieces often, instead of reviewing one giant pile of code at the very end — small reviews catch problems while they're still small.

A simple checklist for reviewing any unit of work:

• [ ] Does this match the specific Acceptance Criterion it's meant to satisfy?
• [ ] Are there tests, and do they actually test the interesting cases (not just the happy path)?
• [ ] Did anything get built that isn't in the Inception doc? (If yes — is that a good idea, or scope creep?)

The Last Stage: Build and Test

Once every unit of work is built, there's one more Construction stage before anything ships: Build and Test, which runs once, after all the units are done — not per unit. Robo writes out exactly how to build the whole thing and verify it, as its own set of files in aidlc-docs/construction/build-and-test/: build instructions, unit test instructions, integration test instructions, and a summary of what's ready. This is the last checkpoint before the app is considered genuinely done, not just "the code exists."

What's Next

Once Build and Test is approved, the app is built and tested — but it's still just sitting on a developer's machine. In the next lesson, we'll put it in front of Ms. Sharma and her students for real, and see what the Operations phase looks like.

Continue to: Operations Phase — Living With What You Built