Summary
The work-package workflow is the one that carries a single piece of work from inception to a merged pull request, or a review from inception to a posted review. It is the busiest definition in the corpus — sixteen activities, thirty-five bindings into the code knowledge graph, and the workflow every other one borrows from.
This initiative collects refinements to it that are too large to sit inside another epic's work item, and whose scope has to be settled before they can be estimated. It opens with one, migrated from the phase that could not size it.
The first item, and why it moved
W1 — Compound comprehension across runs instead of rebuilding it.
When the workflow needs to understand a part of a codebase, it writes what it learned into one file per area inside that run's planning folder. The next run over the same area starts again. A wiki already exists as a separate workflow, built to hold exactly this kind of durable, citation-backed knowledge across sessions, and the intent is for comprehension to write there instead.
Half of that is already done. Comprehension was split some time ago into a durable reference written to a cumulative corpus outside any one session, and a session-local log holding the questions, investigations and follow-ups. The operation carries a step promoting settled outcomes from the second into the first, and the activity's declared outcomes name both.
The other half was sized at five to eight agent hours on the understanding that it binds wiki operations that already exist. They do exist. They are not bindable as they stand, and the reasons were found by reading the definitions rather than the estimate:
The wiki's ingest operation reads two values that are not its inputs — the path the wiki lives at, and the pinned commit its citations are anchored to. Both are declared as workflow-level variables of the wiki workflow, so any borrowing workflow has to supply them. The wiki's own build stage opens by refusing to proceed unless a scope has been confirmed and a baseline commit pinned. The work-package workflow declares neither value anywhere.
The comprehension artifact is not private to comprehension. It is a declared input or output on four other operations — the convergence loop and its analyse, challenge and combine parts — and a fifth writes into it: assumption reconciliation appends findings as a numbered deep-dive section and updates an open-questions table inside the same file, and skips that phase entirely when no artifact was supplied.
A single file never had to answer which page a later activity appends to. A set of typed wiki pages does. So the change reaches the input and output contract of five operations across two stages, and the reconciliation step needs an answer to a question it does not currently ask. That is what the phrase "downstream activities receive equivalent inputs" is standing on, and it is the bulk of the work rather than a detail of it.
What has to be settled first
Three decisions, written before any binding is applied:
- Whether the work-package workflow pins a citation baseline at all, and to what.
- Whether it takes on the wiki's scope-confirmation stage, or the wiki operations gain a path for a caller that seeds its scope directly.
- What the assumption-reconciliation step appends to, once there is no single file.
The shape to follow is the one used by the fan-out item in the phase this migrated from, where a written decision preceded the work.
Why now is cheap
The investigation is done and does not need retaking: the blocking reads, the five operations that share the artifact, and the one that writes into it were each established against the corpus as it stands. The delivered half is real and stays delivered. And the cost of leaving it is the thing the item exists to remove — every run over an area already understood pays to understand it again.
Scope
The work-package workflow's comprehension and assumption-reconciliation stages, and whatever contract the wiki operations need in order to serve a caller that is not the wiki workflow. No change to what comprehension concludes, only to where it is written and how it is read back.
Further refinements to this workflow join here as they are identified. The initiative is the home for them; it is not a claim that more are queued.
Acceptance criteria
Non-goals
- Re-deciding the knowledge and metadata split. It is delivered and it stays.
- Changing what comprehension concludes. This moves where knowledge lives and how it is read back, not the reasoning that produces it.
- Rebuilding the wiki workflow. Where the wiki operations need a contract for an external caller, that is a contract addition rather than a redesign.
Tracking
|
Work item |
Agent time |
State |
| [ ] |
W1 — compound comprehension across runs instead of rebuilding it |
Re-scope first; the three decisions above bound the estimate |
Open. Migrated from I1 P3 W3, where the split half is delivered |
|
Initiative total |
Not estimated until W1 is re-scoped |
|
Item hours and effort-days carry the definitions given in #540.
Investigation detail
The premise check that established why the operations are not bindable as they stand, and the three decisions it produced, is recorded on the phase this migrated from: #539.
The fan-out survey and the reuse breaches that originally framed the item: 2026-08-18-optimisation-of-meta-and-work-package-workflows.
Summary
The work-package workflow is the one that carries a single piece of work from inception to a merged pull request, or a review from inception to a posted review. It is the busiest definition in the corpus — sixteen activities, thirty-five bindings into the code knowledge graph, and the workflow every other one borrows from.
This initiative collects refinements to it that are too large to sit inside another epic's work item, and whose scope has to be settled before they can be estimated. It opens with one, migrated from the phase that could not size it.
The first item, and why it moved
W1 — Compound comprehension across runs instead of rebuilding it.
When the workflow needs to understand a part of a codebase, it writes what it learned into one file per area inside that run's planning folder. The next run over the same area starts again. A wiki already exists as a separate workflow, built to hold exactly this kind of durable, citation-backed knowledge across sessions, and the intent is for comprehension to write there instead.
Half of that is already done. Comprehension was split some time ago into a durable reference written to a cumulative corpus outside any one session, and a session-local log holding the questions, investigations and follow-ups. The operation carries a step promoting settled outcomes from the second into the first, and the activity's declared outcomes name both.
The other half was sized at five to eight agent hours on the understanding that it binds wiki operations that already exist. They do exist. They are not bindable as they stand, and the reasons were found by reading the definitions rather than the estimate:
The wiki's ingest operation reads two values that are not its inputs — the path the wiki lives at, and the pinned commit its citations are anchored to. Both are declared as workflow-level variables of the wiki workflow, so any borrowing workflow has to supply them. The wiki's own build stage opens by refusing to proceed unless a scope has been confirmed and a baseline commit pinned. The work-package workflow declares neither value anywhere.
The comprehension artifact is not private to comprehension. It is a declared input or output on four other operations — the convergence loop and its analyse, challenge and combine parts — and a fifth writes into it: assumption reconciliation appends findings as a numbered deep-dive section and updates an open-questions table inside the same file, and skips that phase entirely when no artifact was supplied.
A single file never had to answer which page a later activity appends to. A set of typed wiki pages does. So the change reaches the input and output contract of five operations across two stages, and the reconciliation step needs an answer to a question it does not currently ask. That is what the phrase "downstream activities receive equivalent inputs" is standing on, and it is the bulk of the work rather than a detail of it.
What has to be settled first
Three decisions, written before any binding is applied:
The shape to follow is the one used by the fan-out item in the phase this migrated from, where a written decision preceded the work.
Why now is cheap
The investigation is done and does not need retaking: the blocking reads, the five operations that share the artifact, and the one that writes into it were each established against the corpus as it stands. The delivered half is real and stays delivered. And the cost of leaving it is the thing the item exists to remove — every run over an area already understood pays to understand it again.
Scope
The work-package workflow's comprehension and assumption-reconciliation stages, and whatever contract the wiki operations need in order to serve a caller that is not the wiki workflow. No change to what comprehension concludes, only to where it is written and how it is read back.
Further refinements to this workflow join here as they are identified. The initiative is the home for them; it is not a claim that more are queued.
Acceptance criteria
Non-goals
Tracking
Item hours and effort-days carry the definitions given in #540.
Investigation detail
The premise check that established why the operations are not bindable as they stand, and the three decisions it produced, is recorded on the phase this migrated from: #539.
The fan-out survey and the reuse breaches that originally framed the item: 2026-08-18-optimisation-of-meta-and-work-package-workflows.