From 3a345a2ee3549d08746076f5b3782b9800c0898c Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:29:23 -0700 Subject: [PATCH 1/6] #114 agents|feat: Permit reviewer insights and add the insight gate Revise the Knowledge items section so insights (I{n}) may be emitted by reviewers, replacing the housekeeping-only "never emitted by code review skills" boundary while keeping insights non-severity and never merge-blocking. Add an Insight gate as strict as the Actionability gate: an insight is non-obvious knowledge a future reader is materially worse off without, distinguished from a Suggestion by whether an action is implied. State it once in the canonical scheme and reference it from review-criteria. Add a shared review-insight-gate partial for reviewer subagents to include. --- .../content/skills/_data/artifact-conventions.md | 14 ++++++++++++-- .../agents/content/skills/review-criteria/SKILL.md | 4 ++++ .../subagents/_partials/review-insight-gate.md | 1 + 3 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 packages/agents/content/subagents/_partials/review-insight-gate.md diff --git a/packages/agents/content/skills/_data/artifact-conventions.md b/packages/agents/content/skills/_data/artifact-conventions.md index c6b5b6db..7862b75d 100644 --- a/packages/agents/content/skills/_data/artifact-conventions.md +++ b/packages/agents/content/skills/_data/artifact-conventions.md @@ -839,13 +839,23 @@ Apply this gate **hardest** to R and S, where the low criticality bar invites fi ## Knowledge items -Knowledge items capture observations and learnings worth preserving. They are not findings: They have no criticality, are never merge-blocking, and are never emitted by code review skills. They appear in housekeeping artifacts (wrap-up inventories, chat summaries, devlogs) where conveying knowledge โ€” not assigning blame or action โ€” is the point. +Knowledge items capture observations and learnings worth preserving. They are not findings: they have no criticality and are never merge-blocking. They belong wherever knowledge is worth carrying forward โ€” housekeeping artifacts (wrap-up inventories, chat summaries, devlogs), run summaries, and, when they clear the Insight gate below, review artifacts. | ID | Category | Icon | Kind | | ------ | -------- | ---- | --------- | | `I{n}` | Insight | ๐Ÿ’ก | knowledge | -Consumers that present insights (`wrap-up`, `summarize-chat`) should render the icon alongside the prefix or label to mirror the convention used for findings. +Consumers that present insights (`wrap-up`, `summarize-chat`, review skills and reviewer agents) should render the icon alongside the prefix or label to mirror the convention used for findings. + +### Insight gate + +An insight is the deliberate complement to a finding: a finding hands the author a decision to act on now; an insight preserves knowledge a future reader would otherwise rediscover. Reviewers may emit insights, but only through a gate as strict as the [Actionability gate](#actionability-gate) โ€” "no severity, no action" is exactly the low bar that invites filler. + +Emit an insight only when it is **non-obvious knowledge a future reader is materially worse off without**, and name that benefit. "A thing I noticed" does not qualify, nor does anything the code, its comments, or its tests already make plain. + +**Insight vs. Suggestion (`S`).** Both are non-blocking, so they are easy to conflate; the test is whether an action is implied. An `S` proposes a change to make in this code now (and must clear the Actionability gate); an `I` records knowledge with no action attached. When an item implies a change the author should weigh, it is an `S`, not an insight โ€” and when in doubt with any action implied, classify it as `S`. + +Insights never carry criticality, never block a merge, and never count toward a review score or the [Overall criticality mapping](#overall-criticality-mapping). ## Artifact lifecycle diff --git a/packages/agents/content/skills/review-criteria/SKILL.md b/packages/agents/content/skills/review-criteria/SKILL.md index acc03f62..28984b9e 100644 --- a/packages/agents/content/skills/review-criteria/SKILL.md +++ b/packages/agents/content/skills/review-criteria/SKILL.md @@ -44,6 +44,10 @@ Findings use the canonical [finding scheme](../_data/artifact-conventions.md#fin Before emitting any F/W/T/R/S finding, confirm it hands the author a concrete decision they can act on **in this change**: fix, defer with a ticket, or explicitly accept. Hedging language inside a finding ("no action this PR", "not actionable here", "just capturing a thought", "call it out only if X", "would matter once Y") is your own signal that it does not belong; drop it, don't soften it. A finding that endorses the current state and then proposes a change anyway is incoherent; drop it. Self-test: _would I make this exact change right now if it were my code?_ If no, it is not a finding. Apply this hardest to R and S. Full treatment, including where dropped content goes: [finding scheme ยง Actionability gate](../_data/artifact-conventions.md#actionability-gate). +## Insight gate + +Reviewers may emit insights (`I{n}`) โ€” knowledge worth preserving that is not a finding. An insight must clear a gate as strict as the Actionability gate: emit it only when it is non-obvious knowledge a future reader is materially worse off without, and name that benefit. Distinguish it from a Suggestion (`S`): an `S` proposes a change to make now; an `I` records knowledge with no action attached. When an action is implied, it is an `S`, not an insight. Number insights sequentially (`I1`, `I2`, โ€ฆ) in their own sequence, with no severity and no `-L` marker. Full treatment: [knowledge items ยง Insight gate](../_data/artifact-conventions.md#insight-gate). + ## Finding concision Compose each finding at the tight altitude ([concision principle](../_data/concision.md)): State the defect, its location, and the decision the author must make, then stop. Cut code the author can already see, hedged narration, and rationale for why you looked. Every reader pays for each line, so weigh each sentence against the decision it enables, not its completeness. diff --git a/packages/agents/content/subagents/_partials/review-insight-gate.md b/packages/agents/content/subagents/_partials/review-insight-gate.md new file mode 100644 index 00000000..e9c72913 --- /dev/null +++ b/packages/agents/content/subagents/_partials/review-insight-gate.md @@ -0,0 +1 @@ +- **Insights are gated too**: You may emit an insight (`I{n}`) โ€” knowledge worth preserving that is not a finding โ€” but only when it is non-obvious knowledge a future reader is materially worse off without; "a thing I noticed" is not one. An insight records knowledge with no action attached; the moment it implies a change to make now, it is a Suggestion (`S`), not an insight. Insights carry no severity and never affect criticality. See the `review-criteria` skill for the full Insight gate. From 3d2321e9d2c79d4a43671a80df4491425d4489ef Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:34:58 -0700 Subject: [PATCH 2/6] #114 agents|feat: Let reviewer subagents emit gated insights Give the five code-review subagents (code, silent-failure, test, simplification, and orchestrated) an insight-gate include so each may emit I{n} insights alongside its findings. Add the `### Insights` section to the shared review-writes scaffold so every reviewer's artifact carries it, and describe the finalized insight form in the finalize partial: gated per the insight gate, no severity, excluded from the criticality aggregate, and omitted when empty. --- .../content/subagents/_partials/review-writes-finalize.md | 2 ++ .../content/subagents/_partials/review-writes-interim.md | 2 +- .../content/subagents/_partials/review-writes-scaffold.md | 4 ++++ packages/agents/content/subagents/aspect-code-reviewer.md | 1 + .../content/subagents/aspect-silent-failure-reviewer.md | 1 + packages/agents/content/subagents/aspect-test-reviewer.md | 1 + .../agents/content/subagents/code-simplification-reviewer.md | 1 + packages/agents/content/subagents/orchestrated-reviewer.md | 1 + 8 files changed, 12 insertions(+), 1 deletion(-) diff --git a/packages/agents/content/subagents/_partials/review-writes-finalize.md b/packages/agents/content/subagents/_partials/review-writes-finalize.md index 17cde430..eb9ea0b4 100644 --- a/packages/agents/content/subagents/_partials/review-writes-finalize.md +++ b/packages/agents/content/subagents/_partials/review-writes-finalize.md @@ -1,4 +1,6 @@ ### Finalize (reserved last 3 turns) Replace `### Criticality: (pending)` with the aggregate enum value (`none|low|medium|high`) and replace `### Summary`'s `(pending)` placeholder with the 1-2 sentence overall assessment. + +Insights are not findings โ€” they carry no severity and never affect the criticality aggregate; a review with only insights and no findings is still `none`. Put any emitted insights under the `### Insights` section, one `#### I{n}: {title}` per insight with a `- **Description:**` line and an optional `- **Destination:** ticket comment | devlog`; omit the section when there are none. Gate each insight per the `review-criteria` insight gate first. diff --git a/packages/agents/content/subagents/_partials/review-writes-interim.md b/packages/agents/content/subagents/_partials/review-writes-interim.md index 8069bd19..07e1c794 100644 --- a/packages/agents/content/subagents/_partials/review-writes-interim.md +++ b/packages/agents/content/subagents/_partials/review-writes-interim.md @@ -1,6 +1,6 @@ ### Interim writes (after each finding) -After each finding crystallizes, overwrite the artifact with the current findings appended under `### Findings`. `### Criticality:` stays `(pending)` and `### Summary` stays `(pending)` until finalize. Example interim form with one finding present: +After each finding crystallizes, overwrite the artifact with the current findings appended under `### Findings` (and any gated insights under `### Insights`). `### Criticality:` stays `(pending)` and `### Summary` stays `(pending)` until finalize. Example interim form with one finding present: ```markdown ### Criticality: (pending) diff --git a/packages/agents/content/subagents/_partials/review-writes-scaffold.md b/packages/agents/content/subagents/_partials/review-writes-scaffold.md index dc3f72d9..068594da 100644 --- a/packages/agents/content/subagents/_partials/review-writes-scaffold.md +++ b/packages/agents/content/subagents/_partials/review-writes-scaffold.md @@ -28,6 +28,10 @@ run_id: '{run id}' ### Findings +(none yet) + +### Insights + (none yet) ``` diff --git a/packages/agents/content/subagents/aspect-code-reviewer.md b/packages/agents/content/subagents/aspect-code-reviewer.md index e64ef941..6ef2e2e2 100644 --- a/packages/agents/content/subagents/aspect-code-reviewer.md +++ b/packages/agents/content/subagents/aspect-code-reviewer.md @@ -173,6 +173,7 @@ Scope re-reviews to your domain: project guideline compliance, bugs, and logic e - **Only actionable findings**: No praise, no style nits outside project conventions + - **No false positives**: If you're not confident something is wrong, don't flag it - **Context-aware**: Understand the codebase conventions before flagging violations. What looks wrong in isolation might be the established pattern. - **Proportional**: A typo fix doesn't need the same scrutiny as a security-critical change. Match your depth to the risk. diff --git a/packages/agents/content/subagents/aspect-silent-failure-reviewer.md b/packages/agents/content/subagents/aspect-silent-failure-reviewer.md index 21099e88..b6692a77 100644 --- a/packages/agents/content/subagents/aspect-silent-failure-reviewer.md +++ b/packages/agents/content/subagents/aspect-silent-failure-reviewer.md @@ -166,6 +166,7 @@ Scope re-reviews to your domain: error handling, catch blocks, fallback behavior - **Only actionable findings**: No praise, no generic advice + - **No false positives**: If you're not confident something is a silent-failure risk, don't flag it - **Context-aware**: Understand the codebase error-handling conventions before flagging violations - **Proportional**: Match scrutiny to the risk level of the code being reviewed diff --git a/packages/agents/content/subagents/aspect-test-reviewer.md b/packages/agents/content/subagents/aspect-test-reviewer.md index 388b3079..0ededeba 100644 --- a/packages/agents/content/subagents/aspect-test-reviewer.md +++ b/packages/agents/content/subagents/aspect-test-reviewer.md @@ -179,6 +179,7 @@ Scope re-reviews to your domain: test coverage quality, behavioral gaps, and mis - **Only actionable findings**: No praise, no generic "add more tests" advice + - **No false positives**: If you're not confident a test gap matters, don't flag it - **Context-aware**: Understand the project's testing conventions and framework before flagging violations - **Proportional**: Match scrutiny to the risk level of the untested behavior diff --git a/packages/agents/content/subagents/code-simplification-reviewer.md b/packages/agents/content/subagents/code-simplification-reviewer.md index 1b240677..dfe3de75 100644 --- a/packages/agents/content/subagents/code-simplification-reviewer.md +++ b/packages/agents/content/subagents/code-simplification-reviewer.md @@ -163,6 +163,7 @@ If no findings: - **Only actionable findings**: No praise, no style nits outside project conventions + - **No false positives**: If you're not confident a simplification improves the code, don't flag it - **Context-aware**: Understand the codebase conventions before flagging opportunities. What looks verbose in isolation might be the established pattern. - **Proportional**: Match your depth to the risk and scope of the change diff --git a/packages/agents/content/subagents/orchestrated-reviewer.md b/packages/agents/content/subagents/orchestrated-reviewer.md index 48e89bfc..c8a5930f 100644 --- a/packages/agents/content/subagents/orchestrated-reviewer.md +++ b/packages/agents/content/subagents/orchestrated-reviewer.md @@ -179,6 +179,7 @@ When reviewing after a coder has responded to previous findings: - **Only actionable findings**: No praise, no style nits, no "consider doing X" without clear justification + - **No false positives**: If you're not confident something is wrong, don't flag it. Every finding should be worth the coder's time. - **Context-aware**: Understand the codebase conventions before flagging violations. What looks wrong in isolation might be the established pattern. - **Proportional**: A typo fix doesn't need the same scrutiny as a security-critical change. Match your depth to the risk. From 17eca4d94b2761e7a72b917a493ccc5237e8cfb3 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:36:36 -0700 Subject: [PATCH 3/6] #114 agents|feat: Render reviewer insights in the standalone review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an `## Insights` section to the review-branch artifact body, placed after `## Areas for improvement` and before `## Technical assessment`, with I{n} items carrying a description and an optional destination. Insights are gated per the insight gate, carry no severity, and do not count against the score; the section is omitted when there are none. Add the I{n} entry to the issue-numbering list and the ๐Ÿ’ก icon to the section-header icon set. review-pr and its platform delegates inherit this body structure unchanged, since the review artifact is produced by review-branch's shared process. --- .../agents/content/skills/review-branch/SKILL.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/packages/agents/content/skills/review-branch/SKILL.md b/packages/agents/content/skills/review-branch/SKILL.md index ed384a5a..7a4342a5 100644 --- a/packages/agents/content/skills/review-branch/SKILL.md +++ b/packages/agents/content/skills/review-branch/SKILL.md @@ -94,10 +94,11 @@ Uniquely number all issues for easy reference. See [finding scheme](../_data/art - Recommendations: `R{n}` โ€” advisable but discretionary - Suggestions: `S{n}` โ€” optional improvement - Legacy: `{F,W,T,R,S}{n}-L` โ€” observation in pre-existing code, not authored in this change. Same severity letter as the equivalent author finding; number it from that letter's shared sequence first, then append `-L` as a marker (e.g., after `F1`, `F2`, the first legacy FIXME is `F3-L`) +- Insights: `I{n}` โ€” knowledge worth preserving, gated per the [insight gate](../review-criteria/SKILL.md#insight-gate); no severity, does not count against the score ## Output format -Section-header icons (๐Ÿšจ, โš ๏ธ, ๐Ÿ“‹, ๐Ÿง , โ˜๏ธ, ๐Ÿ”) come from the canonical [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix); render them as shown. Each finding under "Action required" and "Areas for improvement" follows the canonical per-finding template shown below โ€” see [`review-criteria` ยง Finding references](../review-criteria/SKILL.md#finding-references) for the rules governing the `Location:` field. +Section-header icons (๐Ÿšจ, โš ๏ธ, ๐Ÿ“‹, ๐Ÿง , โ˜๏ธ, ๐Ÿ”) come from the canonical [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix), and the ๐Ÿ’ก insights icon from [knowledge items](../_data/artifact-conventions.md#knowledge-items); render them as shown. Each finding under "Action required" and "Areas for improvement" follows the canonical per-finding template shown below โ€” see [`review-criteria` ยง Finding references](../review-criteria/SKILL.md#finding-references) for the rules governing the `Location:` field. When `ticket_ref` is null (no ticket on the branch), omit the `{ticket_ref}: ` portion so the heading reads naturally without it โ€” e.g., `# Code review: {description}`. @@ -155,6 +156,15 @@ The body following the frontmatter has this structure: {Observations in pre-existing code, using severity-tagged IDs with `-L` suffix (e.g., `F3-L`, `T2-L`). Frame as future opportunities, don't count against score} +## Insights + +{Knowledge worth preserving that is not a finding โ€” a pattern, gotcha, or architectural learning surfaced during review. Gated per the [insight gate](../review-criteria/SKILL.md#insight-gate); no severity, does not count against the score. Omit this section entirely when there are none.} + +### I1: {title} + +- **Description:** {the insight and why a future reader is worse off without it} +- **Destination:** {optional: `ticket comment` or `devlog`} + ## Technical assessment ## Conclusion From f0bc88eabd3fa7e2ec6ca7d452519b58c092618f Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:38:17 -0700 Subject: [PATCH 4/6] #114 agents|feat: Harvest reviewer insights structurally in wrap-up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the wrap-up insight step to read structured insight sources first โ€” the `## Insights` / `### Insights` section of review artifacts and the run-summary โ€” before conversation-scanning, mirroring the structured-source precedence the deferred-item step already uses. Conversation scanning skips any insight already captured from a structured source, so a review-emitted insight and its conversation echo collapse to one item with the structured copy winning. Resolve each insight's destination by honoring a reviewer-suggested destination when present, otherwise applying the existing ticket-comment-versus-devlog heuristic. This makes reviewer insights reach wrap-up in the non-orchestrated review flow, which has no run-summary and previously captured insights only heuristically from conversation prose. --- packages/agents/content/skills/wrap-up/SKILL.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/packages/agents/content/skills/wrap-up/SKILL.md b/packages/agents/content/skills/wrap-up/SKILL.md index 393e1153..f0622109 100644 --- a/packages/agents/content/skills/wrap-up/SKILL.md +++ b/packages/agents/content/skills/wrap-up/SKILL.md @@ -99,10 +99,19 @@ Items at levels 3โ€“4 remain in the standard findings pool for the housekeeping The complexity assessment feeds into the cost-aware disposition flow described in [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md): Trivial items prefer **do now** (Phase 2a drive-bys); items that can't ship as drive-bys but share scope or source prefer **batch later** (Phase 2b batch action); substantive items get a **separate ticket** (Phase 2b per-item ticketing). -#### 1c. Scan for insights +#### 1c. Collect insights Insights are notable observations worth preserving โ€” patterns learned, surprising findings, or knowledge that would benefit future work. +**Structured sources** (high confidence): + +- **Review artifacts**: Extract `I{n}` insights from the `## Insights` / `### Insights` section of review artifacts (both the standalone review and reviewer-subagent artifacts). Reviewers emit these under the insight gate, so they are already vetted knowledge, not heuristic guesses. +- **Run-summary artifact**: If an orchestrated run was detected, read the `## Insights` section of the most recent `*_orchestrator_run-summary.md` in the run directory. + +**Conversation scanning** (heuristic โ€” may produce false positives): + +Structured sources take precedence. When scanning conversation, skip any insight already captured from a structured source (the same observation) to avoid duplicates โ€” a review-emitted insight and its conversation echo are one item, and the structured one wins. + Scan the conversation for: - Architectural patterns discovered or validated @@ -113,10 +122,10 @@ Scan the conversation for: Look for language like: "interesting", "discovered", "realized", "turns out", "surprisingly", "TIL", "worth noting", "insight", "lesson", "gotcha", "caveat". -For each insight found, assign an `I{n}` ID (sequentially: I1, I2, ...) and suggest a destination: +For each insight (structured or conversation-scanned), assign an `I{n}` ID (sequentially: I1, I2, ...) and resolve a destination: -- `ticket comment` โ€” if the insight relates to the current ticket's work -- `devlog` โ€” if the insight is general knowledge not specific to one ticket +- Honor a destination the source insight already carries โ€” a reviewer may suggest `ticket comment` or `devlog`. +- Otherwise: `ticket comment` if the insight relates to the current ticket's work; `devlog` if it is general knowledge not specific to one ticket. If no ticket is available (from the session-context manifest), default all destinations to `devlog`. From bde1d9ececd8c9c3b96c3c02c095d70e57501612 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:38:57 -0700 Subject: [PATCH 5/6] #114 agents|feat: Aggregate reviewer insights into the run-summary Change the run-summary Insights section from free synthesis to structural aggregation: collect the I{n} insights emitted across the run's reviewer artifacts, dedup an insight several reviewers raised into one entry, and add an orchestrator-level observation only when no reviewer already captured it. The omit-when-empty behavior is unchanged, so the Phase 6 wrap-up trigger still fires only on a non-empty section. --- packages/agents/content/skills/orchestrate/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/agents/content/skills/orchestrate/SKILL.md b/packages/agents/content/skills/orchestrate/SKILL.md index 992de7b9..dbcc93cf 100644 --- a/packages/agents/content/skills/orchestrate/SKILL.md +++ b/packages/agents/content/skills/orchestrate/SKILL.md @@ -692,14 +692,14 @@ Write run-summary artifact to `{run-dir}/{NN}_orchestrator_run-summary.md`. The ## Insights -{Notable observations that emerged during the run. Include only items worth preserving โ€” omit this section entirely if nothing notable emerged. +{Aggregate the `I{n}` insights emitted across this run's reviewer artifacts, deduplicating an insight that several reviewers raised into a single entry. Reviewers emit these under the insight gate, so prefer their vetted items over re-derived narration; add an orchestrator-level observation only when it is worth preserving and no reviewer already captured it. Include only items worth preserving โ€” omit this section entirely if none emerged. -Examples of what belongs here: +What belongs here: - Architectural patterns discovered or validated - Design trade-offs surfaced during review - Conventions or project-specific patterns learned -- Surprising findings from reviewers that revealed something non-obvious +- Non-obvious knowledge a reviewer flagged as an insight - Technical debt or risks identified but not in scope to address} ## Deferred items From dadd276924fe1be9bb41a8dd6b5fd0e879d706c3 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 18 Jul 2026 13:58:30 -0700 Subject: [PATCH 6/6] #114 agents|fix: Select wrap-up insight source by run type Make wrap-up's two structured insight sources mutually exclusive by run type so no insight is harvested twice. An orchestrated run reads the run-summary `## Insights` aggregate, which already collects and dedups every reviewer-subagent artifact's insights; a non-orchestrated run reads the standalone review artifact, the only structured insight source when no orchestrated run exists. The conversation-scan dedup was structured-vs-conversation only, so when the run-summary aggregate overlapped the per-reviewer artifacts an orchestrated wrap-up listed each reviewer insight twice. --- packages/agents/content/skills/wrap-up/SKILL.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/agents/content/skills/wrap-up/SKILL.md b/packages/agents/content/skills/wrap-up/SKILL.md index f0622109..5616023a 100644 --- a/packages/agents/content/skills/wrap-up/SKILL.md +++ b/packages/agents/content/skills/wrap-up/SKILL.md @@ -103,10 +103,12 @@ The complexity assessment feeds into the cost-aware disposition flow described i Insights are notable observations worth preserving โ€” patterns learned, surprising findings, or knowledge that would benefit future work. -**Structured sources** (high confidence): +**Structured sources** (high confidence). Which source applies is fixed by the run type detected in 1a โ€” the two never both apply, so there is no structured-vs-structured overlap to dedup: + +- **Orchestrated run โ†’ run-summary**: Read the `## Insights` section of the most recent `*_orchestrator_run-summary.md` in the run directory. It already aggregates and dedups the `I{n}` insights from every reviewer-subagent artifact in the run, so reading it โ€” rather than the per-reviewer artifacts โ€” captures each insight exactly once. +- **Non-orchestrated run โ†’ review artifact**: Read the `## Insights` section of the standalone review artifact (`*_reviewer_review.md`). Reviewer-subagent artifacts exist only in orchestrated runs, so outside orchestration this is the sole structured insight source. -- **Review artifacts**: Extract `I{n}` insights from the `## Insights` / `### Insights` section of review artifacts (both the standalone review and reviewer-subagent artifacts). Reviewers emit these under the insight gate, so they are already vetted knowledge, not heuristic guesses. -- **Run-summary artifact**: If an orchestrated run was detected, read the `## Insights` section of the most recent `*_orchestrator_run-summary.md` in the run directory. +Either way, reviewers emit these under the insight gate, so they are vetted knowledge, not heuristic guesses. **Conversation scanning** (heuristic โ€” may produce false positives):