Context
Surfaced in the 2026-04-24 Agent-Brain ideation session with @tobiu during the meta-enhancement sweep that also produced #10272, #10273, #10274, #10275, #10276. Core observation: strong Discussions like #10119 and #10137 have organically evolved through multi-round iteration — but ideation-sandbox is structured as a one-shot skill that covers initial authoring and stops there.
#10119 is the canonical case. Its author's note explicitly documents the organic pattern:
"Iterated through five rounds of architectural pushback from @tobiu before filing, followed by four post-publication correction passes... The three corrections originally landed as separate comments below; body has since been updated to carry the fixes inline, following the #10119 annotation pattern."
That last phrase — "the #10119 annotation pattern" — self-references a convention that has no skill-level codification. It's in the repo, it's visibly effective, it has no documented protocol. The next agent authoring a Discussion of similar depth re-derives the pattern from scratch or (worse) doesn't know to iterate at all.
#10137 (MX Model Experience) follows the same shape: author's note with correction-pass provenance, Open Questions section, per-domain Graduation Criteria. Two repo-level exemplars; zero skill-level protocol. That's the codification gap this ticket closes.
The Problem
Three failure modes observed when the iteration protocol isn't codified:
Frozen Discussions. Filed without iteration. OQs accumulate as open forever. Never graduate. The Native Edge Graph has them as perpetual-open concept nodes but they never mature into epics.
Comment-orphan edits. Reviewer comments on concerns. Author responds in a comment. Body stays stale. Next reader sees body + 12 comments, can't tell what's current. (PR equivalent: reviewing a PR where every concern is addressed in the PR comments but the diff itself was never updated. Everyone hates this.)
Graduation ambiguity. When is a Discussion "done enough" to become an Epic? #10119 answered this per-Discussion via an explicit Graduation Criteria section. But no skill-level protocol exists saying "write one of these" — so most Discussions don't.
The MX loop framing from #10137 applies directly: the 2026-04-24 Agent-Brain re-derivation (caught by #10276) was partly a symptom of this gap. The author had authored #10137 days earlier but had no protocol guiding them to re-engage with the Open Questions before sketching new ideas. Codifying the iteration protocol addresses the lifecycle; the adjacency sweep (#10276) addresses the entry. Symmetric fixes for symmetric gaps.
The Architectural Reality
.agent/skills/ideation-sandbox/SKILL.md — current skill. Covers drafting + initial filing. Missing: post-authoring iteration, OQ resolution tracking, graduation criteria..agent/skills/pr-review/references/pr-review-guide.md — established iteration protocol for PRs. Three phases (review, author response, re-review) + graph-ingestion tags ([ADDRESSED] / [DEFERRED] / [REJECTED_WITH_RATIONALE]). Model to mirror..agent/skills/pull-request/references/pull-request-workflow.md — symmetric author-side for PRs. Same iteration surface, author perspective.- The PR-parallel framing: Discussion body = PR diff; Discussion comments = review feedback; body edits = force-push; all-OQs-resolved = approval; epic graduation = merge-to-main. The analogy holds cleanly and maps to workflows agents already know.
- Case studies shipping today: #10119 (author's note + OQs + per-domain graduation criteria) and #10137 (same pattern, different domain). Codifying wraps existing successful pattern, not inventing new one.
The Fix
Three new sections added to .agent/skills/ideation-sandbox/SKILL.md:
§N Iterative Review Workflow (PR-Parallel)
Introduces the mental model: Discussion is a PR, comments are review feedback, body edits are force-pushes. Three-phase protocol mirroring pr-review:
- Review Phase. Reviewers post comments with concerns, challenges, clarifying questions, proposed OQ additions. Same tone guidance as
pr-review §1 (peer vs self vs cross-family). Depth Floor §7.1 minimum-one-challenge applies to Discussion reviews too.
- Author Response Phase. Author updates the main body in place, not a reply comment. Annotation marker at top of body carries the change log (see §N+1 Author's Note Convention below). Optional brief comment notifies the channel; the body itself is the authoritative response substrate.
- Resolution Tracking Phase. Each OQ gets tagged with a resolution state (see tag taxonomy below). OQs don't sit open indefinitely.
Graph-ingestion tags for OQ resolution (mirror pr-review §4 structurally):
[RESOLVED_TO_AC] — OQ folded into the epic body as a concrete AC item[GRADUATED_TO_TICKET] — OQ becomes a standalone sub-issue; link the ticket number[DEFERRED_WITH_TIMELINE] — OQ acknowledged but parked; name the trigger condition ("revisit when X lands")[REJECTED_WITH_RATIONALE] — OQ explicitly not pursued; explain why
The Retrospective daemon ingests these the same way it ingests PR review tags — negotiation-thread completeness at the ideation layer.
§N+1 Author's Note Convention
Codifies the top-of-body iteration-provenance pattern emergent from #10119:
> **Author's Note:** [Synthesis origin — agent identity, session ID, human collaborators].
> [Pre-publication iteration summary: N rounds of pushback / corrections before filing.]
>
> **Post-publication correction passes** (dates, same session):
> (1) **[short name]** — [what was wrong, what was corrected]
> (2) **[short name]** — [etc.]
> The corrections originally landed as separate comments below; body has since been
> updated to carry the fixes inline, following the #10119 annotation pattern.
Explicit name: "the #10119 annotation pattern." Once in the skill, future Discussions can self-reference it without each author re-inventing the convention.
§N+2 Per-Domain Graduation Criteria
Not a universal checklist. Each Discussion articulates its own graduation criteria in a dedicated section, matching what #10119 actually ships:
"Scenarios B (standalone harness) and C (extended NL MCP coordination substrate) are the graduation candidates... Either track could ship independently or as a joint epic."
Skill mandate: any Discussion filed under ideation-sandbox MUST have a Graduation Criteria section. If the author can't articulate what "ready for epic" looks like for this proposal specifically, the Discussion isn't yet scoped clearly enough to graduate. Writing it forces the clarity.
Graduation trigger: author (agent or human) declares readiness by adding a GRADUATED marker near the top of the body, linking to the Epic ticket created from it. The Discussion stays open as the archaeological source; the Epic becomes the actionable artifact.
Acceptance Criteria
Out of Scope
- Automated OQ state tracking / CI enforcement. Skill-level protocol first; technical enforcement only if compliance drift appears.
- Retroactive audit of existing Discussions for tag compliance. Not valuable — existing strong Discussions (#10119, #10137) are already the canonical cases; no backward sweep needed.
- Unified Discussion-vs-Epic merge protocol. When a Discussion graduates to an Epic, the mechanical "close Discussion / open Epic / link via native graph" step is already supported by existing GH workflow tools. This ticket codifies when, not how.
- Automated graduation detection. Graduation is an author-declared event. Machine-detecting "is this Discussion ready" is outside scope; it's a human/agent judgment call.
Avoided Traps
- Universal graduation checklist. Rejected in favor of per-Discussion articulation. Forcing every Discussion through an identical set of graduation criteria would flatten the genuine domain diversity #10119 and #10137 exemplify (harness architecture vs. design-principle crystallization — different criteria should govern different domains).
- Mandating comments on every response. Rejected.
#10119's body-folding pattern is the convention — silent body-edits with a top-of-body annotation marker beat noisy parallel comment threads. Authors can add a brief comment for notification, but the body is the authoritative substrate.
- Tag inflation. Started with a 4-tag taxonomy that mirrors PR review response tags exactly. More tags would invite ambiguity without capturing new states. If empirical friction shows 4 isn't enough, extend then — not speculatively.
- Hard-coding graduation trigger to "all OQs resolved." Rejected.
#10119 ships with 12 OQs; some block architecture, some surface implementation questions that naturally become sub-tickets. Graduation requires architectural OQs resolved, not ALL OQs closed. Per-domain criteria captures this nuance.
Related
- Origin: 2026-04-24 Agent-Brain ideation session (Claude Opus 4.7, session
b02bd06c-a2cb-4aff-8af1-c4f2643c91be)
- Canonical Discussion case studies: #10119 (Agent harness as Neo app), #10137 (MX Model Experience)
- Symmetric with: #10276 (ideation-sandbox §1 pre-authoring adjacency sweep) — together these cover entry + middle + exit of the ideation-sandbox lifecycle, paralleling ticket-create's §1 gate + §5 Fat Ticket + §6 visible proposal multi-phase shape
- Mirrors structurally:
.agent/skills/pr-review/references/pr-review-guide.md (PR iteration protocol) and .agent/skills/pull-request/references/pull-request-workflow.md §6 (author-side review response tags)
- Related meta-enhancement tickets from same session: #10272 (comment-ID workflow), #10273 (pr-review decile anchors), #10274 (merge-authorization), #10275 (silence detection daemon)
Origin Session ID: b02bd06c-a2cb-4aff-8af1-c4f2643c91be
Retrieval Hint: "ideation-sandbox iterative review workflow annotation pattern #10119 author's note graduation criteria OQ resolution tags" / "Discussion body as PR diff; comments as review feedback; body edits as force-push; mirrors pr-review protocol"
Context
Surfaced in the 2026-04-24 Agent-Brain ideation session with @tobiu during the meta-enhancement sweep that also produced #10272, #10273, #10274, #10275, #10276. Core observation: strong Discussions like #10119 and #10137 have organically evolved through multi-round iteration — but
ideation-sandboxis structured as a one-shot skill that covers initial authoring and stops there.#10119 is the canonical case. Its author's note explicitly documents the organic pattern:
That last phrase — "the #10119 annotation pattern" — self-references a convention that has no skill-level codification. It's in the repo, it's visibly effective, it has no documented protocol. The next agent authoring a Discussion of similar depth re-derives the pattern from scratch or (worse) doesn't know to iterate at all.
#10137 (MX Model Experience) follows the same shape: author's note with correction-pass provenance, Open Questions section, per-domain Graduation Criteria. Two repo-level exemplars; zero skill-level protocol. That's the codification gap this ticket closes.
The Problem
Three failure modes observed when the iteration protocol isn't codified:
Frozen Discussions. Filed without iteration. OQs accumulate as open forever. Never graduate. The Native Edge Graph has them as perpetual-open concept nodes but they never mature into epics.
Comment-orphan edits. Reviewer comments on concerns. Author responds in a comment. Body stays stale. Next reader sees body + 12 comments, can't tell what's current. (PR equivalent: reviewing a PR where every concern is addressed in the PR comments but the diff itself was never updated. Everyone hates this.)
Graduation ambiguity. When is a Discussion "done enough" to become an Epic? #10119 answered this per-Discussion via an explicit Graduation Criteria section. But no skill-level protocol exists saying "write one of these" — so most Discussions don't.
The MX loop framing from #10137 applies directly: the 2026-04-24 Agent-Brain re-derivation (caught by #10276) was partly a symptom of this gap. The author had authored #10137 days earlier but had no protocol guiding them to re-engage with the Open Questions before sketching new ideas. Codifying the iteration protocol addresses the lifecycle; the adjacency sweep (#10276) addresses the entry. Symmetric fixes for symmetric gaps.
The Architectural Reality
.agent/skills/ideation-sandbox/SKILL.md— current skill. Covers drafting + initial filing. Missing: post-authoring iteration, OQ resolution tracking, graduation criteria..agent/skills/pr-review/references/pr-review-guide.md— established iteration protocol for PRs. Three phases (review, author response, re-review) + graph-ingestion tags ([ADDRESSED]/[DEFERRED]/[REJECTED_WITH_RATIONALE]). Model to mirror..agent/skills/pull-request/references/pull-request-workflow.md— symmetric author-side for PRs. Same iteration surface, author perspective.The Fix
Three new sections added to
.agent/skills/ideation-sandbox/SKILL.md:§N Iterative Review Workflow (PR-Parallel)
Introduces the mental model: Discussion is a PR, comments are review feedback, body edits are force-pushes. Three-phase protocol mirroring
pr-review:pr-review §1(peer vs self vs cross-family). Depth Floor §7.1 minimum-one-challenge applies to Discussion reviews too.Graph-ingestion tags for OQ resolution (mirror
pr-review §4structurally):[RESOLVED_TO_AC]— OQ folded into the epic body as a concrete AC item[GRADUATED_TO_TICKET]— OQ becomes a standalone sub-issue; link the ticket number[DEFERRED_WITH_TIMELINE]— OQ acknowledged but parked; name the trigger condition ("revisit when X lands")[REJECTED_WITH_RATIONALE]— OQ explicitly not pursued; explain whyThe Retrospective daemon ingests these the same way it ingests PR review tags — negotiation-thread completeness at the ideation layer.
§N+1 Author's Note Convention
Codifies the top-of-body iteration-provenance pattern emergent from #10119:
> **Author's Note:** [Synthesis origin — agent identity, session ID, human collaborators]. > [Pre-publication iteration summary: N rounds of pushback / corrections before filing.] > > **Post-publication correction passes** (dates, same session): > (1) **[short name]** — [what was wrong, what was corrected] > (2) **[short name]** — [etc.] > The corrections originally landed as separate comments below; body has since been > updated to carry the fixes inline, following the #10119 annotation pattern.Explicit name: "the #10119 annotation pattern." Once in the skill, future Discussions can self-reference it without each author re-inventing the convention.
§N+2 Per-Domain Graduation Criteria
Not a universal checklist. Each Discussion articulates its own graduation criteria in a dedicated section, matching what #10119 actually ships:
Skill mandate: any Discussion filed under
ideation-sandboxMUST have a Graduation Criteria section. If the author can't articulate what "ready for epic" looks like for this proposal specifically, the Discussion isn't yet scoped clearly enough to graduate. Writing it forces the clarity.Graduation trigger: author (agent or human) declares readiness by adding a GRADUATED marker near the top of the body, linking to the Epic ticket created from it. The Discussion stays open as the archaeological source; the Epic becomes the actionable artifact.
Acceptance Criteria
.agent/skills/ideation-sandbox/SKILL.mdgains three sections: Iterative Review Workflow, Author's Note Convention, Per-Domain Graduation Criteria. Section numbering harmonized with existing skill structure.[RESOLVED_TO_AC]/[GRADUATED_TO_TICKET]/[DEFERRED_WITH_TIMELINE]/[REJECTED_WITH_RATIONALE]) documented alongside the Retrospective daemon ingestion protocol (mirrorspr-review §4).pr-review-guide.md §7.1(Depth Floor extension for Discussion reviews) and topull-request-workflow.md §6(symmetric author-side review response protocol — the tag taxonomy).ideation-sandboxfollow the new convention. Measure OQ resolution rate + graduation-to-epic rate. If Discussions still sit with open OQs after 14 days, sharpen the skill further.Out of Scope
Avoided Traps
#10119's body-folding pattern is the convention — silent body-edits with a top-of-body annotation marker beat noisy parallel comment threads. Authors can add a brief comment for notification, but the body is the authoritative substrate.#10119ships with 12 OQs; some block architecture, some surface implementation questions that naturally become sub-tickets. Graduation requires architectural OQs resolved, not ALL OQs closed. Per-domain criteria captures this nuance.Related
b02bd06c-a2cb-4aff-8af1-c4f2643c91be).agent/skills/pr-review/references/pr-review-guide.md(PR iteration protocol) and.agent/skills/pull-request/references/pull-request-workflow.md §6(author-side review response tags)Origin Session ID:
b02bd06c-a2cb-4aff-8af1-c4f2643c91beRetrieval Hint:
"ideation-sandbox iterative review workflow annotation pattern #10119 author's note graduation criteria OQ resolution tags"/"Discussion body as PR diff; comments as review feedback; body edits as force-push; mirrors pr-review protocol"