Design-of-Record

The tutorial recipe

flowchart LR
  S[Specification] --> A[Agent] --> C[Code]

Five decisions the use case left open

• Where is "has not submitted" computed: one shared service, or each feature on its own?
• Which part of the code owns the scheduler?
• May the request name the week, or does the server always compute it?
• Send during the request, or in the background?
• Keep a log of reminders sent?

...and the shape of the code

• Classes: which exist, which are reused.
• Sequences: who calls whom, in what order.
• Contract: the endpoints, their inputs, outputs, and errors.
• Tests: what counts as done.

Without a design, the agent decides

Where we are

Two levels of design

Code review before there is code

• Written first, approved first. Nobody builds from it before then.
• Cites, never restates. The use case says what. The design says how.
• One per area, revised in place. Not a stack of per-use-case sections.
• Stays true. The code changed? The design changes in the same pull request.

Old idea, new author

Firm the problem first

Row one: two definitions

Both are wrong, differently

• The WAR page reads the first 200 activities and 100 students. With 77 students filing several each, people who submitted show up as missing.
• The report counts a student as done after rating one teammate. The back end saves one rating at a time.

Finding the classes

• Grammatical: nouns are classes, verbs are operations.
• Domain: start from what the domain already has.
• Scenario: walk a flow; whatever has no owner is a missing class.

Walk the reminder: three jobs with no owner

• Decide who owes what. SubmissionStatusService
• Send a batch, surviving failures. ReminderService
• Take the instructor's request. ReminderController

The class diagram: new or reused?

classDiagram
    direction LR
    class ReminderController {
        <<new>>
    }
    class SubmissionStatusService {
        <<new>>
    }
    class ReminderService {
        <<new>>
    }
    class WeeklyReminderScheduler {
        <<moved>>
    }
    class ActivityService {
        <<reused>>
    }
    class EvaluationService {
        <<reused>>
    }
    class EmailService {
        <<reused>>
    }
    class SectionService {
        <<reused>>
    }
    ReminderController --> SubmissionStatusService
    ReminderController --> ReminderService
    WeeklyReminderScheduler --> SectionService
    WeeklyReminderScheduler --> SubmissionStatusService
    WeeklyReminderScheduler --> ReminderService
    SubmissionStatusService --> ActivityService
    SubmissionStatusService --> EvaluationService
    ReminderService --> EmailService

Reading a sequence diagram

The reminder, step by step

sequenceDiagram
    actor I as Instructor
    participant RC as ReminderController
    participant SS as SubmissionStatusService
    participant RS as ReminderService
    participant EM as EmailService
    I->>RC: choose the item (steps 1 to 3)
    RC->>SS: who owes it, previous week
    SS-->>RC: students who owe it
    RC-->>I: list by team, and weekActive (step 4)
    alt week inactive (4a)
        Note over I: "Only for an active week", no send button
    else week active
        I->>RC: confirm (step 5)
        RC->>RS: remind them
        loop each student (step 6)
            RS->>EM: send
        end
        RS-->>RC: sent, and who failed
        RC-->>I: sent, and who failed (step 7)
    end

When to draw a state diagram

stateDiagram-v2
    direction LR
    [*] --> Editable: submit
    Editable --> Editable: edit
    Editable --> ReadOnly: week ends

Two sessions, one contract

A contract row

Three things to notice

• Every extension has an error. Or someone invents one.
• A scheduled job is a contract too. It has a trigger and a promise.
• What is left out is a decision. No week in the request.

Decisions name what they rejected

Where "has not submitted" lives. One service, used by the scheduler, the reminder, and both reports. Rejected: each page computing its own list. Rejected: the report calling the new service, which makes a cycle.

A pattern no requirement needs

The data model change

The test list, before the code

When the design finds the map wrong

• The scheduler lived in the shared foundation.
• Deciding who owes needs the activity and evaluation features.
• The foundation may not depend on a feature.
• So: a new notification feature slice.

The questions test, one level down

• A fresh session, in plan mode.
• Give it only the use case, its rules, your crosscutting concepts, and the design.
• Ask what it would still have to guess.
• Each guess: fix the design, or say why a wrong guess breaks nothing.

What it found on not.md

Sketch first

• You sketch the sequence and the contract. Twenty minutes.
• The agent drafts from the template, in plan mode.
• Compare. Decide which is right, and why.
• Questions test, then the pull request.

When the agent asks

The design gate

• The design, the specification fixes, and any architecture change: one pull request.
• The questions-test list in its description.
• Approved by a teammate who did not write it.
• No implementation branch until it merges.

Review it with questions

• Does every extension have a branch or a test row?
• Does every interaction name a use case step?
• Could two sessions build from the contract alone?
• Does every decision name what it rejected?
• Does anything disagree with the architecture?
• Is every questions-test item answered?

The proving slice

Pick it by risk

Before week 8

• Copy design-of-record.md to docs/design/ for your slice's area.
• Sketch, agent draft, compare, questions test.
• Pull request, approved by a teammate who did not write it.
• Merged by the date on the schedule.

• Week 8, in your team meeting: it becomes your agent's build-context.
• Weeks 8 and 9: the agent builds it.
• Checkpoint 2: it runs. Not described. Runs.