deep-research-scorecard

name	deep-research-scorecard
description	Use during deep research and tool comparisons to turn researched candidates into a weighted Σ/100 ranking, crown one winner, and explain why the winner beats the runner-up. Triggers: "score the candidates", "punkte vergeben", "Sieger küren", "weighted comparison", "100-point scorecard", "rank tools and pick a winner with justification".

deep-research-scorecard

deep-research-scorecard is a dependency-free ranking utility. Feed it a JSON spec with candidates, criteria, weights, and evidence-backed scores; it computes a weighted Σ/100, sorts candidates, and crowns one winner with a short rationale.

CLI: scorecard on PATH, or:

python3 ~/.claude/skills/deep-research-scorecard/scripts/scorecard.py

Install from the v0.1.0 source bundle:

git clone https://github.com/Martin-Hausleitner/interactive-deep-research.git
cd interactive-deep-research
git checkout v0.1.0
./install.sh

The installer copies this skill to ~/.claude/skills and links scorecard into ~/.local/bin by default. Override with CLAUDE_SKILLS_DIR or BIN_DIR if needed. There is no package-manager distribution for v0.1.0; use the tagged source checkout when reproducing a release install.

When To Use

Use this after research has identified credible candidates and decision criteria:

1. Define weighted criteria that reflect the user's actual decision.
2. Score each candidate from evidence on a 0..scale range.
3. Run scorecard spec.json for Markdown or scorecard spec.json --html for an embeddable fragment.
4. Include the weights in the final report; changing weights can change the winner.

JSON Spec

{
  "title": "Best open-source DE+EN voice cloning",
  "scale": 10,
  "criteria": [
    {"key": "de", "label": "German quality", "weight": 3},
    {"key": "license", "label": "Commercially usable", "weight": 3}
  ],
  "candidates": [
    {
      "name": "CosyVoice 3.0",
      "link": "https://github.com/FunAudioLLM/CosyVoice",
      "note": "Apache license; strong multilingual support.",
      "scores": {"de": 9, "license": 10}
    }
  ]
}

Commands

scorecard data/voice_scorecard.json
scorecard data/voice_scorecard.json --html > /tmp/scorecard.html
cat spec.json | scorecard -

Markdown output contains a ranked table and winner explanation. HTML output emits <table class="scorecard"> plus <div class="winner"> for local reports/sites.

Validation And Exit Behavior

• stdout is the rendered scorecard only.
• malformed JSON or an invalid spec exits non-zero with a concise stderr error.
• scale must be numeric and greater than 0.
• criteria must be a non-empty list with key, label, and numeric weight.
• criterion keys must be unique.
• at least one criterion weight must be positive; negative weights are rejected.
• candidates must be a non-empty list with name and scores.
• every score must be numeric and within 0..scale.
• score keys must match declared criteria.
• missing scores are allowed and treated as 0; use this deliberately.

Privacy / No PII

Use public, non-sensitive evidence in scorecard specs. Do not include private customer names, personal identifiers, credentials, account IDs, or proprietary research notes in note, link, or candidate names when the scorecard will be committed or rendered into a public report.

For vulnerability reporting and responsible-use boundaries, follow the repository SECURITY.md.

Failure Modes

Symptom	Cause	Fix
scorecard: error on stderr	Malformed JSON or invalid spec	Validate JSON and the documented schema.
Unexpected winner	Weights changed the decision	Revisit criteria weights with the human and rerun.
Score renders as 0	Criterion score is missing	Add the score deliberately or document the absence.
HTML fragment looks unstyled	Caller did not include report CSS	Embed in idr/proof-site report or provide table styles.

Guidance

• Scores should come from research evidence, not from the scorecard script.
• Keep criteria few and decision-relevant.
• Use askq if the human needs to confirm weights before ranking.
• Pair with integrative-deep-research when the report needs a decisive final recommendation instead of a loose comparison.