Capstone › Capstone Build II: Ship It › Day 365
Hands-on lab — Day 365: Graduation: Your AI Roadmap Going Forward
- ← Back to the Day 365 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/capstone/day-365-graduation-your-ai-roadmap-going-forward/
Commands
Setup
pip install -r requirements/requirements.txt Run
python examples/plan_demo.py Test
bash tests/run_tests.sh File tree
examples/plan_demo.py examples/plan.py expected-output/examples-run.txt expected-output/FIELDS.md expected-output/measured-values.txt expected-output/run-output.txt expected-output/starter-run.txt expected-output/test-output.txt expected-output/test-run.txt metadata.yml README.md requirements/requirements.txt security.md starter/plan.py tests/run_tests.sh tests/test_plan.py troubleshooting.md
Lab README
Lab — Day 365: Graduation: Your AI Roadmap Going Forward
Lesson
- Lesson title: Graduation: Your AI Roadmap Going Forward
- Day number: 365 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-365-graduation-your-ai-roadmap-going-forward
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-365-graduation-your-ai-roadmap-going-forwardwhen the site is running.
Purpose
Check whether the plan you make today is a plan or a wish list — before week one rather than in week three.
Two things kill a post-course plan, and both are visible in the plan itself before it starts: commitments phrased as topics rather than next actions, and a total that exceeds the hours you actually have. The second is what usually does it, and almost nobody checks it.
The tool does not judge whether your goals are worthwhile. It checks whether the plan is one you could execute.
Learning objectives
- Distinguish a next action from a topic, including a topic dressed as an action.
- Require an artifact — something that exists afterwards and did not before.
- Compute a plan's weekly load against your real available hours.
- Re-cost a plan at your own measured calibration from Day 364.
- Trim to what fits by dropping commitments rather than shaving them, and name what was cut.
Prerequisites
- Day 364, "Capstone Retrospective" — this lab consumes its calibration number.
- Comfortable with Python dataclasses and regular expressions.
Supported operating systems
macOS, Linux and Windows (via WSL or PowerShell). Nothing is platform-specific.
Hardware requirements
Any machine running Python 3.10 or newer. No GPU. The suite completes in hundredths of a second.
Required software
- Python 3.10 or newer.
pytest7 or newer.
Free and open-source options
Every dependency is free and open source: Python is PSF-licensed, pytest is MIT-licensed. No account, no API key, no network — the input is a written plan, so there is nothing to fetch.
Installation
python3 -m venv .venv
.venv/bin/pip install -r requirements/requirements.txt
Removing .venv fully reverses the installation.
File structure
starter/plan.py your work: eight stubbed tasks
examples/plan.py reference implementation
examples/plan_demo.py a plausible post-course plan, checked
tests/test_plan.py grouped by what the check decides
tests/run_tests.sh suite entry point
expected-output/ real captured output and measured values
requirements/ pinned dependency
How to run
python3 examples/plan_demo.py # check a post-course plan
bash tests/run_tests.sh # run the suite
To work on the exercise, edit starter/plan.py, then copy it over the reference:
cp starter/plan.py examples/plan.py
bash tests/run_tests.sh
Keep a copy of the reference first if you want to compare.
What the commands do
python3 examples/plan_demo.py checks six commitments against five available hours a week, twice: as written, and re-costed at the 1.20x calibration measured on Day 364. It then prints what survives, what is cut, and the findings as sentences.
bash tests/run_tests.sh runs pytest over twenty-seven tests grouped by what the check decides: actionability, artifacts, load, calibration, the trim, the review and the findings.
Expected output
--- as written ---
needs 17.0h/week have 5.0h/week 3.40x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- in my own hours ---
needs 20.4h/week have 5.0h/week 4.08x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- what survives ---
keep p1 3.6h/wk evaluation harness for my capstone
keep p2 1.2h/wk writing about the work
cut p3 4.8h/wk fine-tuning
Not one of the six commitments is unreasonable on its own. Together they are three and a half times the available time, and four times it once your own calibration is applied.
expected-output/FIELDS.md explains every field, and expected-output/measured-values.txt records why three commitments fail the wording check and have no artifact — the same three, which is not a coincidence.
Validation steps
bash tests/run_tests.shreports27 passed.- The demo must report
3.40xas written and4.08xonce calibrated. If both are the same, the calibration is being applied after the load is measured rather than before. "build up my understanding of evals"must fail the actionability check despite starting with an action verb.- Two identical commitments must yield one kept and one cut, not zero kept.
Commitmentis a frozen dataclass and compares by value. - A calibration of
0.0must leave the plan unchanged rather than reporting that it fits comfortably.
Tests
Twenty-seven tests in seven groups:
- actionable — action verbs pass; topic verbs fail; a topic verb disqualifies even when an action verb is present; empty fails; multi-word topic verbs are listed.
- artifact — an artifact is required; whitespace is not one; total hours multiply out.
- load — the weekly hours are summed; one hour over does not fit; zero available hours does not divide by zero.
- calibration — every commitment is re-costed; nothing but the hours changes; a nonsensical ratio leaves the plan alone.
- trim — highest priority first; not proportional; it skips past something too big and carries on; a fitting plan is kept whole; cuts are named; duplicates are not confused.
- review — every failure kind is reported; calibration is applied before the load is measured.
- findings — how far over, each cut named, the wording quoted, the fitting case stated, and the calibration disclosed.
Cleanup
rm -rf __pycache__ .pytest_cache
rm -rf .venv
Both are safe to remove and fully reversible.
Troubleshooting
See troubleshooting.md.
Security notes
See security.md. In short: no network, no credentials — and a note on which habits from this year are cheap enough to keep once nobody is grading you.
Extension exercises
- Add dependencies. Let a commitment depend on another, and refuse a plan whose dependencies cannot be satisfied in order. Detect cycles rather than looping.
- Run it on your own plan, with your own available hours and your own calibration from Day 364. Measure the hours; do not estimate them.
- Add a decay model. Available hours are not constant — holidays, deadlines, illness. Check the plan against your worst plausible month rather than your best, and see how many commitments survive that instead.
Navigation
- Lesson
- Previous: Day 364 — Capstone Retrospective
- Next: none — this is the final day.
Expected output
FIELDS.md
# Reading the plan check
## The load line
needs 17.0h/week have 5.0h/week 3.40x OVER
| Part | Meaning |
| --- | --- |
| needs | The weekly hours every commitment adds up to. |
| have | The hours you actually have, which is the number people guess rather than measure. |
| ratio | How many times over budget the plan is. 1.0 exactly fits. |
| fits / OVER | Whether the plan is executable at all. |
The plan is printed twice: as written, and re-costed at your measured
calibration from day 364. Both are shown because the gap between them is the
part optimism hides.
as written needs 17.0h/week 3.40x OVER
in my own hours needs 20.4h/week 4.08x OVER
## The summary line
2 kept / 4 cut not-actionable=3 no-artifact=3
| Field | Meaning |
| --- | --- |
| kept | Commitments that fit inside the available hours. |
| cut | Commitments that do not. Cut now and deliberately, or in week three by attrition. |
| not-actionable | The next action names a topic rather than something you could start within the hour. |
| no-artifact | Nothing will exist afterwards that did not exist before. |
## What the trim does, and what it deliberately does not
It keeps commitments highest-priority-first while they still fit, and it
**skips past one that does not fit** rather than stopping. Stopping would waste
every remaining hour.
That has a consequence worth seeing rather than hiding: a cheap low-priority
commitment can survive when a dear high-priority one does not fit at the point
it is considered.
keep p1 3.6h/wk evaluation harness for my capstone
keep p2 1.2h/wk writing about the work
cut p2 2.4h/wk open-source contribution
The open-source contribution is the same priority as the writing and was cut,
because 3.6 + 2.4 exceeds 5.0 while 3.6 + 1.2 does not. The right response to
that output is usually to **split the expensive commitment**, not to accept the
substitution the tool made. The tool cannot make that call, and it should not
pretend to.
## The trim is not proportional
Six commitments at half the hours each is six things done badly. Two
commitments at full hours is two things done. The plan that fits is the plan
that happens, which is why the trim drops commitments rather than shaving them.
## The findings
Sentences rather than a score, because a score is not an instruction:
| Finding | Trigger |
| --- | --- |
| calibration applied | A calibration above 1.0 was used, so the reader knows which hours these are. |
| how far over | The load does not fit. |
| how many survive, and each cut named | The load does not fit. |
| rewrite this wording | A next action that names a topic, quoted so the fix is obvious. |
| name what will exist | A commitment with no artifact. |
| the plan fits | Everything fits — reported explicitly, and worth not filling. |
examples-run.txt
--- as written ---
needs 17.0h/week have 5.0h/week 3.40x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- in my own hours ---
needs 20.4h/week have 5.0h/week 4.08x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- what survives ---
keep p1 3.6h/wk evaluation harness for my capstone
keep p2 1.2h/wk writing about the work
cut p3 4.8h/wk fine-tuning
cut p2 2.4h/wk open-source contribution
cut p4 3.6h/wk agent frameworks
cut p5 4.8h/wk systems and scaling
--- findings ---
- Costed at your measured 1.20x rather than in optimistic hours.
- The plan needs 20.4h/week and you have 5.0h — it is 4.08x over before it starts.
- 2 of 6 commitments fit. Cut the rest now, deliberately, rather than in week three by attrition.
- cut: fine-tuning (priority 3, 4.8h/week)
- cut: open-source contribution (priority 2, 2.4h/week)
- cut: agent frameworks (priority 4, 3.6h/week)
- cut: systems and scaling (priority 5, 4.8h/week)
- 'fine-tuning' names a topic, not a next action — rewrite 'learn how LoRA works'.
- 'agent frameworks' names a topic, not a next action — rewrite 'explore the main agent frameworks'.
- 'systems and scaling' names a topic, not a next action — rewrite 'get better at distributed systems'.
- 'fine-tuning' produces nothing checkable. Name what will exist afterwards.
- 'agent frameworks' produces nothing checkable. Name what will exist afterwards.
- 'systems and scaling' produces nothing checkable. Name what will exist afterwards.
measured-values.txt
Measured on macOS 26.5.1 (Apple Silicon), Python 3.14.0, pytest 9.1.1.
python3 examples/plan_demo.py -> 27 lines, exit 0
bash tests/run_tests.sh -> 27 passed in 0.02s
the untouched starter -> 25 failed, 2 passed in 0.07s
Six commitments, five available hours a week.
The number this lab exists for:
as written 17.0h/week needed against 5.0 available 3.40x over
in my own hours 20.4h/week needed against 5.0 available 4.08x over
surviving 2 of 6
Not one of the six commitments is unreasonable on its own. Three hours a week
on evals, two on an open-source contribution, one on writing -- each is the
kind of thing anybody would agree to. Added up they are three and a half times
the time available, and applying the day 364 calibration of 1.20x takes it to
four.
This plan does not fail in week three because of discipline. It was arithmetic-
ally impossible on the day it was written, and nobody did the arithmetic.
What survives:
keep p1 3.6h/wk evaluation harness for my capstone
keep p2 1.2h/wk writing about the work
What does not:
cut p3 4.8h/wk fine-tuning
cut p2 2.4h/wk open-source contribution
cut p4 3.6h/wk agent frameworks
cut p5 4.8h/wk systems and scaling
Note the second cut. "Open-source contribution" is priority 2, the same as the
writing that survived, and it was cut because 3.6 + 2.4 exceeds 5.0 while
3.6 + 1.2 does not. The greedy trim skips what does not fit and carries on, so
a cheaper commitment can outlive a dearer one of equal priority. That is a
real property rather than a bug -- stopping at the first non-fitting item would
waste the remaining 1.4 hours entirely -- but the right response is usually to
split the expensive commitment rather than to accept the substitution.
Three of the six also fail the wording check, and they are the same three that
have no artifact:
fine-tuning "learn how LoRA works"
agent frameworks "explore the main agent frameworks"
systems and scaling "get better at distributed systems"
That correlation is not a coincidence and it is the second finding of the lab.
A commitment phrased as a topic has no artifact because a topic does not
produce one. The two checks catch the same underlying failure from opposite
directions, which is why a plan can look full and contain very little.
One implementation note. is_actionable rejects a topic verb even when an action
verb is also present, so "build up my understanding of evals" fails. An earlier
version tested only for a leading action verb and passed that sentence -- which
would have let the single most common way of dressing a topic as an action
straight through the check.
run-output.txt
--- as written ---
needs 17.0h/week have 5.0h/week 3.40x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- in my own hours ---
needs 20.4h/week have 5.0h/week 4.08x OVER
2 kept / 4 cut not-actionable=3 no-artifact=3
--- what survives ---
keep p1 3.6h/wk evaluation harness for my capstone
keep p2 1.2h/wk writing about the work
cut p3 4.8h/wk fine-tuning
cut p2 2.4h/wk open-source contribution
cut p4 3.6h/wk agent frameworks
cut p5 4.8h/wk systems and scaling
--- findings ---
- Costed at your measured 1.20x rather than in optimistic hours.
- The plan needs 20.4h/week and you have 5.0h — it is 4.08x over before it starts.
- 2 of 6 commitments fit. Cut the rest now, deliberately, rather than in week three by attrition.
- cut: fine-tuning (priority 3, 4.8h/week)
- cut: open-source contribution (priority 2, 2.4h/week)
- cut: agent frameworks (priority 4, 3.6h/week)
- cut: systems and scaling (priority 5, 4.8h/week)
- 'fine-tuning' names a topic, not a next action — rewrite 'learn how LoRA works'.
- 'agent frameworks' names a topic, not a next action — rewrite 'explore the main agent frameworks'.
- 'systems and scaling' names a topic, not a next action — rewrite 'get better at distributed systems'.
- 'fine-tuning' produces nothing checkable. Name what will exist afterwards.
- 'agent frameworks' produces nothing checkable. Name what will exist afterwards.
- 'systems and scaling' produces nothing checkable. Name what will exist afterwards.
starter-run.txt
An untouched starter fails nearly the whole suite:
25 failed, 2 passed in 0.07s
The two that pass are test_topic_verbs_are_listed_including_multiword_forms,
which exercises topic_verbs_in, and test_total_hours_is_the_weekly_cost_over_
the_weeks, which exercises the Commitment dataclass. Neither is one of the
eight stubbed tasks.
Fix them in order. Task 3, the load, is the one that produces the number the
whole lab is about.
test-output.txt
........................... [100%]
27 passed in 0.01s
test-run.txt
........................... [100%]
27 passed in 0.01s
Source files
examples/plan_demo.py (2537 bytes)
#!/usr/bin/env python3
"""A plausible post-course plan, checked before week one."""
from __future__ import annotations
import os
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from plan import Commitment, findings, review
# Six commitments. Every one of them sounds modest on its own.
PLAN = [
Commitment(
topic="evaluation harness for my capstone",
next_action="build a 50-question eval set and run it weekly",
artifact="eval suite in the capstone repository",
hours_per_week=3,
weeks=8,
priority=1,
),
Commitment(
topic="fine-tuning",
next_action="learn how LoRA works",
artifact="",
hours_per_week=4,
weeks=6,
priority=3,
),
Commitment(
topic="open-source contribution",
next_action="fix one documented issue in a retrieval library",
artifact="a merged pull request",
hours_per_week=2,
weeks=12,
priority=2,
),
Commitment(
topic="agent frameworks",
next_action="explore the main agent frameworks",
artifact="",
hours_per_week=3,
weeks=6,
priority=4,
),
Commitment(
topic="writing about the work",
next_action="publish one post on what the capstone retrospective found",
artifact="a published post",
hours_per_week=1,
weeks=4,
priority=2,
),
Commitment(
topic="systems and scaling",
next_action="get better at distributed systems",
artifact="",
hours_per_week=4,
weeks=10,
priority=5,
),
]
AVAILABLE_HOURS = 5.0
MY_CALIBRATION = 1.20 # measured on day 364
def main() -> int:
plain = review(PLAN, AVAILABLE_HOURS)
print("--- as written ---")
print(f" {plain.load.line()}")
print(f" {plain.summary()}")
costed = review(PLAN, AVAILABLE_HOURS, calibration=MY_CALIBRATION)
print("--- in my own hours ---")
print(f" {costed.load.line()}")
print(f" {costed.summary()}")
print("--- what survives ---")
for c in costed.kept:
print(f" keep p{c.priority} {c.hours_per_week:>4.1f}h/wk {c.topic}")
for c in costed.cut:
print(f" cut p{c.priority} {c.hours_per_week:>4.1f}h/wk {c.topic}")
print("--- findings ---")
for finding in findings(PLAN, AVAILABLE_HOURS, calibration=MY_CALIBRATION):
print(f" - {finding}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
examples/plan.py (8027 bytes)
"""Check whether a post-course learning plan is a plan or a wish list.
Offline and standard-library only. The input is a list of written commitments,
so nothing is fetched.
Almost every plan made at the end of a course dies in about week three, and it
usually dies for one of two reasons that are visible in the plan itself before
it starts:
not actionable "get better at evals" names a topic, not a next action
not affordable the hours it needs exceed the hours you actually have
The second is the one that kills plans, and it is the one nobody checks. Six
commitments that each sound modest can add up to three times the time you have,
and the failure arrives as a vague sense of falling behind rather than as an
arithmetic error -- which is why it is never diagnosed and never fixed.
So this module does the arithmetic. It also applies your OWN calibration from
day 364, because a plan costed in optimistic hours is not costed at all.
Nothing here judges whether your goals are worthwhile. It checks whether the
plan is one you could actually execute, which is a different question and the
one that decides the outcome.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
# Verbs that name a topic rather than an action. Each one describes a state you
# would like to be in, and none of them tells you what to do on Monday.
TOPIC_VERBS = (
"learn",
"study",
"explore",
"understand",
"get better at",
"get familiar with",
"read about",
"look into",
"dive into",
"master",
"improve my",
"brush up",
)
# A next action starts with something you could begin within the hour.
ACTION_VERB = re.compile(
r"^\s*(build|write|ship|deploy|measure|benchmark|implement|port|replace|"
r"instrument|profile|reproduce|publish|contribute|review|refactor|migrate|"
r"automate|test|add|fix|extend|compare|run)\b",
re.I,
)
@dataclass(frozen=True)
class Commitment:
topic: str
next_action: str
artifact: str # what exists afterwards that did not exist before
hours_per_week: float
weeks: int
priority: int = 3 # 1 is highest
@property
def total_hours(self) -> float:
return self.hours_per_week * self.weeks
@dataclass
class Load:
weekly: float
available: float
@property
def ratio(self) -> float:
"""How many times over budget the plan is. 1.0 exactly fits."""
return self.weekly / self.available if self.available else 0.0
@property
def fits(self) -> bool:
return self.weekly <= self.available
def line(self) -> str:
return (
f"needs {self.weekly:.1f}h/week have {self.available:.1f}h/week "
f"{self.ratio:.2f}x {'fits' if self.fits else 'OVER'}"
)
def topic_verbs_in(text: str) -> list[str]:
lowered = text.lower()
return sorted(v for v in TOPIC_VERBS if lowered.startswith(v) or f" {v}" in lowered)
def is_actionable(next_action: str) -> bool:
"""Whether this is something you could start within the hour.
Two conditions, and both are needed. A topic verb disqualifies it even when
an action verb appears later in the sentence, because "build up my
understanding of evals" is a topic wearing an action's clothes.
"""
if not next_action.strip():
return False
if topic_verbs_in(next_action):
return False
return ACTION_VERB.search(next_action) is not None
def has_artifact(commitment: Commitment) -> bool:
"""Whether something exists afterwards that did not exist before.
This is what makes a commitment checkable by anyone, including future you.
"Confidence with agents" is not an artifact. A repository is.
"""
return bool(commitment.artifact.strip())
def weekly_load(commitments: list[Commitment], available: float) -> Load:
return Load(weekly=sum(c.hours_per_week for c in commitments), available=available)
def with_calibration(commitments: list[Commitment], ratio: float) -> list[Commitment]:
"""Re-cost the plan in YOUR hours rather than optimistic ones.
Day 364 measured how wrong your estimates are. A plan costed without that
correction is costed in hours belonging to somebody who does not exist.
"""
if ratio <= 0:
return list(commitments)
return [
Commitment(
topic=c.topic,
next_action=c.next_action,
artifact=c.artifact,
hours_per_week=round(c.hours_per_week * ratio, 2),
weeks=c.weeks,
priority=c.priority,
)
for c in commitments
]
def trim_to_fit(commitments: list[Commitment], available: float) -> list[Commitment]:
"""What actually survives the hours you have, highest priority first.
Deliberately not proportional. Halving the hours on six commitments gives
you six things done badly; keeping two gives you two things done. The plan
that fits is the plan that happens.
"""
kept: list[Commitment] = []
spent = 0.0
for c in sorted(commitments, key=lambda c: (c.priority, -c.hours_per_week, c.topic)):
if spent + c.hours_per_week <= available:
kept.append(c)
spent += c.hours_per_week
return kept
def dropped(commitments: list[Commitment], available: float) -> list[Commitment]:
"""What the trim removed. Worth naming, so the choice is made rather than
discovered in week three."""
kept = {id(c) for c in trim_to_fit(commitments, available)}
return [c for c in commitments if id(c) not in kept]
@dataclass
class PlanReport:
load: Load
not_actionable: list[Commitment] = field(default_factory=list)
no_artifact: list[Commitment] = field(default_factory=list)
kept: list[Commitment] = field(default_factory=list)
cut: list[Commitment] = field(default_factory=list)
def summary(self) -> str:
return (
f"{len(self.kept)} kept / {len(self.cut)} cut "
f"not-actionable={len(self.not_actionable)} no-artifact={len(self.no_artifact)}"
)
def review(commitments: list[Commitment], available: float, *, calibration: float = 1.0) -> PlanReport:
"""The whole check, in your own hours."""
costed = with_calibration(commitments, calibration)
return PlanReport(
load=weekly_load(costed, available),
not_actionable=[c for c in costed if not is_actionable(c.next_action)],
no_artifact=[c for c in costed if not has_artifact(c)],
kept=trim_to_fit(costed, available),
cut=dropped(costed, available),
)
def findings(commitments: list[Commitment], available: float, *, calibration: float = 1.0) -> list[str]:
"""The review, as sentences you can act on before week one."""
out: list[str] = []
report = review(commitments, available, calibration=calibration)
if calibration > 1.0:
out.append(
f"Costed at your measured {calibration:.2f}x rather than in optimistic hours."
)
if not report.load.fits:
out.append(
f"The plan needs {report.load.weekly:.1f}h/week and you have "
f"{report.load.available:.1f}h — it is {report.load.ratio:.2f}x over before it starts."
)
out.append(
f"{len(report.kept)} of {len(commitments)} commitments fit. Cut the rest now, "
"deliberately, rather than in week three by attrition."
)
for c in report.cut:
out.append(f"cut: {c.topic} (priority {c.priority}, {c.hours_per_week:.1f}h/week)")
else:
out.append(
f"The plan fits: {report.load.weekly:.1f}h/week against {report.load.available:.1f}h "
"available. Rare, and worth not filling."
)
for c in report.not_actionable:
out.append(f"'{c.topic}' names a topic, not a next action — rewrite '{c.next_action}'.")
for c in report.no_artifact:
out.append(f"'{c.topic}' produces nothing checkable. Name what will exist afterwards.")
return out
metadata.yml (936 bytes)
lesson_id: D365
day: 365
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/plan_demo.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 55
last_executed: '2026-08-31'
executed_on: 'macOS 26.5.1 (Apple Silicon), Python 3.14.0, pytest 9.1.1 — python3 examples/plan_demo.py
reproduced the documented figures exactly (17.0h/week needed against 5.0 available as written, 20.4h
once costed at the day-364 calibration of 1.20x, 2 of 6 commitments surviving); bash tests/run_tests.sh
-> 27 passed in 0.02s. The untouched starter fails 25 of 27; the 2 that pass exercise topic_verbs_in
and the Commitment dataclass, neither of which is stubbed. requires_network is false: the input is a
written plan, so there is nothing to fetch.'
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/plan.py (7112 bytes)
"""STARTER -- implement the eight tasks below, then run the tests.
Check whether a post-course learning plan is a plan or a wish list.
Offline and standard-library only. The input is a list of written commitments,
so nothing is fetched.
Almost every plan made at the end of a course dies in about week three, and it
usually dies for one of two reasons that are visible in the plan itself before
it starts:
not actionable "get better at evals" names a topic, not a next action
not affordable the hours it needs exceed the hours you actually have
The second is the one that kills plans, and it is the one nobody checks. Six
commitments that each sound modest can add up to three times the time you have,
and the failure arrives as a vague sense of falling behind rather than as an
arithmetic error -- which is why it is never diagnosed and never fixed.
So this module does the arithmetic. It also applies your OWN calibration from
day 364, because a plan costed in optimistic hours is not costed at all.
Nothing here judges whether your goals are worthwhile. It checks whether the
plan is one you could actually execute, which is a different question and the
one that decides the outcome.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
# Verbs that name a topic rather than an action. Each one describes a state you
# would like to be in, and none of them tells you what to do on Monday.
TOPIC_VERBS = (
"learn",
"study",
"explore",
"understand",
"get better at",
"get familiar with",
"read about",
"look into",
"dive into",
"master",
"improve my",
"brush up",
)
# A next action starts with something you could begin within the hour.
ACTION_VERB = re.compile(
r"^\s*(build|write|ship|deploy|measure|benchmark|implement|port|replace|"
r"instrument|profile|reproduce|publish|contribute|review|refactor|migrate|"
r"automate|test|add|fix|extend|compare|run)\b",
re.I,
)
@dataclass(frozen=True)
class Commitment:
topic: str
next_action: str
artifact: str # what exists afterwards that did not exist before
hours_per_week: float
weeks: int
priority: int = 3 # 1 is highest
@property
def total_hours(self) -> float:
return self.hours_per_week * self.weeks
@dataclass
class Load:
weekly: float
available: float
@property
def ratio(self) -> float:
"""How many times over budget the plan is. 1.0 exactly fits."""
return self.weekly / self.available if self.available else 0.0
@property
def fits(self) -> bool:
return self.weekly <= self.available
def line(self) -> str:
return (
f"needs {self.weekly:.1f}h/week have {self.available:.1f}h/week "
f"{self.ratio:.2f}x {'fits' if self.fits else 'OVER'}"
)
def topic_verbs_in(text: str) -> list[str]:
lowered = text.lower()
return sorted(v for v in TOPIC_VERBS if lowered.startswith(v) or f" {v}" in lowered)
def is_actionable(next_action: str) -> bool:
"""Whether this is something you could start within the hour.
Two conditions, and both are needed. A topic verb disqualifies it even when
an action verb appears later in the sentence, because "build up my
understanding of evals" is a topic wearing an action's clothes.
"""
raise NotImplementedError(
"TASK 1: empty is not actionable; a topic verb anywhere disqualifies it "
"even when an action verb also appears; otherwise require an action verb "
"at the START of the sentence."
)
def has_artifact(commitment: Commitment) -> bool:
"""Whether something exists afterwards that did not exist before.
This is what makes a commitment checkable by anyone, including future you.
"Confidence with agents" is not an artifact. A repository is.
"""
raise NotImplementedError("TASK 2: whitespace is not an artifact")
def weekly_load(commitments: list[Commitment], available: float) -> Load:
raise NotImplementedError("TASK 3: sum the weekly hours into a Load")
def with_calibration(commitments: list[Commitment], ratio: float) -> list[Commitment]:
"""Re-cost the plan in YOUR hours rather than optimistic ones.
Day 364 measured how wrong your estimates are. A plan costed without that
correction is costed in hours belonging to somebody who does not exist.
"""
raise NotImplementedError(
"TASK 4: scale hours_per_week by the ratio, rounded to 2 decimals, and "
"change NOTHING else. A ratio of zero or less is nonsense -- return the "
"plan unchanged rather than zeroing it."
)
def trim_to_fit(commitments: list[Commitment], available: float) -> list[Commitment]:
"""What actually survives the hours you have, highest priority first.
Deliberately not proportional. Halving the hours on six commitments gives
you six things done badly; keeping two gives you two things done. The plan
that fits is the plan that happens.
"""
raise NotImplementedError(
"TASK 5: highest priority first, keeping each commitment that still "
"fits. SKIP past one that does not and carry on -- stopping would waste "
"every remaining hour."
)
def dropped(commitments: list[Commitment], available: float) -> list[Commitment]:
"""What the trim removed. Worth naming, so the choice is made rather than
discovered in week three."""
raise NotImplementedError(
"TASK 6: everything the trim removed. Careful -- two identical "
"commitments are EQUAL as dataclasses, so a value-based membership test "
"drops both."
)
@dataclass
class PlanReport:
load: Load
not_actionable: list[Commitment] = field(default_factory=list)
no_artifact: list[Commitment] = field(default_factory=list)
kept: list[Commitment] = field(default_factory=list)
cut: list[Commitment] = field(default_factory=list)
def summary(self) -> str:
return (
f"{len(self.kept)} kept / {len(self.cut)} cut "
f"not-actionable={len(self.not_actionable)} no-artifact={len(self.no_artifact)}"
)
def review(commitments: list[Commitment], available: float, *, calibration: float = 1.0) -> PlanReport:
"""The whole check, in your own hours."""
raise NotImplementedError(
"TASK 7: apply the calibration FIRST, then measure everything against "
"the re-costed plan rather than the optimistic one."
)
def findings(commitments: list[Commitment], available: float, *, calibration: float = 1.0) -> list[str]:
"""The review, as sentences you can act on before week one."""
raise NotImplementedError(
"TASK 8: sentences, not scores. Cover (a) that calibration was applied, "
"when it was; (b) how far over the plan is, or that it fits; (c) how "
"many commitments survive, and one line naming each cut; (d) one line "
"per commitment that names a topic rather than an action, quoting the "
"wording to rewrite; (e) one per commitment with no artifact."
)
tests/run_tests.sh (194 bytes)
#!/usr/bin/env bash
# Run the day 365 plan test suite.
# Offline, standard library plus pytest. No network, no API key.
set -euo pipefail
cd "$(dirname "$0")/.."
python3 -m pytest tests -q "$@"
tests/test_plan.py (7522 bytes)
"""Grouped by what the plan check decides.
Run with: bash tests/run_tests.sh
"""
from __future__ import annotations
import os
import sys
HERE = os.path.dirname(os.path.abspath(__file__))
LAB = os.path.dirname(HERE)
sys.path.insert(0, os.path.join(LAB, "examples"))
from plan import ( # noqa: E402
Commitment,
dropped,
findings,
has_artifact,
is_actionable,
review,
topic_verbs_in,
trim_to_fit,
weekly_load,
with_calibration,
)
def c(topic, action="build a thing", artifact="a repository", hours=1.0, weeks=4, priority=3):
return Commitment(topic, action, artifact, hours, weeks, priority)
# ---------------------------------------------------------------- actionable
def test_an_action_verb_makes_a_next_action():
assert is_actionable("build a 50-question eval set and run it weekly")
assert is_actionable("publish one post on what the retrospective found")
def test_a_topic_verb_is_not_a_next_action():
assert not is_actionable("learn how LoRA works")
assert not is_actionable("get better at distributed systems")
assert not is_actionable("explore the main agent frameworks")
def test_a_topic_verb_disqualifies_even_with_an_action_verb_present():
# "build up my understanding" is a topic wearing an action's clothes.
assert not is_actionable("build up my understanding of evals")
def test_an_empty_next_action_is_not_actionable():
assert not is_actionable("")
assert not is_actionable(" ")
def test_topic_verbs_are_listed_including_multiword_forms():
assert topic_verbs_in("I want to get better at evals and read about agents") == [
"get better at",
"read about",
]
# ------------------------------------------------------------------ artifact
def test_a_commitment_with_an_artifact_is_checkable():
assert has_artifact(c("evals", artifact="eval suite in the repository"))
def test_a_commitment_with_no_artifact_is_not():
assert not has_artifact(c("agents", artifact=""))
assert not has_artifact(c("agents", artifact=" "))
def test_total_hours_is_the_weekly_cost_over_the_weeks():
assert c("evals", hours=3, weeks=8).total_hours == 24
# ---------------------------------------------------------------------- load
def test_load_sums_the_weekly_hours():
load = weekly_load([c("a", hours=3), c("b", hours=2)], 5.0)
assert load.weekly == 5.0
assert load.fits
def test_a_plan_one_hour_over_does_not_fit():
load = weekly_load([c("a", hours=3), c("b", hours=3)], 5.0)
assert not load.fits
assert round(load.ratio, 2) == 1.2
def test_zero_available_hours_does_not_divide_by_zero():
assert weekly_load([c("a", hours=3)], 0.0).ratio == 0.0
# --------------------------------------------------------------- calibration
def test_calibration_recosts_every_commitment():
costed = with_calibration([c("a", hours=3), c("b", hours=2)], 1.20)
assert [x.hours_per_week for x in costed] == [3.6, 2.4]
def test_calibration_preserves_everything_but_the_hours():
original = c("evals", action="build an eval set", artifact="a suite", hours=3, priority=1)
costed = with_calibration([original], 1.5)[0]
assert (costed.topic, costed.next_action, costed.artifact, costed.priority) == (
"evals",
"build an eval set",
"a suite",
1,
)
def test_a_nonsensical_calibration_leaves_the_plan_alone():
plan = [c("a", hours=3)]
assert with_calibration(plan, 0.0) == plan
assert with_calibration(plan, -1.0) == plan
# ---------------------------------------------------------------------- trim
def test_the_trim_keeps_highest_priority_first():
plan = [c("low", hours=3, priority=5), c("high", hours=3, priority=1)]
assert [x.topic for x in trim_to_fit(plan, 5.0)] == ["high"]
def test_the_trim_is_not_proportional():
# Six commitments halved is six things done badly. The plan that fits is
# the plan that happens.
plan = [c(f"t{i}", hours=2, priority=i) for i in range(1, 7)]
kept = trim_to_fit(plan, 5.0)
assert len(kept) == 2
assert all(x.hours_per_week == 2 for x in kept)
def test_the_trim_skips_past_something_too_big_to_fit():
# A known and deliberate property: the top-priority commitment does not fit
# at all, so a cheaper lower-priority one survives instead. Stopping at the
# first thing that does not fit would waste every remaining hour.
#
# The right response to this output is usually to SPLIT the p1 commitment,
# not to accept the p5 one in its place. The tool cannot make that call.
plan = [c("dear", hours=6, priority=1), c("cheap", hours=1, priority=5)]
assert [x.topic for x in trim_to_fit(plan, 5.0)] == ["cheap"]
def test_a_plan_that_already_fits_is_kept_whole():
plan = [c("a", hours=2), c("b", hours=2)]
assert len(trim_to_fit(plan, 5.0)) == 2
assert dropped(plan, 5.0) == []
def test_dropped_names_what_the_trim_removed():
plan = [c("keep", hours=3, priority=1), c("drop", hours=3, priority=2)]
assert [x.topic for x in dropped(plan, 5.0)] == ["drop"]
def test_duplicate_commitments_are_not_confused_with_each_other():
# Two identical commitments are equal as dataclasses; the trim must still
# keep one and drop the other rather than dropping both.
same = c("evals", hours=3, priority=1)
plan = [same, c("evals", hours=3, priority=1)]
assert len(trim_to_fit(plan, 5.0)) == 1
assert len(dropped(plan, 5.0)) == 1
# -------------------------------------------------------------------- review
def test_the_review_reports_every_failure_kind():
plan = [
c("good", action="build an eval set", artifact="a suite", hours=2, priority=1),
c("vague", action="learn about agents", artifact="", hours=4, priority=2),
]
report = review(plan, 5.0)
assert [x.topic for x in report.not_actionable] == ["vague"]
assert [x.topic for x in report.no_artifact] == ["vague"]
assert [x.topic for x in report.kept] == ["good"]
def test_the_review_applies_calibration_before_measuring_the_load():
plan = [c("a", hours=4)]
assert review(plan, 5.0).load.fits
assert not review(plan, 5.0, calibration=1.5).load.fits
# ------------------------------------------------------------------ findings
def test_findings_state_how_far_over_the_plan_is():
plan = [c(f"t{i}", hours=3) for i in range(4)]
out = findings(plan, 5.0)
assert any("2.40x over before it starts" in f for f in out)
def test_findings_name_each_cut_commitment():
plan = [c("keep", hours=3, priority=1), c("cut me", hours=3, priority=2)]
out = findings(plan, 5.0)
assert any(f.startswith("cut: cut me") for f in out)
def test_findings_quote_the_wording_that_needs_rewriting():
plan = [c("agents", action="explore the main agent frameworks", hours=1)]
out = findings(plan, 5.0)
assert any("rewrite 'explore the main agent frameworks'" in f for f in out)
def test_findings_say_so_when_the_plan_fits():
plan = [c("a", action="build an eval set", artifact="a suite", hours=2)]
out = findings(plan, 5.0)
assert any("The plan fits" in f for f in out)
assert not any(f.startswith("cut:") for f in out)
def test_findings_disclose_that_calibration_was_applied():
plan = [c("a", action="build an eval set", artifact="a suite", hours=2)]
assert any("1.20x" in f for f in findings(plan, 5.0, calibration=1.20))
assert not any("rather than in optimistic hours" in f for f in findings(plan, 5.0))
Troubleshooting
Troubleshooting — Day 365
NotImplementedError on nearly every test
Expected. The starter stubs eight functions — see expected-output/starter-run.txt, which names the two tests that pass without them.
Fix them in order. Task 3, the load, produces the number the whole lab is about.
"build up my understanding of evals" passes the actionability check
You are testing only for a leading action verb. That sentence starts with "build" and commits to nothing, and it is the single most common way of dressing a topic as an action.
A topic verb anywhere in the sentence disqualifies it, even when an action verb is also present. Check for topic verbs first and return early.
test_topic_verbs_are_listed_including_multiword_forms fails
Your search is word-by-word, so the multi-word entries — "get better at", "read about" — never match. Test each entry as a substring of the lowered text, and check startswith as well so a sentence beginning with the verb is caught.
test_a_nonsensical_calibration_leaves_the_plan_alone fails
A ratio of zero would silently zero every commitment's hours and report that the plan fits comfortably, which is the worst possible failure for this tool. Return the plan unchanged for any ratio at or below zero.
test_duplicate_commitments_are_not_confused_with_each_other fails
Commitment is a frozen dataclass, so two identical commitments compare equal. A membership test like c not in kept therefore drops both. Compare by id(), or track indices.
The trim shaves hours instead of dropping commitments
Deliberately not what this does. Six commitments at half the hours each is six things done badly; two at full hours is two things done. Drop whole commitments.
A low-priority commitment survives while a high-priority one is cut
Correct, and worth understanding rather than fixing. The trim skips past a commitment too expensive to fit and carries on, because stopping would waste every remaining hour.
On the demo record the priority-2 open-source contribution is cut while the priority-2 writing survives, since 3.6 + 2.4 exceeds the 5.0 budget and 3.6 + 1.2 does not. The right response is usually to split the expensive commitment rather than accept the substitution — a judgement the tool cannot make for you.
review reports a load that fits, but the demo says it does not
You are measuring the load before applying the calibration. Re-cost first, then measure everything — the load, the trim and the cuts — against the re-costed plan. Measuring the optimistic plan and then reporting a calibrated number is how a tool tells you something reassuring and wrong.
The findings do not mention that calibration was applied
Add the disclosure line whenever the ratio is above 1.0. A reader looking at "needs 20.4h/week" is entitled to know those are your measured hours rather than the ones you wrote down.
Everything is cut and the report is dispiriting
That is the finding. A plan four times over budget is not a discipline problem to be pushed through; it was impossible on the day it was written. Reduce the commitments, or reduce the hours each one claims, and run it again — the point of the check is that this conversation happens in week zero rather than week three.
Security notes
Security notes — Day 365
What this lab does and does not touch
- No network. The input is a written plan. Nothing is fetched.
- No credentials. No API key, token or account.
- No writes outside this directory. Only
__pycache__/,.pytest_cache/and, if you create it,.venv/. - No
sudo, no global installs. - The example plan is fictional, and deliberately typical rather than drawn from anyone's real commitments.
Keeping the habits when nobody is grading you
This is the last day, and the security point of it is not about this lab. It is that the practices from the past year survive only if they are cheap enough to keep doing without a course telling you to.
Four that are worth the minutes, in rough order of how often skipping them causes real harm:
- Secret scanning before anything goes public. Making a repository public exposes every commit, not just the current tree.
gitleaksover the history takes seconds and is the single highest-value habit on this list. - A spend cap on anything that calls a paid API. Day 327's per-request cap and Day 360's budget alarm. An agent with a retry loop and no cap is the most common expensive accident in this field, and it happens to careful people.
- Untrusted input stays untrusted. Day 361's review. Retrieved documents, tool output and user text are data, never instructions, and that does not stop being true because the project is small.
- A dependency you did not read is a dependency you trusted. Pin versions, and look at what a new package actually pulls in before it is in your lock file.
If you keep one, keep the first. It is the one whose failures are permanent.
A learning plan is a personal document
If you publish yours — some people do, and it is a reasonable way to stay accountable — it states your available hours, what you are weak at, and what you are working on. That is unremarkable on its own and worth a moment's thought if your plan names an employer's systems, an unfixed weakness in something you run, or hours that contradict what you have told somebody.
Nothing here needs paranoia. It needs the same read-before-publishing pass as anything else that leaves your machine.
Reversing everything this lab did
rm -rf __pycache__ .pytest_cache .venv
Nothing else was created, and nothing outside this directory was modified.