workplan-project: plan order is never stated, and the re-run path appends out of position #70

From the QEP-6 field test (QuantEcon/qeps#19). Companion to #69.

Order is QEP-6's central thesis — the sub-issue list is the plan, top open item is next, completed items keep their place, phase groups contiguous. workplan-project never mentions it: not plan order, not list position, not reprioritize.

A first run is correct by accident

Step 5 creates each sub-issue from NN-<slug>.md in draft order and links each in the same order, and the sub-issue API appends. So a clean first run does produce plan order — but nothing in the skill says that is the invariant, which means nothing protects it. Two paths already break it:

1. The documented re-run. The "Re-runs are safe if you look first" rule files only what is missing:

before each create, gh issue list --repo <o>/<r> --search "<title> in:title" — file only what is missing, and edit rather than duplicate.

A missing item is then created and linked, which appends it to the bottom regardless of which phase it belongs to. A phase-2 item recovered on a re-run lands after phase 4. That breaks §2's contiguity requirement and §4's "phase order shows as contiguity in the list", and it does so silently — the tracker still looks fine, it just no longer states the plan.

2. Re-planning. Adoption clause 3 requires the qe skills to "create sub-issues in plan position, reprioritize on re-plan, and refresh the stamp section, Next: line, and list position as one atomic update." None of that is in the skill.

The mechanism

Reorder is the one sub-issue operation with no gh verb at all — a repo-wide grep for reprioriti|after_id|before_id across cli/cli returns zero matches. It is gh api only:

gh api --method PATCH repos/<o>/<r>/issues/<parent>/sub_issues/priority \
  -F sub_issue_id="$id" -F after_id="$prev_id"

with the trap the skill's Gotchas already name for a different call: the parent is an issue number in the path while the children are database IDs in the body, both bare integers, indistinguishable to the API if transposed.

Verified in the field test: a reprioritize write is reflected in the list read-back, and REST, GraphQL and the rendered UI all return the same order. The mechanism is sound; it simply isn't used here.

Where the database-id lookup actually belongs

The skill currently pays that cost on the common path. Step 5.4 and the first Gotcha are both built around resolving sub_issue_id:

id=$(gh api repos/<o>/<r>/issues/<child-number> --jq .id)
gh api repos/<o>/<r>/issues/<parent-number>/sub_issues -F sub_issue_id="$id"

Since gh v2.94.0 this is unnecessary for linking: gh issue edit <parent> --add-sub-issue <number> takes plain issue numbers. Confirmed in the field test on the sibling verb — --add-blocked-by accepted plain numbers and the database-id fallback was never reached.

So the two changes are one change:

• Linking → native verb, plain numbers, no lookup.
• Reordering → gh api, database IDs, which is where that gotcha genuinely lives.

Net effect: the doc's one scary footgun moves off every link and onto the single operation that actually requires it, and the batch form off /sub_issues gets the IDs for a whole tracker in one call rather than one per child.

Proposed change

1. State the invariant in step 4: the draft file order is the plan order, and NN- prefixes are draft filenames only — never issue titles (§2 bans sequence tokens in titles outright).
2. Step 5 links with gh issue edit <parent> --add-sub-issue <number>, in draft order.
3. On a re-run, place by position rather than appending: resolve the intended predecessor and PATCH …/sub_issues/priority with after_id.
4. Add a step-5 read-back assertion that the list order matches the draft order, alongside the existing stamp check.

Acceptance

• The plan-order invariant is stated, not implied by file naming
• Linking uses the native verb; no database-id lookup on the common path
• A re-run that files a missing item places it in position, and this is tested at least once
• The reorder call, with its issue-number-vs-database-id trap, is the only place the lookup appears

Note

Until QuantEcon/status-projects#19 ships, the dashboard re-sorts published children ascending by issue number, so a tracker conforming to this and one ignoring it publish identically. That does not block this change — the list is right on GitHub either way — but it does mean the fix cannot be verified through the dashboard yet.