Discussion: a QEP for work-plan tracking issues — genres, the body/comment discipline, and succession

[mmcky]

Per QEP-1, this is the optional discussion issue preceding a draft proposal. The question: should the org's work-plan tracking-issue practice be formalised as a QEP?

The practice exists; the convention doesn't

A search for work plan across the org's issues returns ~45 issues in 15 repositories. The recent ones are strikingly consistent in discipline and completely inconsistent in form. Four genres are tangled under one phrase:

Genre	What it is	Exemplars
Long-lived tracker	a state register for a project's duration; revised, never session-closed	QuantEcon/workspace-lectures#14, QuantEcon/QuantEcon.py#925, QuantEcon/skills#25
Period plan	disposable, scoped to a session or week, chained: closes with a ledger, succeeded by a plan built from the carry-forward register	the QuantEcon/project-translation session chain (issues 17 through 37), the QuantEcon/workspace-lectures weekly series (issues 23 through 50)
Handoff record	a separate "what happened" issue alongside the forward plan	QuantEcon/action-translation#114 — a dying genre, now folded into the plan's comments
Work package	a triage's output as a family of scoped issues	QuantEcon/action-translation#257 with its W0–W6 family (issues 258 through 264)

The discipline the recent issues share, nowhere written down: the body is the single source of truth for current state, revised in place, stamping its own revision date; comments are revision logs recording what changed and why, especially premises that inverted; claims are re-verified against live state, never carried forward; a period plan closes with a ledger and its successor is built from the register, never by copying the old body; and the chained repos keep exactly one open period plan at a time, which is what makes "resume the session" unambiguous.

What varies with no stated reason: six title conventions (Work plan —, TRACKING:, PLAN:, PROJECT:, W1 —, Session handoff), scoping (per-session vs per-week vs per-track), and labelling (all plan issues are currently untyped; QuantEcon/skills#25 explicitly defers to "a QuantEcon/qeps field report on plan/tracking issues", which does not yet exist).

Why a QEP

By QEP-1's own test this is QEP territory: the practice crosses repositories and changes how the team works. It also now has an operator: the qe plugin's workplan-* skill family in QuantEcon/skills (workplan-project, workplan-issue, workplan-update) encodes the observed practice, with the convention text currently held in one SKILL.md pending an upstream home. Per that repo's single-source-of-truth principle, the convention should be authored here and pointed to from there — the same relationship the style guide has to the check-style skills.

What the QEP would settle

1. The two live genres (tracker vs period plan), their lifecycles, and when to use which.
2. The body/comment discipline above, stated normatively.
3. One title form per genre.
4. The one-open-period-plan-per-repo invariant.
5. The QEP-2 question TRACKING: work plan from 2026-07-29 — run 2 against meta, and the block-2 judgement calls skills#25 left open: whether plan/tracking issues carry a type label (the field evidence so far says untyped).
6. Succession and closing-ledger rules.

Suggested path

Run the skill family for a few sessions first and let field experience shape the draft — the skills are new (see QuantEcon/skills#47) and their runs will surface what the convention gets wrong. Then draft the QEP from the evidence above plus those field reports.

[mmcky]

Note: I think this belongs in skills and does NOT require a QEP. I will leave this open for visibility but I propose we close this and leave it to skills.

[mmcky]

Ruled 2026-08-23, at the projects dashboard's architecture review (QuantEcon/status-projects#9 — private repo; public site at https://quantecon.github.io/status-projects/): split this discussion in two.

The practice — the genres, the body/comment discipline, one open period plan per repo, succession and the closing ledger — stays in the qe skills, as noted above. No QEP for that half.

The interface is different now: the dashboard's collector reads every registered project tracker nightly, so the tracker has a machine consumer and three producer classes (people, the skills, and a future maintenance agent). That half gets a one-page QEP defining only the unit: a Project is one tracker issue whose work items are native sub-issues (progress is measured on direct children, never deeper); it carries a machine-readable status stamp in one fixed form; and it carries the native Project issue type — an org issue type, not a label, so QEP-2 is untouched and the gap in #11 is answered without a tracking label. Programme-level trackers (programme → project → items) are deliberately outside it; whether that layer is structure or a venue is deferred to status-projects#10.

Evidence the draft will be written from, measured 2026-08-23 across 99 tracker-shaped open issues org-wide: 13 title conventions (the commonest covers 23%); 92% carry no issue type; 60% have no sub-issues and track work by checkboxes or prose; 8 carry a status stamp, in three different forms; 14 of 34 sub-issue parents are themselves children; 24 parent→child links cross repos; 0 trackers use dependencies. Per #14 the QEP is field-tested in Draft: a tracker-conform skill (QuantEcon/skills#49) brings the registered trackers into the layout, and the collector reports compliance nightly. Drafting waits until the collector has a month of data, so the spec is written from what it actually sees rather than before it.

[mmcky]

A fourth question for the one-page QEP: does the unit express order?

The 2026-08-23 ruling above scopes the QEP to the unit — one tracker issue, work items as native sub-issues one level down, a machine-readable status stamp, and the native Project issue type. That answers membership (which issues are the work), progress (how many are done), freshness (the stamp) and type. It does not answer order, and the question has now arrived from the field rather than from theory.

QuantEcon/textstrata#8 is the first work plan to reach for milestones to supply it, and QuantEcon/skills#55 proposes generalising that as a wp{issue}-stage{n} naming convention. I reviewed the first instance in detail on that issue; the finding relevant here is that milestones group but do not order. In textstrata the three wp8-stage* milestones mirror QuantEcon/project-translation#49's programme stages, while the plan's own sequencing is Phase 0–5 — the two axes cut across each other, and wp8-stage1 is four issues spanning three phases in no stated order. The audit finding those milestones were meant to close named two things, the stage structure and the inter-issue dependencies; only the first was encoded. The dependencies remain prose.

Why I think the QEP should rule order explicitly out of the unit

Not because it does not matter, but because of a constraint the ruling did not have in front of it — and the existing contract has already made the relevant call once, which is the strongest evidence available.

The only carriers anyone has proposed for order are issue titles and milestone names. Both are repository content, and the published data contract treats content and quantity differently by design. Progress survives redaction because it is a pair of integers. The stamp survives because it is a date. A milestone, where a tracker has one, survives as its due date and progress percent with the title stripped — the numbers are kept, the name is dropped, because a milestone title is repository content (schema/latest.schema.json, collector/collect.py; private repo, so these will 404 for non-members — the behaviour is visible on the public dashboard, where one project's milestone shows as a bare 38% with no title).

That is the precedent. The contract has already decided that a milestone's quantity is publishable and its name is not. A convention that encodes ordering in the name is therefore proposing a field the machine consumer can only read for public repositories. Titles fail the same test harder: a private tracker publishes no child list at all, not even its public children, because the parent-to-child edge is itself a fact held in the private repository. Of the 28 registered projects, 12 are in that class.

So order cannot be an observable property of the unit in the way progress and the stamp are. A spec that made it one would be defining a half-observable field — exactly what the unit spec is trying to avoid.

That argues for one normative sentence rather than silence: the unit does not carry sequence; sequencing lives in the tracker body's plan table, which is the authority. That is already the observed practice — QuantEcon/textstrata#8's plan table and Sequencing paragraph are the real order, and the milestones are a partial shadow of it. Stating it stops the next repo inventing a third mechanism, without committing the machine consumer to reading one.

The one exception worth naming

The ruling's own evidence line — "0 trackers use dependencies" across 99 tracker-shaped issues — is the most actionable zero in that list. GitHub's issue dependencies are native, machine-readable, and survive redaction as a count rather than as prose, which is precisely the property titles and milestone names lack. They are already read nightly by the collector and published as an open-blocker count. They express #2 → #1 exactly, which is the relationship textstrata's audit wrote in a paragraph.

I would still keep them optional. A dependency is a constraint (a partial order), not a presentation order, and it is a heavier edit than a plan-table row. But "where a sequencing constraint is real, express it as a dependency rather than as prose" is a defensible normative line, it is the only ordering statement that behaves like the unit's other three fields, and it costs the spec nothing.

Where the naming convention itself belongs

wp{issue}-stage{n} is not QEP-2 territory (that governs labels) and, on the reading above, not unit-spec territory either — so it currently has no home. Consistent with the 2026-08-23 split, it belongs with the practice in the qe skills, and that is where it is being worked at QuantEcon/skills#55.

Two notes for whoever picks it up there. First, a milestone token stage1 collides with stage as the projects registry already uses it — the declared lifecycle column, idea through dropped, that the public pipeline view is built on; phase avoids the collision and matches the plan tables people actually write. Second, adoption would be greenfield: only 3 of the 28 registered trackers carry a milestone at all today, and all three are descriptive names for a body of work rather than structural tokens. Nothing has to be migrated, but nothing existing endorses the structural reading either.

Suggested addition to the draft's scope list

One line under what the QEP settles: whether the unit expresses sequence, and if not, where sequence lives. My recommendation is the answer above — it does not, the body's plan table is the authority, and a genuine constraint may be expressed as a native dependency. Cheap to state, grounded in a call the data contract has already made, and it closes the question that produced the first ad hoc convention.

[mmcky]

Field evidence for the ordering question, from a live tracker

A first real run of /qe:workplan update against QuantEcon/quantecon-theme.mystmd#147 produced a data point bearing on the fourth question above — does the unit express order?

Measured against the unit as scoped by the 2026-08-23 ruling, that tracker conforms structurally and fails on exactly the machine-readable half: 9 native sub-issues one level down and a single tracker per project, but no Project issue type (untyped, and unlabelled) and a stamp that is human prose only. The Project type is already available at both org and repo level, so that half is a mechanical fix rather than a blocker.

On order specifically: it is load-bearing, and a linear order is not sufficient. #147 does express order, entirely in prose — the body opens with a "Next session — resume here" section naming which sub-issue leads and why. That section had to be added precisely because the sub-issue list could not convey it, and because the existing prose said what could run in parallel, which is not the same as what to start.

The remaining six sub-issues have a genuine dependency structure that no sequence captures: one pair must ship together, two are independent and can run concurrently, one is a decision with no implementation attached. So the honest shape is a partial order, not a ranking. Encoding "next" is easy; encoding "these two are independent" is not, and a mechanism that only offers the former would push authors back into prose for the rest — which is where it already lives.

Worth weighing before the QEP fixes a mechanism. I have opened #17 for the compliance review that should follow the QEP, which carries the full measurement of #147, and QuantEcon/skills#68 for the two skill-side gaps the same run surfaced (the resume pointer has no named home in the body, and the long-lived tracker genre has no body spec).