Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
7 changes: 7 additions & 0 deletions .changes/discovery/work-resolve-issue-issue-8466-b52e8d04.md
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,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
12 changes: 12 additions & 0 deletions .changes/planning/work-resolve-issue-issue-8466-3f9c1a7e.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
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.
- `context/recommendation-basis.md`: the re-emit rule defers to the same contract when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user (recommendation-basis 3.0.0).

### Added

- Eval cases `late-return-restates-every-open-question-in-full` and `held-question-release-restates-every-open-question-in-full`.
7 changes: 7 additions & 0 deletions .changes/review/work-resolve-issue-issue-8466-6a1d73c9.md
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,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Changed

- `context/recommendation-basis.md`: when the evidence that changes a pending recommendation is dispatched work that returned while open items wait on the user, the message ends with every open item in full, the moved one marked, in place of the one-line list of unchanged recommendations. The rule is `docs/contracts/async-round-presentation/README.md` in the marketplace (recommendation-basis 3.0.0).
53 changes: 53 additions & 0 deletions docs/contracts/async-round-presentation/README.md
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.
9 changes: 9 additions & 0 deletions docs/contracts/recommendation-basis/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ Notable changes to the recommendation-basis contract (SemVer). Changing the grou
label's values, or the re-emit shape is a major bump; additive guidance is a minor bump; docs-only
clarification is a patch.

## [3.0.0] - 2026-11-01

Major: the re-emit section defers to the async-round-presentation contract when the changed
recommendation comes from dispatched work that returned while open items wait on the user. That
message ends with every open item in full, the moved one marked, in place of the one-line list of
unchanged recommendations. The re-emit shape for any other evidence is unchanged. The
`/planning:interview` out-of-band drift rule and the plugin-shipped
`context/recommendation-basis.md` copies carry the change.

## [2.0.1] - 2026-10-10

Patch: the conforming-surfaces table folds the `/discipline:do-your-research-deep` row into
Expand Down
15 changes: 8 additions & 7 deletions docs/contracts/recommendation-basis/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
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

Expand Down
1 change: 1 addition & 0 deletions docs/plugin-philosophy.md
Original file line number Diff line number Diff line change
Expand Up @@ -888,6 +888,7 @@ doc before a second plugin adopts it. Fleet audits check conformance per row.
| Retired-convention detection and cleanup (manifest + shared helper) | [`docs/contracts/retired-conventions/`](contracts/retired-conventions/README.md) |
| Recommendation basis: grounding bar, `Basis:` label, and old → new → why re-statement | [`docs/contracts/recommendation-basis/`](contracts/recommendation-basis/README.md) |
| Authoring formats: acceptance-criteria format and diagram dialect by artifact kind, read by `/planning:interview`, `/planning:prd`, and `/planning:design` | [`docs/contracts/authoring-formats/`](contracts/authoring-formats/README.md) |
| Async round presentation: the latest message restates every open item in full after dispatched work returns | [`docs/contracts/async-round-presentation/`](contracts/async-round-presentation/README.md) |

## Cross-platform contract

Expand Down
7 changes: 6 additions & 1 deletion plugins/architecture/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
7 changes: 6 additions & 1 deletion plugins/code-tidying/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
7 changes: 6 additions & 1 deletion plugins/debugging/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
7 changes: 6 additions & 1 deletion plugins/developer-experience/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
7 changes: 6 additions & 1 deletion plugins/discipline/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
2 changes: 2 additions & 0 deletions plugins/discovery/skills/explore/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,8 @@ Before writing EXPLORE.md (or returning the summary), check the artifact against
- **Paths are machine-agnostic**. No finding in the artifact echoes an absolute machine path (notably the project root gathered above); every path it records is written relative to the repo root, or, when there is no repo root, to the current working directory, so the handoff stays portable across machines.
- **Open questions handed off, never dropped**. Surfaced to the user inline, or carried in the payload's `open_questions` for the parent to surface under dispatch. Each with a recommended default.

When dispatched work returns after you presented open questions and before the user answers, the next message that presents anything ends with every open question in full: `docs/contracts/async-round-presentation/README.md` in the marketplace.

## Scope

Explore the following: $ARGUMENTS
Expand Down
2 changes: 2 additions & 0 deletions plugins/discovery/skills/research/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ Each criterion is binary. **Any FAIL returns to the named phase (a verifier-owne

**A claim that cannot pass the gate is a Gap, not a finding**, never laundered into the answer. Report the gate result (pass, or which criterion failed and what you re-ran); rework bounds: "Effort, source breadth". Tier-3 reconciliation: "Reconciling sources at the gate" below.

When dispatched work returns after you presented open questions and before the user answers, the next message that presents anything ends with every open item in full: `docs/contracts/async-round-presentation/README.md` in the marketplace.

## Topic

Research the following topic: $ARGUMENTS
Expand Down
7 changes: 6 additions & 1 deletion plugins/github/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
7 changes: 6 additions & 1 deletion plugins/harness-ops/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,9 @@ convention, with its boundary and adopters, is
question that names the evidence that would settle it.
- **Re-emit.** When evidence changes a pending recommendation, restate it as
old → new → why, where new is a verified or judgment recommendation or the
withheld open question; name the unchanged ones in one line.
withheld open question; name the unchanged ones in one line. When the
evidence is dispatched work that returned while open items wait on the
user, the async-round-presentation contract governs instead: the message
ends with every open item in full, the moved one marked
(`docs/contracts/async-round-presentation/README.md` in the marketplace
repository).
Loading
Loading