Scorecard Matrix

Scorecard Matrix

Generates a complete, self-contained HTML scorecard by (1) interviewing the user or parsing their data, (2) constructing and validating a JSON document, then (3) rendering that JSON into HTML using assets/scorecard-matrix-template.html. The JSON is the authoritative source of truth; the HTML is fully determined by it.

Step 1: Determine the Data Source

Check what the user has already provided before asking anything:

• SharePoint list or table: Parse all rows. Identify entities (the things being compared) and scoring columns (the dimensions).
• CSV or table pasted in chat: Extract entities, dimension names, and scores directly. Do not ask for data you already have.
• Verbal description only: Proceed to Step 2.

Step 2: Interview the User

If the data or intent is not fully clear, ask these questions in a single message — not one at a time:

1. What are you comparing? List the entities: vendors, tools, candidates, sites, products, options. (2–10 items.)
2. What are the criteria? List the dimensions you are scoring against: features, cost, fit, support, risk, readiness, etc. (2–10 items.)
3. Weights: How important is each dimension relative to the others? Can be given as percentages (must sum to 100%), ratios (e.g. 3:2:1), or plain priority ranking. The skill normalizes to decimals summing to 1.0.
4. Scores: For each entity × dimension cell: what is the score? Use whichever scale feels natural — the skill will ask you to confirm the scale (1–5 or 1–10). If scores come from data, extract them. If from judgment, prompt the user to rate each combination.
5. Cell notes: For any cell, is there a short phrase (under 6 words) that explains the score? Optional but valuable.
6. Context sentence: One or two sentences describing the decision being made, the audience, and the date or period.
7. Palette: Warm paper (cream/terra-cotta), deep ink (dark/gold), clean white (white/green), or slate (gray/blue)? Default to warm paper.

Confirm your understanding of the full matrix before building the JSON.

Step 3: Normalize Weights

Weights must sum to exactly 1.0. Apply these rules:

• Percentages given: divide each by 100. Check sum = 1.0. If not, normalize: w_i = raw_i / sum(raw).
• Ratios given (e.g. 3:2:2:1): w_i = ratio_i / sum(ratios).
• Priority ranking only: assign equal weight: w_i = 1 / N where N = number of dimensions.
• Weights already decimal: verify sum. If off by ≤ 0.01 due to rounding, adjust the largest weight to compensate.

Always document the normalized weights in the JSON and show the user before rendering.

Step 4: Choose the Scoring Scale

Default to 1–5 unless:

• The user provides scores already on a 1–10 scale, or
• There are 8+ dimensions and fine-grained differentiation matters.

When prompting the user to rate cells manually, describe each anchor:

• 1–5 scale: 1 = very poor fit, 3 = adequate, 5 = exceptional.
• 1–10 scale: 1 = unacceptable, 5 = meets minimum bar, 10 = best in class.

Step 5: Build and Validate the JSON Document

Construct the JSON object. Read references/components.md for the full schema and computation rules.

Top-level structure:

{
  "report": {
    "title": "CRM Platform Evaluation",
    "subtitle": "Q2 2026 · Vendor Selection",
    "context": "Evaluating five CRM platforms for the SMB sales team...",
    "palette": "warm-paper",
    "footer": "Generated May 28, 2026 · 5 vendors · 6 dimensions"
  },
  "scale": 5,
  "dimensions": [...],
  "entities": [...]
}

Computed fields (the skill must calculate these before rendering):

• weighted_total per entity = sum(score_d × weight_d) for all dimensions d
• rank per entity = 1-based position sorted by weighted_total descending; ties share the lower rank number
• column_avg per dimension = average score across all entities (round to 1 decimal)