Problem
Finding categories (FIXME, Warning, TODO, Recommendation, Suggestion, Legacy) have associated icons defined inline in packages/agents/content/skills/review-change/SKILL.md's output templates. The icons aren't part of the canonical finding scheme, so consumers like wrap-up and respond-to-review render findings without them — losing the at-a-glance severity cue that the review document already establishes. The insight item type used by wrap-up and summarize-chat has the same gap: 💡 is used inline but isn't canonicalized.
Example of current wrap-up output:
warning W1 — rename test in packages/release-kit/...
recommendation R1 — reword the docstring on resolveSinglePackageTags...
suggestion S1 — restructure filterPublishableTags...
Context
- The finding scheme (F/W/T/R/S +
-L legacy suffix) is canonically documented in _data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix and duplicated in review-criteria/SKILL.md.
- Icons currently appear only inline in
review-change/SKILL.md section headers: 🚨 ⚠️ 📋 🧠 💡 🔍.
- 💡 is used by
summarize-chat for "important learning," which is the same concept as wrap-up's insight (I{n}) prefix. The Suggestion icon is being changed from 💡 to ☝️ as part of this work, freeing 💡 to be the canonical Insight icon.
Insight is not a finding (no criticality, never merge-blocking, never produced by review skills). It will be canonicalized in a separate ## Knowledge items section adjacent to the finding scheme — not inside it — to avoid confusing reviewers about what they're allowed to emit.
- Scope of consumer updates is limited to
wrap-up, respond-to-review, and summarize-chat; broader rollout is out of scope.
Solution
- Add an Icon column to the canonical finding-scheme table in
_data/artifact-conventions.md. Adopt 🚨 / ⚠️ / 📋 / 🧠 / ☝️ / 🔍 for FIXME / Warning / TODO / Recommendation / Suggestion / Legacy respectively.
- Add a sibling
## Knowledge items section in _data/artifact-conventions.md containing a one-row table: I{n} | Insight | 💡 | knowledge. This canonicalizes 💡 as the Insight icon without pretending Insight is a finding.
- Deduplicate
review-criteria/SKILL.md: remove the duplicate finding-scheme table, category criteria, criticality mapping, and severity-escalation chain. Replace with a one-line link to the canonical section. Move the review-specific Warning Gate language into the canonical category criteria so it applies wherever findings are classified. Keep the PR comment format table in review-criteria (review-specific output guidance, not part of the scheme).
- Update
review-change/SKILL.md: change ### Suggestions 💡 to ### Suggestions ☝️ in both branch-scope and commit-scope output templates. Add a sentence pointing readers to the canonical icon table.
- Update
wrap-up/SKILL.md: render finding items with {icon} {prefix} {ID} in the drive-by output (Phase 2a) and the Findings/Legacy/Insights sections of the inventory output (Phase 2b). Add an Icon column to the Item vocabulary table, sourced from the canonical tables (findings from the finding scheme; insight from Knowledge items).
- Update
respond-to-review/SKILL.md: prefix the section headers with the icon (### FIXMEs 🚨, ### Warnings ⚠️, ### TODOs 📋, ### Recommendations 🧠, ### Suggestions ☝️, ### Legacy 🔍) so the response document mirrors the review document it pairs with.
- Update
summarize-chat/SKILL.md: continue using 💡 for important learnings, but add a link noting that 💡 is the canonical Insight icon defined in _data/artifact-conventions.md#knowledge-items.
Acceptance criteria
Problem
Finding categories (FIXME, Warning, TODO, Recommendation, Suggestion, Legacy) have associated icons defined inline in
packages/agents/content/skills/review-change/SKILL.md's output templates. The icons aren't part of the canonical finding scheme, so consumers likewrap-upandrespond-to-reviewrender findings without them — losing the at-a-glance severity cue that the review document already establishes. Theinsightitem type used bywrap-upandsummarize-chathas the same gap: 💡 is used inline but isn't canonicalized.Example of current wrap-up output:
Context
-Llegacy suffix) is canonically documented in_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffixand duplicated inreview-criteria/SKILL.md.review-change/SKILL.mdsection headers: 🚨summarize-chatfor "important learning," which is the same concept aswrap-up'sinsight(I{n}) prefix. The Suggestion icon is being changed from 💡 to ☝️ as part of this work, freeing 💡 to be the canonical Insight icon.Insightis not a finding (no criticality, never merge-blocking, never produced by review skills). It will be canonicalized in a separate## Knowledge itemssection adjacent to the finding scheme — not inside it — to avoid confusing reviewers about what they're allowed to emit.wrap-up,respond-to-review, andsummarize-chat; broader rollout is out of scope.Solution
_data/artifact-conventions.md. Adopt 🚨 /## Knowledge itemssection in_data/artifact-conventions.mdcontaining a one-row table:I{n} | Insight | 💡 | knowledge. This canonicalizes 💡 as the Insight icon without pretending Insight is a finding.review-criteria/SKILL.md: remove the duplicate finding-scheme table, category criteria, criticality mapping, and severity-escalation chain. Replace with a one-line link to the canonical section. Move the review-specific Warning Gate language into the canonical category criteria so it applies wherever findings are classified. Keep the PR comment format table inreview-criteria(review-specific output guidance, not part of the scheme).review-change/SKILL.md: change### Suggestions 💡to### Suggestions ☝️in both branch-scope and commit-scope output templates. Add a sentence pointing readers to the canonical icon table.wrap-up/SKILL.md: render finding items with{icon} {prefix} {ID}in the drive-by output (Phase 2a) and the Findings/Legacy/Insights sections of the inventory output (Phase 2b). Add an Icon column to the Item vocabulary table, sourced from the canonical tables (findings from the finding scheme; insight from Knowledge items).respond-to-review/SKILL.md: prefix the section headers with the icon (### FIXMEs 🚨,### Warnings ⚠️,### TODOs 📋,### Recommendations 🧠,### Suggestions ☝️,### Legacy 🔍) so the response document mirrors the review document it pairs with.summarize-chat/SKILL.md: continue using 💡 for important learnings, but add a link noting that 💡 is the canonical Insight icon defined in_data/artifact-conventions.md#knowledge-items.Acceptance criteria
_data/artifact-conventions.mdincludes an Icon column with the agreed icons.## Knowledge itemssection in_data/artifact-conventions.mddefinesI{n}/Insight/ 💡.review-criteria/SKILL.mdno longer duplicates the finding-scheme table, criteria, criticality mapping, or escalation chain; links to the canonical section instead. Warning Gate language is preserved in the canonical criteria.review-change/SKILL.mduses ☝️ for Suggestion in both output templates.wrap-up/SKILL.mdrenders finding and insight items with their icons in drive-by and inventory output, and its Item vocabulary table includes an Icon column.respond-to-review/SKILL.mdsection headers include the corresponding finding icons.summarize-chat/SKILL.mdreferences the canonical Insight icon definition.packages/agents/content/(every place that names a finding category still resolves correctly).