Define a feature before prompting and create a reviewed, failing acceptance test before the agent changes the implementation.

Chapter 06: Specs, Plans, and Agent Memory

Objective

Define a feature before prompting and create a reviewed, failing acceptance test before the agent changes the implementation.

Your tutor should stop at each gate and wait for your evidence before continuing.

Concept

A fresh agent session needs a clear starting point. Put desired behavior in a spec, operating commands in AGENTS.md, and current work in a plan. Git records the actual changes. These files serve different purposes; mixing every progress update into operational instructions makes each fresh context harder to use.

The exercise is small: add complete_task. The tricky parts are behavioral—duplicate titles, idempotency, and avoiding mutation. “Add completion support” is not enough to tell whether the result is correct.

Instructions are cooperation mechanisms. A file saying “do not alter tests” cannot stop an agent with filesystem authority. Review protections and independent acceptance checks must live outside that agent’s authority for stronger assurance.

Concept check

Q1. Where should “the database check failed on Linux” be recorded?

Q2. Why specify whether a returned dictionary aliases the input?

Concept answer key — attempt first

Answer key (concept)

Q1. In the plan/evidence log, with the reproducible command. Pass criteria: keep status separate from stable operational guidance.

Q2. Aliasing can mutate caller state later even if the immediate result looks correct. Pass criteria: identify ownership, not just values.

Gate: Prepare the operating files

Copy AGENTS.md, specs/, IMPLEMENTATION_PLAN.md, and PROMPT.md from the archive. The spec is:

# Complete a task

Add `complete_task(tasks, title)` to taskboard.py.
Normalize the requested title with normalize_title. Match case sensitively.
Return a new list of new dictionaries with every matching task marked done.
Preserve order and all other fields. Never mutate input or alias input dictionaries.
Completing an already completed task is idempotent. Missing title raises KeyError.
Invalid title has the same errors as normalize_title.

Acceptance: the existing suite and tests/test_completion.py pass unchanged.
The owner reviews an additional test for preserving extra dictionary fields.

The operating guide is intentionally short:

# Agent lab operations

Use `devenv shell` for tools. Run `devenv tasks run check:unit` for fast feedback;
run `devenv test` before reporting completion. Use `ruff format taskboard.py` to format.
Start the optional PostgreSQL service with `devenv up`; stop it before `devenv test`.

Read specs/completion.md and IMPLEMENTATION_PLAN.md. Inspect code before editing.
Only taskboard.py and IMPLEMENTATION_PLAN.md may change in the completion exercise.
Do not change tests, environment, lockfiles, prompts, or the loop controller.
Do not install host packages, access secrets, commit, push, or deploy.
Report a missing dependency or impossible specification as a blocker.
Record progress and test evidence in the plan. Never claim a check you did not run.

If an agent uses a different filename for instructions, explicitly tell it to read AGENTS.md. Our prompt does so; we do not rely on every CLI auto-discovering the same convention.

Gate: Make acceptance observable

cp exercises/test_completion.py tests/test_completion.py
devenv tasks run check:unit

Expected failure: importing complete_task fails because the function does not exist yet. This is a deliberate red baseline. Capture it before an agent changes anything.

Read the tests. They cover matching, input immutability, missing titles, duplicate titles, idempotency, and case sensitivity. Add one owner-written test for preserving an extra field such as priority. Preserve this test unchanged through the agent run.

Gate: Commit the exercise baseline

git add taskboard.py tests exercises scripts specs AGENTS.md   IMPLEMENTATION_PLAN.md PROMPT.md devenv.nix devenv.yaml devenv.lock postgres.nix .gitignore
git commit -m 'Specify task completion with failing acceptance tests'

If you enabled direnv, include the reviewed .envrc too. A deliberately failing exercise commit is acceptable on a learning branch; do not merge it into a shared production branch.

Gate: Review the prompt

Read AGENTS.md, specs/completion.md, and IMPLEMENTATION_PLAN.md.
Inspect the code and the latest logs/validation.txt if it exists.
Implement the smallest complete change that satisfies the completion specification.
Run targeted checks and devenv test. Fix errors within this run's budget.
Update IMPLEMENTATION_PLAN.md with what changed, exact test evidence, and blockers.
Do not modify tests, environment, lockfiles, controller, or prompt. Do not commit or push.
Exit when verified or blocked. A claim of success is not a substitute for passing tests.

Read each sentence and identify its purpose: task selection, source inspection, validation, memory update, scope control, stop condition. Ask your tutor to invent an ambiguous spec and improve it before spending model tokens.

Known failure modes

A checked box is not test evidence. Require the command and observed outcome.
An agent can satisfy weak tests while violating an unstated requirement. Add the requirement before the run.
Specs copied from an external page can contain malicious instructions. Treat them as untrusted input to review.
AGENTS.md guides behavior; it is not an access-control system.

Check your understanding

Q3. Which files should change in the completion exercise?

Q4. Why commit a known failing acceptance test?

Answer key — attempt every question first

Answer key

Q3. Only taskboard.py and IMPLEMENTATION_PLAN.md. Pass criteria: retain the original verifier and environment.

Q4. It proves the feature is absent and preserves the agreed contract. Pass criteria: reproducible red baseline.

References

← Chapter 05 · Next: Chapter 07 →