Appendix B. Work-Log Template

B.1 What the log is for

The work log is the dataset for the labs in Part II. It supplies the parameters of the agent-aware cost model (Chapter 6), the shares of human hours behind prediction P1, the defect root causes behind P2, the comprehension hours behind P8, and the failure data behind P10. Table B.2 sends every category to a term of the cost model. Chapter 18 explains how the log is used across the project. Start it in the first week and never stop. The log lives in the project repository, so it transfers with the project at the handoff (Appendix C).

Three rules govern it.

1. Log at the time. Record each work block when it ends, or at the latest the same day.
2. Log what happened, not what should have happened. The log has no correct answer.
3. One total. Every human hour you spend on the project goes into exactly one category.

B.2 Fields

Record these for every work block.

• Date, week number, phase. Phase is own before the handoff and inherited after it.
• Category and hours. Hours to the nearest quarter hour, one category per entry (definitions below).
• Agent task ID and agent run ID. A task is one unit of work briefed to an agent, of up to about 200 delivered lines (Chapter 11, Section 11.5). A task can take several runs. One ID per run; the run record carries the next fields. The count of tasks is n in Chapter 6.
• Tokens in, tokens out, cost. From the agent harness's own report, not from memory.
• Lines presented for review. Lines of generated text you are asked to read for the first time, including alternatives and attempts you discarded. A regenerated attempt is new text and counts.
• Lines resubmitted (optional). Lines you had already read and were shown again after a defect. They do not count as presented; the time spent re-reading them is rework.
• Lines merged. Lines that reached the main line after review and verification. Lines delivered (Section B.7) are the merged lines that remain in the main line when you compute.
• Defects. One record per defect (Section B.4).
• Questions to the original author. Inherited phase only (Appendix C, Section C.5).
• Escalations and refusals. From M3 on (Chapter 18, Section 18.2). One record per event: whether an agent escalated a decision to you or refused an action, who decided, and the minutes the work waited.
• Note. One sentence: what you decided, or what surprised you.

The eight hour categories, with the code to write in the log:

• Specification (specification): writing and revising the spec, acceptance criteria and non-goals.
• Prompting (prompting): writing the brief and prompts that start or continue a task, assembling context, configuring the harness, steering a run.
• Hand-coding (hand-coding): writing code yourself, outside prompting.
• Review (review): reading generated code and its evidence for the first time.
• Verification (verification): writing, running and investigating acceptance tests, property checks and evaluations, first pass.
• Debugging (debugging): diagnosing why something failed, before the fix is decided.
• Rework (rework): what you do after a defect: re-prompting, re-reading text you have already read, and re-running or re-investigating checks.
• Comprehension (comprehension): reading and understanding inherited code before changing it (inherited phase only).

Prompting, hand-coding and debugging together are construction hours (Section B.7), the steering term of Chapter 6's model. Comprehension is logged separately and counts on neither side of prediction P1.

If an activity fits none of them, log it as other with a note. If other exceeds 10% of your hours, you need a better category; propose one and keep both for the old entries.

Three lines need care, and each decides which term of Chapter 6's model an hour lands in.

• Debugging or rework. Debugging ends when you know the cause; rework starts when you redo something because of it.
• Review or rework. Reading text for the first time is review, even when it follows a rejection: a regenerated attempt is new text. Reading text you have already read is rework.
• Prompting or rework. A prompt that starts or continues a task is prompting. A corrective prompt after a defect is rework. Hand-coding is code you write or edit yourself.

B.3 Weekly log page

Fill in one page a week, from the entries. This layout fits a printed page and a spreadsheet tab.

WEEK __  dates ____ to ____   phase: own / inherited
HOURS    spec __  prompt __  hand-code __  review __  verify __
         debug __  rework __  comprehension __  other __  TOTAL __
AGENTS   tasks __  runs __  tokens in __  tokens out __  cost $__
CODE     lines presented __  resubmitted __  merged __
DEFECTS  found __   (one record each, Section B.4)
QUESTIONS to original author: sent __  answered __
ESCALATIONS (from M3) escalations __  refusals __  minutes waiting __
DECIDED  what I decided this week, and the evidence I had
SURPRISES what an agent did that I did not expect
NEXT     planned work, with my estimate in hours

Check each week that the category hours sum to the total. A page that does not add up has a missing entry.

B.4 Defect record

Record every defect you find, in any artifact, whoever introduced it. A defect is a deviation from what the specification, or the user, required. Use these fields.

• ID and date found.
• Description: one observable sentence ("export omits rows dated the 31st"), not a theory.
• Introduced at: the stage where the defect entered. Stages, in order: specification, plan or prompt, generation, review, verification, merge or integration, use.
• Caught at: the stage where you found it, from the same list.
• Caught by: the method that found it: agent's own tests, independent acceptance test, diff reading, evidence-package review, mutation testing, running the program, CI, user report, inheritor's characterization test, other.
• Root cause: one code from Table B.1.
• Hours to find and fix.
• Link: commit, issue or evidence package.

The distance between "introduced at" and "caught at" is the defect's escape distance. A defect introduced at generation and caught at review has distance one; the same defect caught in use has distance four. Escape distance is the quantity to watch, because the cost of a defect grows with it.

B.5 Root-cause codes

Assign exactly one primary code. If two apply, choose the earliest cause that, had it been absent, would have prevented the defect, and note the other in the description.

Table B.1. Root-cause codes, with the crosswalk to Chapters 4 and 12.

The last two columns let you pool your data with the chapters' schemes. Chapter 4's four lab categories are a coarse grouping of these codes: spec gap is SPEC, ambiguity is AMB, agent error is any AGT-* code, and other is HUM or ENV. Chapter 12's six defect classes (Table 12.3) map onto the same codes. Four have a code of their own (AGT-API, AGT-DEP, AGT-NULL, AGT-EDIT), the missing server-side check is coded AGT-OTH, and plausible handling of ambiguity is coded SPEC or AMB, because the agent's guess fills a gap the specification left. Always record the Appendix B code; derive the coarser labels from it, never the reverse.

Two tests separate the codes that students confuse.

• AMB or AGT? Ask whether a careful person reading only the specification could have made the same choice. If yes, code AMB. If the specification was clear and the agent departed from it, code AGT.
• SPEC or HUM? If the requirement existed only in your head, code SPEC. If it was written and you overlooked it, code HUM.

Prediction P2 says that SPEC and AMB together (Chapter 4's spec gap and ambiguity) will be the largest category. Your log can show it wrong, which is why you code honestly and decide nothing about the totals until the end.

B.6 CSV headers

Keep the log as plain files in the repository, in log/. Four short files cover everything above. The fourth starts at M3.

# hours.csv   (category: the eight codes in Section B.2, or other)
date,week,phase,category,hours,note
# runs.csv
date,run_id,task_id,tokens_in,tokens_out,cost_usd,lines_presented,lines_resubmitted,lines_merged
# defects.csv
id,date,introduced_at,caught_at,caught_by,root_cause,hours_fix,link
# escalations.csv   (kind: escalation or refusal)
date,run_id,kind,decided_by,minutes_waiting,note

Use the category and root-cause codes exactly as written in this appendix, so that results can be pooled across a class.

B.7 Quantities you compute from the log

After the first milestone, compute these. Chapter 6 defines the agent-aware model that uses them (Section 6.5.1; Appendix E, Section E.5). Table B.2 sends every logged hour to one term of that model.

Table B.2. From log category to model term (after Chapter 6, Table 6.3).

Every hour belongs to one term. Because every parameter comes from the same log, H computed from them equals your logged hours minus other. That is an accounting identity: it shows the terms cover your log, not that the model predicts anything (Chapter 6, Section 6.5.5). Chapter 6, Table 6.4 follows one rejected-and-regenerated task through the crosswalk; use it to check how you code rework.

• Share of hours in each category = category hours ÷ total hours.
• Construction hours = prompting + hand-coding + debugging (Chapter 3, Section 3.6; Chapter 11). Specification, rework, comprehension and other are reported but are not construction. Prediction P1 compares the share of review plus verification hours with the share of construction hours. Comprehension hours are logged separately and are in neither share.
• Steering time per task t_s = (prompting + hand-coding + debugging hours) ÷ n, the number of agent tasks. Debugging is absorbed here, so a defect-heavy project shows up as a larger t_s.
• Generation ratio γ = first-pass lines presented ÷ lines delivered (γ ≥ 1). Each presented line is counted once, the first time you are asked to read it. Alternatives, false starts, discarded attempts and regenerated attempts all count, because their text is new to you. Re-reading text you have already read does not count; that is rework. Delivered lines are those merged and kept in the main line (Chapter 5). γ is 1.0 only if nothing was ever thrown away.
• Observed review rate r = lines presented ÷ first-pass review hours: the rate you actually achieved, the log's counterpart of Chapter 6's r. The book's illustrative 400 lines per hour is the fast end of the verified rates (Chapter 12, Section 12.1.3); compare yours with the rates reported there, and note if you skimmed.
• Rework fraction ρ = rework hours ÷ (first-pass review hours + first-pass verification hours): the re-review, re-verification and re-prompting that follow defects, as a fraction of first-pass work (Chapter 6, Section 6.5.1). If you file the first reading of a regenerated attempt under rework, that reading is priced twice, once in γ and again in ρ, and the model overshoots your log.
• Specification rate s = specification hours ÷ function points.
• Verification rate v = first-pass verification hours ÷ acceptance properties.
• Comprehension rate r_c = lines inherited (or read) ÷ comprehension hours, so that H_comp = L_existing ÷ r_c (inherited phase only).
• Waiting time from M3 on = total minutes waiting across escalations and refusals, and the count of each (Chapter 18, Section 18.7).
• Defects by root cause, and by escape distance.

B.8 Logging honestly

A flattering log is useless to you, because the models you calibrate on it will be wrong in your favor.

• Log the unflattering hours. Hours spent reviewing an agent's mistakes, rerunning, and redoing work are the hours the model most needs.
• Do not round review to zero. Skimming a diff for two minutes is review time. Log two minutes, and note that it was a skim.
• Log discarded attempts. They are lines presented. Without them γ comes out as 1.0 and your review estimate comes out low.
• Log the agent's defects and your own. A log in which every defect is the agent's, or none is, is not believable, and a reader will not believe it.
• Never backfill from memory. If you missed a day, mark the gap. A marked gap costs nothing; a reconstructed week looks like data and is not.
• Never edit an entry to match an estimate. Estimates are pre-registered and logs are not tuned to them (Appendix E, Section E.8).
• Record the code you did not trust. If you merged something unreviewed, log the lines and the reason. That is a risk-register decision (Appendix D).
• Verify any log an agent keeps for you. Check it against the harness's own reports. A log written by the agent is a self-report (Chapter 16, condition 2).