review-scorecard

name	review-scorecard
description	Defines the standard scorecard and table of contents format for Companion module reviews. Use when assembling the final review file to generate the 📊 Scorecard section (issue counts by severity with New vs. Existing columns) and 📋 Table of Contents section (clickable anchor links to each finding).

Review Scorecard & Table of Contents

Defines the standard format for the two sections inserted immediately after the Verdict in every assembled review.

When to Use This Skill

• When assembling the final review file from all agents' findings
• When computing New vs. Existing issue counts per severity level
• When generating a Table of Contents with anchor links to each finding
• When a review needs retroactive formatting

---

⚠️ CRITICAL: Review File Output Location

Read project-conventions skill before writing the review file.

Final review files MUST be written to this repo's reviews/ directory — NOT the module's folder.

reviews/{short-module-name}/review-{short-module-name}-{version}-{YYYYMMDD}-{HHmmss}.md

• short-module-name = module folder name with companion-module- prefix stripped
• Timestamp from: date -u +"%Y%m%d-%H%M%S"
• Create subdirectory if needed: mkdir -p reviews/{short-module-name}/

❌ WRONG: writing a review file inside the module clone (companion-modules-reviewing/companion-module-*/review-*.md)
✅ RIGHT: reviews/{short-module-name}/review-*.md in this repo

---

Section 1: 📊 Scorecard

Insert this section immediately after the Verdict section.

Issue Counting Rules

Column definitions:

• 🆕 New — findings classified as 🆕 NEW or 🔙 REGRESSION anywhere in the review
• ⚠️ Existing — findings classified as ⚠️ PRE-EXISTING anywhere in the review, including items in the ## ⚠️ Pre-existing Notes table
• Total — sum of New + Existing for that severity row

Severity rows to include: Always include Critical through Low. Include "Nice to Have" only if there are findings at that level.

Blocking count: Count all findings in the ## 🔴 Critical and ## 🟠 High main sections. Pre-existing issues in those main sections still block per review policy. Do NOT count the ⚠️ Pre-existing Notes table entries as blocking — those are explicitly non-blocking. This "blocking" determination drives the 📋 Issues Blocking/Non-blocking grouping and the Verdict; it is not printed as a scorecard line.

Scorecard Template

## 📊 Scorecard

| Severity | 🆕 New | ⚠️ Existing | Total |
|----------|--------|-------------|-------|
| 🔴 Critical | {n} | {n} | {n} |
| 🟠 High | {n} | {n} | {n} |
| 🟡 Medium | {n} | {n} | {n} |
| 🟢 Low | {n} | {n} | {n} |
| 💡 Nice to Have | {n} | {n} | {n} |
| **Total** | **{n}** | **{n}** | **{n}** |

Omit the "Nice to Have" row if there are no findings at that level.

Verdict Format

The Verdict section (immediately before the Scorecard in the assembled review) contains only the status line — no reasoning or "Reason:" paragraph:

## Verdict: ❌ Changes Required

or

## Verdict: ✅ Approved

Example — Changes Required with pre-existing blocking issues

## 📊 Scorecard

| Severity | 🆕 New | ⚠️ Existing | Total |
|----------|--------|-------------|-------|
| 🔴 Critical | 0 | 0 | 0 |
| 🟠 High | 0 | 3 | 3 |
| 🟡 Medium | 0 | 0 | 0 |
| 🟢 Low | 1 | 0 | 1 |
| 💡 Nice to Have | 1 | 0 | 1 |
| **Total** | **2** | **3** | **5** |

Example — Changes Required with new critical issue

## 📊 Scorecard

| Severity | 🆕 New | ⚠️ Existing | Total |
|----------|--------|-------------|-------|
| 🔴 Critical | 1 | 0 | 1 |
| 🟠 High | 0 | 2 | 2 |
| 🟡 Medium | 3 | 3 | 6 |
| 🟢 Low | 3 | 4 | 7 |
| **Total** | **7** | **9** | **16** |

---

Section 2: 📋 Table of Contents

Insert this section immediately after the Scorecard section.

TOC Rules

• Include every finding with a heading in the main review body (Critical through Nice to Have sections)
• Group as Blocking / Non-blocking — Blocking = items from 🔴 Critical and 🟠 High main sections; Non-blocking = everything else
• Omit the Pre-existing Notes table entries — they don't have individual headings to link to
• If there are no blocking issues, omit the Blocking group header (or write *(none)*)
• If there are no non-blocking issues, omit the Non-blocking group header

Anchor Generation (GitHub Markdown Rules)

To generate the anchor for a heading:

1. Lowercase the entire heading text
2. Remove everything that is NOT: letters, digits, spaces, hyphens
3. Replace one or more consecutive spaces/hyphens/underscores with a single hyphen (they collapse — — surrounded by spaces becomes one -, not two)
4. Backtick content keeps its inner text (backticks themselves are removed)
5. Emoji characters and their variation selectors are removed
6. Special characters removed: : ( ) — . @ / ' ` ! ?

⚠️ Avoid emoji in issue headings. Emoji followed by spaces produce ambiguous anchor output across different Markdown renderers (the number of hyphens generated is not consistent). Keep emoji in section-level headings (e.g., ## 🔴 Critical) but use plain text in issue headings (### H1:, ### C1:, etc.). Classification metadata like "pre-existing" belongs in the **Classification:** line below the heading, not in the heading text itself.

Anchor Examples

Heading	Anchor
### C1: \clearIdleTimer()` called in Reconnect action — method does not exist`	#c1-clearidletimer-called-in-reconnect-action-method-does-not-exist
### H1: EventSource not closed in \destroy()``	#h1-eventsource-not-closed-in-destroy
### M3: \@companion-module/base` version doesn't satisfy peer dependency`	#m3-companion-modulebase-version-doesnt-satisfy-peer-dependency
### L1: Build script \rimraf dist` removal may leave stale files`	#l1-build-script-rimraf-dist-removal-may-leave-stale-files
### N1: Unused import in \upgrades.ts``	#n1-unused-import-in-upgradests

TOC Template

Each item is a GitHub-flavored Markdown task list item (- [ ]). On a re-review, mark an item - [x] once the maintainer has addressed it in the resubmitted version.

## 📋 Issues

**Blocking**
- [ ] [C1: Issue title here](#c1-anchor-here)
- [ ] [H1: Issue title here](#h1-anchor-here)

**Non-blocking**
- [ ] [M1: Issue title here](#m1-anchor-here)
- [ ] [L1: Issue title here](#l1-anchor-here)
- [ ] [N1: Issue title here](#n1-anchor-here)

---

Updated Section Order in Assembled Review

1. Title + meta header
2. 📊 Scorecard ← this skill
3. Verdict
4. 📋 Issues ← this skill (formerly "Table of Contents")
5. 🔴 Critical
6. 🟠 High
7. 🟡 Medium
8. 🟢 Low
9. 💡 Nice to Have
10. 🔮 Next Release
11. ⚠️ Pre-existing Notes
12. 🧪 Tests (only when tests are present; omit entirely if none found)

The Verdict (item 3) is the status line only — no reasoning paragraph (see "Verdict Format" above).

Omit any section that has no findings.