Repository navigation
feat(planning): restate every open item in full when async work lands mid-round #11888
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| bump: patch | ||
| --- | ||
|
|
||
| ### Changed | ||
|
|
||
| - `/discovery:research` and `/discovery:explore`: when dispatched work returns after open questions were shown and before the user answers, the next message that presents anything ends with every open question in full, per `docs/contracts/async-round-presentation/README.md` in the marketplace. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| bump: minor | ||
| --- | ||
|
|
||
| ### Changed | ||
|
|
||
| - `/planning:interview`: when a dispatched agent's or background task's output lands after a round was shown, the next message that presents a question ends with every open question in full, the changed one marked, in place of a one-line pointer for the untouched questions. Questions that do not wait on a pending result are still asked without waiting. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace. | ||
|
|
||
| ### Added | ||
|
|
||
| - Eval case `late-return-restates-every-open-question-in-full`. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| bump: patch | ||
| --- | ||
|
|
||
| ### Changed | ||
|
|
||
| - `/review:fanout`: when a surface returns after findings were presented for a decision and before the user answers, the next message that presents findings ends with every open finding in full, per `docs/contracts/async-round-presentation/README.md` in the marketplace. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # Async round presentation: the latest message holds every open item | ||
|
|
||
| A skill can show the user open items (questions, decisions, findings that wait on a choice) and | ||
| also dispatch async work: sub-agents, background tasks, lookups. That work can return after the | ||
| items are shown and before the user answers. This contract owns what the next message shows. | ||
|
|
||
| ## The rule | ||
|
|
||
| When a skill has presented open items and dispatched work returns before the user answers, the | ||
| next message that presents anything ends with one block that restates every open item in full: | ||
| the question, its options, and the recommendation with its basis. The block marks each item the | ||
| returned work changed. | ||
|
|
||
| - **An item that depends on a pending result may be held.** It stays out of the block until the | ||
| result lands; the block may name it in one line as waiting. | ||
| - **A status line while waiting is fine.** A message that only reports progress (a return touched | ||
| no open item, work is still running) presents nothing, so it needs no block. | ||
| - **A partial set is never the last word.** A message that shows the changed item in full and | ||
| points back to an earlier message for the rest breaks this rule. | ||
|
|
||
| ## Why | ||
|
|
||
| The user reads the latest message. A pointer to an earlier block makes them scroll back to | ||
| rebuild the open set, and with several returns that set spreads across several messages, so an | ||
| item can go unanswered because it was never in view. A full restate costs length; the cost of a | ||
| pointer is an answer given against a set the user could not see whole. | ||
|
|
||
| ## What this does not require | ||
|
|
||
| The rule does not hold a round until every dispatch drains. Items that do not depend on pending | ||
| work are still asked at once, so the session is not serialized behind its slowest lookup. Only | ||
| the items that need a pending result wait for it. | ||
|
|
||
| ## Who is bound | ||
|
|
||
| Any skill that presents open items for the user's answer while its own dispatched work can still | ||
| return. A bound skill cites this file by its repository path, `docs/contracts/async-round-presentation/README.md` | ||
| in the marketplace, rather than restating a narrower rule. Adopters: | ||
|
|
||
| - `/planning:interview`: `plugins/planning/skills/interview/context/loop.md` "Out-of-band drift", | ||
| with its pointer in the skill's `SKILL.md`. | ||
| - `/discovery:research`: `plugins/discovery/skills/research/SKILL.md` "Outcome gate (run before | ||
| presenting)". | ||
| - `/discovery:explore`: `plugins/discovery/skills/explore/SKILL.md` "Outcome gate (before | ||
| EXPLORE.md handoff)". | ||
| - `/review:fanout`: `plugins/review/skills/fanout/SKILL.md` "Step 2: Normalize". | ||
| - The [recommendation-basis](../recommendation-basis/README.md) re-emit shape defers to this | ||
| contract when dispatched work moved a recommendation. | ||
|
|
||
| ## Format changes | ||
|
|
||
| This contract carries no version. A change to the rule updates every adopter in the same pull | ||
| request. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -98,13 +98,14 @@ and may ground a code edit, but its label carries the flag, | |
| When evidence changes a recommendation the user still has pending, restate it as **old → new → | ||
| why**: the superseded recommendation named as superseded, the replacement in its own outcome (a | ||
| `Basis:`-labeled recommendation, or the withheld open question), and the evidence that moved it. Re-state only the recommendations that moved; name the rest as | ||
| unchanged in one line. A pending recommendation the session has disproved is worse than none, | ||
| because the user decides against it. | ||
|
|
||
| The shape is adopted from `/planning:interview`'s out-of-band drift rule, outcome 2 and "Re-present | ||
| narrowly" in | ||
| [`plugins/planning/skills/interview/context/loop.md`](../../../plugins/planning/skills/interview/context/loop.md) | ||
| (lines 267-270). That file owns the wording; this doc generalizes it beyond an interview round. | ||
| unchanged in one line. When the evidence is dispatched work that returned while open items wait on | ||
| the user, [async-round-presentation](../async-round-presentation/README.md) governs instead: the | ||
| message ends with every open item in full, the moved one marked. A pending recommendation the | ||
|
Comment on lines
+101
to
+103
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This bumps the contract's re-emit shape to 3.0.0, but the plugin copies still give the old shape, so the shipped planning plugin contradicts itself. This section's own "Plugin-shipped copies" rule (L118-125) says each adopting plugin must state the re-emit shape in its own shipped text, because installed plugins cannot read
It has no exception for dispatched work. Fix: add the dispatched-work exception (with its absolute-URL pointer to async-round-presentation) to claude-lane: claude-review
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. pr-unblock / address-feedback: UNCERTAIN, left open Evidence:
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. pr-unblock / adjudicate-feedback: the finding stands A fresh-context adjudicator read the review comment, the locations both sides cited and the code at Evidence:
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. pr-fix lane: please fix this finding. Add the dispatched-work exception, with its absolute-URL pointer to
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. pr-unblock / address-feedback: UNCERTAIN, left open Evidence: |
||
| session has disproved is worse than none, because the user decides against it. | ||
|
|
||
| The shape is adopted from `/planning:interview`'s out-of-band drift rule, outcome 2, in | ||
| [`plugins/planning/skills/interview/context/loop.md`](../../../plugins/planning/skills/interview/context/loop.md). | ||
| That file owns the wording; this doc generalizes it beyond an interview round. | ||
|
|
||
| ## Routing | ||
|
|
||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.