Skip to content

Use associated icons consistently when presenting and reporting findings #491

Description

@williamthorsen

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

  1. Add an Icon column to the canonical finding-scheme table in _data/artifact-conventions.md. Adopt 🚨 / ⚠️ / 📋 / 🧠 / ☝️ / 🔍 for FIXME / Warning / TODO / Recommendation / Suggestion / Legacy respectively.
  2. 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.
  3. 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).
  4. 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.
  5. 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).
  6. 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.
  7. 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

  • Canonical finding-scheme table in _data/artifact-conventions.md includes an Icon column with the agreed icons.
  • A ## Knowledge items section in _data/artifact-conventions.md defines I{n} / Insight / 💡.
  • review-criteria/SKILL.md no 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.md uses ☝️ for Suggestion in both output templates.
  • wrap-up/SKILL.md renders 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.md section headers include the corresponding finding icons.
  • summarize-chat/SKILL.md references the canonical Insight icon definition.
  • No regressions in finding-scheme references elsewhere in packages/agents/content/ (every place that names a finding category still resolves correctly).

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions