---

name: audit-course-docs description: Audit course documentation for accuracy and narrative cohesion, and assemble the PR. Use when asked to audit/review exercise docs, or before opening any PR that touches */exercises/.

Audit course docs

The procedure that repeated shipped-then-corrected defects forced into existence. The expensive lesson underneath it: a wrong claim caught before commit is one edit; after push it is a correction commit plus a PR-body amendment. Front-load the checking.

Procedure

1. Scope the diff. Confirm it is docs-only — no behavioral change to any server.py / db.py / test file. (Comment/docstring fixes are fine but get their own clearly-labelled commit.) If user-authored commits are being extracted from a mixed branch, cherry-pick them intact and land corrections as separate commits on top.

2. Fan out one exercise-auditor agent per affected course (they are read-only; run them in parallel). Give each the exact commit/branch to audit and the course directory.

3. Verify before fixing. Reproduce every reported defect against the code yourself before editing. The standing example: "your server says no five times" looked like a miscount against eleven scope-checked functions — but SUPPORTED_SCOPES also has five entries and the sentence is narrative, not a count. An illustrative number is not a defect; "fixing" it introduces an error. Every finding that fails verification goes in the PR body under "checked and left alone" — reporting the non-fix is part of the audit.

4. Sequential read-through, pre-commit. Walk every forward pointer in course order and check each against the next lesson's actual task section (## Your task, ## What you're building, …). This is the gate that has caught what per-file review misses: adjacent blocks saying the same thing, pointers promising work the next lesson doesn't do, problem blocks echoing their solution twin.

5. Gates, per affected course, before push:

   make -C <course> test            # every solution suite green
   make -C <course> test-problems   # every problem stub still starts red
   

   test-problems is also the proof no coursework leaked into the stubs.

6. PR body contract:

   • Each correction: the exact old text quoted, the file:line of the code or test that contradicts it, what changed.
   • Checked and left alone: every suspected defect that verification cleared, with why.
   • Verification transcript (the two gate lines per course).
   • Observations that are not defects (pre-existing inconsistencies worth a separate change) go in the body, not the diff.

Commit shape

One commit for the additive narrative work, then one commit per accuracy defect, named for the defect — never bundled. Staging by name (story-commit rules apply). This keeps "what was authored" and "what the audit corrected" separately reviewable.