[Carr1005]

Replaces the loop-engineering agnostic spec.md (guide 11b3673, 2026-10-12; it predates the Lesson 6 transcript, #48 U18) with a fresh clean-room generation on guide 5caba53 (#62, merged).

How it was made (Opus 5.5)

1. A clean-room generation from the guide and course materials only. Checker: 0 findings.
2. Two independent audits, each followed by a repair pass. Repairs fix consistency only: counts, fixtures, citations, schemas and "Tests by option" cells. They make no decisions and add no rules or tests.
3. A script compared the generated spec with the final one:
   • no Ledger row changed;
   • the same 29 rules and 43 tests;
   • the gate text is unchanged.
4. A purpose probe on the generation took the "no grader" option. 60 of 63 items were covered, left out or adapted as the guide intends, 1 sat in the gate and 2 needed a guess (details in Guide: rows never restate parts another option removes; gate step 5 leaves out what exists only for a retired rule and records adapted criteria #62).

Repair conventions to note (new text, within the rules):

• fixture timestamps;
• the exact event-banner wording;
• the exact text of the baseline instructions file and the rubric file.

What changed for a learner

• 12 decisions (was 10). The four loops are now separate questions: where instructions live; whether a grader checks the report, and what kind; what starts a review; whether the agent learns across runs. Real Slack/Jira are offered as heavy-setup options (shown in the course, no code shipped).
• Skips: the learning-loop question is asked only when a grader exists; the event-surface question only when events start reviews.
• A plain-language table of every decision and option is in the first comment below, for review.

Known open points (decisions, not repaired; going to #48)

• The spec records "no grader" as a warned failure in its trade-off table, yet offers "no grader" as a working option.
• D1's rule says each run records its instructions; event-triggered runs record none.
• RR1b (a real Slack app) names no agent-owned page or ticket, which RR1's own rule requires.

🤖 Generated with Claude Code

[Carr1005]

Decision Ledger for review: loop-engineering

A plain-language version of the spec's Decision Ledger, for review. Each heading links to its row in this PR's spec.md.

How to read it. Before building, the build agent asks the learner one question per decision below. Each table lists the answers they can pick.

• ✅ Recommended: what the default build uses (chosen when the spec was written, not tailored to the learner).
• 📘 Course used: what the course itself did.
• If chosen: what the build leaves out or changes. "—" means nothing.

Some questions are asked only after a certain earlier answer; they say so.

---

L1 · What the agent reviews

The learner is asked: what kind of document should the agent review? Why it's a choice: the default is the course's example; swapping it means rewriting the instructions, report sections and grading for your kind of document.

Ref	Option	Setup	Labels	If chosen
L1a	A requirements review agent that turns a raw software requirement into a structured review report	None	✅ 📘	—
L1b	A review agent for another kind of document you name, on the same design	None		A second setup for your kind of document is added, checked only by the live tests on your documents

L2 · Which documents it reviews

The learner is asked: which documents should the agent review, and where do they come from? Why it's a choice: your own documents feed only the live runs you start; the tests stay on the spec's examples, so they pass on day one.

Ref	Option	Setup	Labels	If chosen
L2a	The spec's invented requirement documents, served by ticket number from a local fake issue tracker	None	✅ 📘	—
L2b	Your own requirement documents, loaded into the local fake tracker from a folder you name	Your files		The live tests run on a ticket from your folder

L3 · What a finished review contains

The learner is asked: what sections should a finished review report have? Why it's a choice: new sections need new instructions and grading checks, and in the course a fresh batch run before the learning loop can compare versions.

Ref	Option	Setup	Labels	If chosen
L3a	A five-section report: confirmed facts; unclear points, each quoting its clause with why it is unclear, what would settle it and what could go wrong in production; questions to ask; assumptions; a short summary	None	✅ 📘	—
L3b	Your own report sections and checks for the documents you review	None		Your sections and checks are added as a second setup, checked only by the live tests; the offline tests keep the five sections

L4 · Which AI model provider, for live runs

The learner is asked: which model provider should the agent use for live runs? Why it's a choice: Lesson 2 matches a model's strength to the task's difficulty; a different provider may need the instructions re-tuned.

Ref	Option	Setup	Labels	If chosen
L4a	OpenAI	A paid OpenAI API key (live runs only)	✅ 📘	—
L4b	Anthropic	A paid Anthropic API key (live runs only)		The live tests run against Anthropic; its connector package is added
L4c	A local model server (Ollama) on your machine, with no key	Heavy: a large model download that supports tool calling		The live tests run against the local server; no provider key is checked

L5 · Where it runs

The learner is asked: where should the app run? Why it's a choice: a container adds an image build and a shared data folder; the tests are unchanged.

Ref	Option	Setup	Labels	If chosen
L5a	Your local machine with Python 3.12 or newer, files on local disk	None	✅ 📘	—
L5b	The same app in a container on your machine	None stated		Commands run inside the container; the restart test restarts the container on the same data folder

L6 · What this build leaves out

The learner is asked: here is everything this build does not include; keep it, or bring something back? (The question shows the full list.) Why it's a choice: each item's note says whether it can come back, and with or without tests.

Ref	Option	Setup	Labels	If chosen
L6a	Keep everything left out as listed	None	✅	—
L6b	Bring one or more listed items back, named in your answer	Per item		Each item is built as its note in the list allows

D1 · Where the agent's instructions live

The learner is asked: where should the reviewing agent's instructions be kept? Why it's a choice: Lesson 3 weighs three places: a system prompt fixed at creation, an always-loaded file that can change but costs space on every call, and a skill read only when needed.

Ref	Option	Setup	Labels	If chosen
D1a	An always-loaded instructions file (AGENTS.md), read into every run, that the agent cannot change	None	✅ 📘	—
D1b	The steps in the always-loaded file, and the review guidance in a skill (a file whose short description is always loaded and whose body the agent reads only when needed); shown in the course on a different agent	None		Each review takes one more step to read the skill
D1c	All instructions in the system prompt, fixed when the agent is created	None		The instructions are no longer a file in the agent's workspace; changes apply when the agent is next created

D2 · How the finished report is checked

The learner is asked: what should check the agent's report before the run counts as done? Why it's a choice: Lesson 5 says nothing in the basic agent loop checks that the report is good enough; checking costs a grader call per attempt.

Ref	Option	Setup	Labels	If chosen
D2a	An AI grader marks each grading point pass or fail and sends failures back as feedback for another attempt	None	✅ 📘	—
D2b	A code grader: code checks each grading point and sends failures back as feedback	None	never built by the course; the spec gives no tests for it	Code checks the build defines replace the AI grader; 15 tests no longer apply
D2c	A person marks each grading point pass or fail and writes the feedback	None	never built by the course; the spec gives no tests for it	A person replaces the AI grader; 21 tests no longer apply
D2d	No grader: the run ends when the agent says it is done	None		Leaves out checking the report; runs are marked not graded; 21 tests no longer apply. Skips 1 later question (D4)

D3 · What starts a review

The learner is asked: what should start a review? Why it's a choice: Lesson 6 argues that starting each review by hand adds steps people skip; events also respond when a requirement changes.

Ref	Option	Setup	Labels	If chosen
D3a	Events: creating a ticket, or saving a new version of a requirement an open ticket links to, starts a review automatically	None	✅ 📘	—
D3b	Manual start only: a person runs each review from the command line	None		Leaves out automatic starts and the local tracker app; 9 tests no longer apply. Skips 1 later question (RR1)
D3c	A schedule: a timer re-reviews open tickets	None	never built by the course; the spec gives no tests for it	A timer replaces ticket creation as the start; you name how often it runs; 6 tests no longer apply

D4 · Whether the agent improves over time

Asked only if D2 = D2a, D2b or D2c. The learner is asked: should the agent learn from past runs, or treat each run on its own? Why it's a choice: Lesson 7 says checking fixes one run at a time, so a new document repeats old mistakes; learning costs two batches of five documents and one call to a stronger model.

Ref	Option	Setup	Labels	If chosen
D4a	A learning loop: run a batch of documents, an analyst agent proposes one instruction change from feedback that recurs, a person approves it, code applies it, and the batch is re-run and compared	None	✅ 📘	—
D4b	No learning loop: each run is checked on its own and nothing carries over	None		Leaves out the learning loop and the run history; 12 tests no longer apply

RR1 · Where requests come from and reports go

Asked only if D3 = D3a or D3c. The learner is asked: where should review requests come from, and where should the report be written back? Why it's a choice: Lesson 6 showed real Slack, Jira and Confluence, but the course's shipped code is a simulated app.

Ref	Option	Setup	Labels	If chosen
RR1a	A local web app that simulates an issue tracker and a wiki; no key, and the course ships it	None	✅ 📘	—
RR1b	A real Slack app the team messages to ask for a review	Heavy: a Slack workspace where you can install an app, and two Slack tokens	shown in the course, no code shipped	Adds a live Slack check; the offline tests still use the simulated tracker
RR1c	Real Jira and Confluence Cloud, connected by automation rules	Heavy: an Atlassian Cloud site, an API token, automation rules and a public tunnel to your machine	shown in the course, no code shipped	Adds a live Jira/Confluence check; the offline tests still use the simulated tracker

RR2 · Which model the tests run against

The learner is asked: should the tests use a scripted fake model or the live one? Why it's a choice: a scripted model makes every test repeatable; the course warned that live models do not always give the same results.

Ref	Option	Setup	Labels	If chosen
RR2a	A scripted fake model: written, repeatable answers for every model role, not a real language model	None	✅	—
RR2b	The live provider chosen in L4, with the course's own model for each role	A paid API key	📘	Most remaining tests run live and check only the shape of answers; 9 tests no longer apply

---

Known open points (already flagged; tracked on #48)

1. D2d (no grader) is offered as a working choice, but the spec's own list of failures names "no grader" as a failure. It's open which of the two it should be.
2. D1's rule says each run records its instructions as one versioned text, but runs started by events record none.
3. RR1b (Slack app) names no page or ticket that belongs to the agent, which RR1's own rule requires.

Reviewers: comment with the Ref (for example "D2d: …").