Module 25 - Sort Prerequsites #100

New Issue

2026-06-23T09:28:47-04:00

justin commented

2026-06-23 09:28:47 -04:00

Check all modules, but i spot checked module 25 and the prereq's section bounces all over the place. We should organize them numerically lowest to highest unless there is a really good reason not to.

Build scope (AI-ready)

Problem

Each module's README.md has a ## Prerequisites section: a bullet list where every bullet names a prior module the module depends on. In several modules the bullets are ordered by pedagogical importance ("most load-bearing first") or essentially at random, so the module numbers jump around (e.g. Module 25 lists 24 → 9 → 6 → 10/11 → 13/14 → 15 → 19 → 12 → 5 → 16/17/22). The ask: reorder each Prerequisites list numerically, lowest module number first, unless a specific bullet has a genuinely good reason to lead.

This is editorial/documentation only — markdown prose. No code, no behavior change. The dependency chain is preserved automatically: per AGENTS.md ("A module may assume only what precedes it"), every prerequisite already references a lower-numbered module, so a numeric ascending sort never creates a forward reference.

Affected files / areas

All under modules/*/README.md, only the ## Prerequisites section of each. An audit of all 27 modules found 9 modules out of numeric order that need fixing. The other 18 are already ascending (or have only one/zero prereqs) and should be left alone.

Modules to reorder (current order → target ascending order; multi-module bullets like "Modules 10 and 11" sort by their lowest number; a trailing "Helpful but not required" group stays last and is sorted within itself):

modules/07-worktrees-running-agents-in-parallel/README.md — currently 6, 4, 2, 1 → 2, 4, 6. (Closing "If you parachuted in…" paragraph stays after the list.)
modules/09-issues-and-the-task-layer/README.md — currently 8, 5, 2, 1 → 1, 2, 5, 8. (Closing "You do not yet need…" paragraph stays last.)
modules/14-continuous-integration/README.md — currently 8, 13, 2 → 2, 8, 13.
modules/15-security-scanning/README.md — main list currently 14, 2, 1 → 1, 2, 14. "Helpful but not required" group (8, 10) is already ascending; keep it as the trailing group.
modules/22-securing-third-party-mcp-and-skills/README.md — main list currently 20, 21, 15, 2 → 2, 15, 20, 21. "Helpful but not required" group (16, 17, 5) → sort to 5, 16, 17.
modules/24-assistive-agents/README.md — main list currently 9, 10, 5, 22 → 5, 9, 10, 22. "Helpful but not required" group (13, 14, 15, 19, 20–21) is already ascending; keep it trailing.
modules/25-autonomous-agents/README.md — currently 24, 9, 6, 10/11, 13/14, 15, 19, 12, 5, 16/17/22 → 5, 6, 9, 10/11, 12, 13/14, 15, 16/17/22, 19, 24. (Intro sentence "This is the module the whole back half…" and the closing "If you skipped straight here…" paragraph both stay; only the bullets move.)
modules/26-orchestrating-multiple-agents/README.md — currently 7, 25, 11, 10, 9, 14, 8, then a combined "Modules 2, 5, 6" bullet → 2/5/6, 7, 8, 9, 10, 11, 14, 25 (the "Modules 2, 5, 6" bullet sorts first by its lowest number, 2). (Closing "If you parachuted in…" paragraph stays last.)
modules/27-evals/README.md — currently 1, 13, 14, 10, 24–26 → 1, 10, 13/14, 24–26. (Note 13 and 14 are separate bullets here; sort them 13 then 14. Intro "This is the closer…" sentence stays.)

Recommended approach

For each of the 9 modules above, reorder only the - bullets inside ## Prerequisites. Move each bullet's full explanatory prose with it — every bullet is "Module N: " and the prose travels with the number. Do not rewrite the prose.
Keep any non-bullet content in place: an intro sentence before the bullets, a "Helpful but not required" sub-group (keep it as the last group, sorted ascending within itself — being optional is the "really good reason" it trails the required list), and any closing paragraph after the list.
Sort key = the lowest module number a bullet references. Combined bullets ("Modules 10 and 11", "Modules 2, 5, 6", "Modules 24–26") keep their grouping and sort by their lowest number.
Watch prose that references a module by name rather than by list position (e.g. M04's "Module 2: this is the load-bearing prerequisite", M21's "Module 5, the one this builds on directly", M25's "the rest of this list"). These read fine after reordering because they name the module, not its slot — but re-read each moved bullet to confirm no sentence depends on being first/last. If one truly does, that bullet is a candidate for the "really good reason" exception: leave it and note why in the PR.
De-slop / house style: this repo is em-dash-free and avoids banned words (see recent commits #94–#98 and AGENTS.md). Reordering shouldn't introduce any, but don't add any new em-dashes or slop while editing.

"Really good reason not to" — judgement calls

The issue explicitly allows exceptions. The recurring pattern is a list that deliberately leads with the immediate-predecessor / most load-bearing module (M07 leads with M6 "this module makes no sense without it"; M25 leads with M24 the escalation; M26 leads with M7 "the primitive everything here rests on"). Default to numeric per the issue, since each bullet's prose already carries its own importance and survives reordering. Only preserve a non-numeric lead if a bullet's wording genuinely breaks when moved — call those out explicitly in the PR description rather than deciding silently (AGENTS.md: "If you think something should move, flag it; don't silently reorder").

Acceptance criteria / how to verify

All 9 listed modules have Prerequisites bullets in ascending numeric order (by lowest referenced module number); any "Helpful but not required" group trails the required list and is itself ascending.
The 18 unmodified modules are untouched.
No prose content changed beyond bullet ordering; no bullets dropped or added; intro/closing paragraphs intact.
No em-dashes or banned words introduced.
Spot-check render: git diff shows only reordered bullet blocks within Prerequisites sections.
Optional sanity build of the wiki to confirm nothing broke: python tools/build_wiki.py (it only concatenates modules in reading order; it does not parse prerequisite ordering, so it should pass unchanged).
No test suite exists for content; verification is the diff review above.

Target surface(s)

Markdown only: 9 modules/*/README.md files (modules 7, 9, 14, 15, 22, 24, 25, 26, 27). No code, config, or wiki-generator changes.

Stop-lines

Do not touch any module already in ascending order (1, 2, 3, 4, 5, 6, 8, 10, 11, 12, 13, 16, 17, 18, 19, 20, 21, 23).
Do not rewrite, shorten, or "improve" the explanatory prose on any bullet — reorder only.
Do not change which modules are listed as prerequisites (no adding/removing dependencies), and do not reorder the modules themselves or the syllabus — only the bullets within each Prerequisites section.
Do not edit the-workflow-syllabus.md, tools/build_wiki.py, AGENTS.md, or _TEMPLATE.md.
If a bullet's wording genuinely depends on its position, leave it and flag it in the PR rather than forcing the sort.

Check all modules, but i spot checked module 25 and the prereq's section bounces all over the place. We should organize them numerically lowest to highest unless there is a really good reason not to. ## Build scope (AI-ready) ### Problem Each module's `README.md` has a `## Prerequisites` section: a bullet list where every bullet names a prior module the module depends on. In several modules the bullets are ordered by pedagogical importance ("most load-bearing first") or essentially at random, so the module numbers jump around (e.g. Module 25 lists 24 → 9 → 6 → 10/11 → 13/14 → 15 → 19 → 12 → 5 → 16/17/22). The ask: reorder each Prerequisites list **numerically, lowest module number first**, unless a specific bullet has a genuinely good reason to lead. This is editorial/documentation only — markdown prose. No code, no behavior change. The dependency chain is preserved automatically: per `AGENTS.md` ("A module may assume only what precedes it"), every prerequisite already references a *lower-numbered* module, so a numeric ascending sort never creates a forward reference. ### Affected files / areas All under `modules/*/README.md`, only the `## Prerequisites` section of each. An audit of all 27 modules found **9 modules out of numeric order** that need fixing. The other 18 are already ascending (or have only one/zero prereqs) and should be left alone. Modules to reorder (current order → target ascending order; multi-module bullets like "Modules 10 and 11" sort by their lowest number; a trailing "Helpful but not required" group stays last and is sorted within itself): - `modules/07-worktrees-running-agents-in-parallel/README.md` — currently 6, 4, 2, 1 → **2, 4, 6**. (Closing "If you parachuted in…" paragraph stays after the list.) - `modules/09-issues-and-the-task-layer/README.md` — currently 8, 5, 2, 1 → **1, 2, 5, 8**. (Closing "You do not yet need…" paragraph stays last.) - `modules/14-continuous-integration/README.md` — currently 8, 13, 2 → **2, 8, 13**. - `modules/15-security-scanning/README.md` — main list currently 14, 2, 1 → **1, 2, 14**. "Helpful but not required" group (8, 10) is already ascending; keep it as the trailing group. - `modules/22-securing-third-party-mcp-and-skills/README.md` — main list currently 20, 21, 15, 2 → **2, 15, 20, 21**. "Helpful but not required" group (16, 17, 5) → sort to **5, 16, 17**. - `modules/24-assistive-agents/README.md` — main list currently 9, 10, 5, 22 → **5, 9, 10, 22**. "Helpful but not required" group (13, 14, 15, 19, 20–21) is already ascending; keep it trailing. - `modules/25-autonomous-agents/README.md` — currently 24, 9, 6, 10/11, 13/14, 15, 19, 12, 5, 16/17/22 → **5, 6, 9, 10/11, 12, 13/14, 15, 16/17/22, 19, 24**. (Intro sentence "This is the module the whole back half…" and the closing "If you skipped straight here…" paragraph both stay; only the bullets move.) - `modules/26-orchestrating-multiple-agents/README.md` — currently 7, 25, 11, 10, 9, 14, 8, then a combined "Modules 2, 5, 6" bullet → **2/5/6, 7, 8, 9, 10, 11, 14, 25** (the "Modules 2, 5, 6" bullet sorts first by its lowest number, 2). (Closing "If you parachuted in…" paragraph stays last.) - `modules/27-evals/README.md` — currently 1, 13, 14, 10, 24–26 → **1, 10, 13/14, 24–26**. (Note 13 and 14 are separate bullets here; sort them 13 then 14. Intro "This is the closer…" sentence stays.) ### Recommended approach 1. For each of the 9 modules above, reorder only the `-` bullets inside `## Prerequisites`. **Move each bullet's full explanatory prose with it** — every bullet is "**Module N**: <why>" and the prose travels with the number. Do not rewrite the prose. 2. Keep any non-bullet content in place: an intro sentence before the bullets, a "Helpful but not required" sub-group (keep it as the *last* group, sorted ascending within itself — being optional is the "really good reason" it trails the required list), and any closing paragraph after the list. 3. Sort key = the **lowest** module number a bullet references. Combined bullets ("Modules 10 and 11", "Modules 2, 5, 6", "Modules 24–26") keep their grouping and sort by their lowest number. 4. Watch prose that references a module by name rather than by list position (e.g. M04's "Module 2: this is the load-bearing prerequisite", M21's "Module 5, the one this builds on directly", M25's "the rest of this list"). These read fine after reordering because they name the module, not its slot — but re-read each moved bullet to confirm no sentence depends on being first/last. If one truly does, that bullet is a candidate for the "really good reason" exception: leave it and note why in the PR. 5. **De-slop / house style:** this repo is em-dash-free and avoids banned words (see recent commits #94–#98 and `AGENTS.md`). Reordering shouldn't introduce any, but don't add any new em-dashes or slop while editing. ### "Really good reason not to" — judgement calls The issue explicitly allows exceptions. The recurring pattern is a list that *deliberately* leads with the immediate-predecessor / most load-bearing module (M07 leads with M6 "this module makes no sense without it"; M25 leads with M24 the escalation; M26 leads with M7 "the primitive everything here rests on"). Default to **numeric** per the issue, since each bullet's prose already carries its own importance and survives reordering. Only preserve a non-numeric lead if a bullet's wording genuinely breaks when moved — call those out explicitly in the PR description rather than deciding silently (`AGENTS.md`: "If you think something should move, flag it; don't silently reorder"). ### Acceptance criteria / how to verify - All 9 listed modules have Prerequisites bullets in ascending numeric order (by lowest referenced module number); any "Helpful but not required" group trails the required list and is itself ascending. - The 18 unmodified modules are untouched. - No prose content changed beyond bullet ordering; no bullets dropped or added; intro/closing paragraphs intact. - No em-dashes or banned words introduced. - Spot-check render: `git diff` shows only reordered bullet blocks within Prerequisites sections. - Optional sanity build of the wiki to confirm nothing broke: `python tools/build_wiki.py` (it only concatenates modules in reading order; it does not parse prerequisite ordering, so it should pass unchanged). - No test suite exists for content; verification is the diff review above. ### Target surface(s) Markdown only: 9 `modules/*/README.md` files (modules 7, 9, 14, 15, 22, 24, 25, 26, 27). No code, config, or wiki-generator changes. ### Stop-lines - **Do not** touch any module already in ascending order (1, 2, 3, 4, 5, 6, 8, 10, 11, 12, 13, 16, 17, 18, 19, 20, 21, 23). - **Do not** rewrite, shorten, or "improve" the explanatory prose on any bullet — reorder only. - **Do not** change which modules are listed as prerequisites (no adding/removing dependencies), and do not reorder the *modules themselves* or the syllabus — only the bullets within each Prerequisites section. - **Do not** edit `the-workflow-syllabus.md`, `tools/build_wiki.py`, `AGENTS.md`, or `_TEMPLATE.md`. - If a bullet's wording genuinely depends on its position, leave it and flag it in the PR rather than forcing the sort.

justin added the autopilot label 2026-06-23 09:28:47 -04:00

claude added the ai-ready label 2026-06-23 09:32:32 -04:00

claude referenced this issue from a commit

2026-06-23 09:49:18 -04:00

fix(autopilot): always reap finished scope-<n> worktrees

justin referenced a pull request that will close this issue

2026-06-23 09:53:34 -04:00

Module prereqs: sort Prerequisites lists numerically ascending #102

justin referenced this issue from a commit

2026-06-23 14:00:50 -04:00

docs: sort Prerequisites lists numerically ascending (#100)

justin closed this issue