borghei/Claude-Skills / business-operations/vendor-management
vendor-management
VerifiedVendor lifecycle — weighted selection scorecards, risk tiering, renewal and notice-deadline tracking, spend concentration, and SLA credits. Use when selecting a vendor, preparing a renewal, or reviewing a vendor portfolio.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.7 KB |
| assets/sample_portfolio.json | config | 3.6 KB |
| assets/sample_sla.json | config | 2.2 KB |
| assets/sample_vendor_candidates.json | config | 2.7 KB |
| assets/vendor-review-template.md | markdown | 3.1 KB |
| assets/vendor-selection-scorecard.md | markdown | 2.9 KB |
| references/renewal-negotiation-leverage.md | markdown | 10.1 KB |
| references/vendor-risk-tiering.md | markdown | 8.6 KB |
| scripts/portfolio_analyzer.py | script | 11.2 KB |
| scripts/sla_report.py | script | 10.5 KB |
| scripts/vendor_scorecard.py | script | 10.4 KB |
scripts/vendor_scorecard.py
View on GitHub#!/usr/bin/env python3
"""Score vendor candidates against weighted criteria with must-have gating.
Disqualifies candidates failing any must-have, computes weighted scores,
normalises cost into a value ratio, and runs a weight-sensitivity check so a
narrow win is not mistaken for a clear one.
Usage:
python3 vendor_scorecard.py --input sample_vendor_candidates.json
python3 vendor_scorecard.py --input sample_vendor_candidates.json --format json
"""
import argparse
import json
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional
# Score gap below this share of the leader's score is inside the noise floor of
# subjective scoring; treat the result as a tie and decide on other grounds.
TIE_THRESHOLD = 0.05
# Weight perturbation applied in the sensitivity check.
SENSITIVITY_SWING = 0.5
def validate(data: Dict[str, Any]) -> None:
"""Raise ValueError if criteria or vendor definitions are malformed."""
criteria = data.get("criteria", [])
vendors = data.get("vendors", [])
if not criteria:
raise ValueError("input JSON needs a non-empty 'criteria' array")
if not vendors:
raise ValueError("input JSON needs a non-empty 'vendors' array")
total_weight = sum(float(c.get("weight", 0)) for c in criteria)
if total_weight <= 0:
raise ValueError("criteria weights must sum to more than zero")
names = [c.get("name") for c in criteria]
if len(set(names)) != len(names):
raise ValueError("criterion names must be unique")
for v in vendors:
scores = v.get("scores", {})
missing = [n for n in names if n not in scores]
if missing:
raise ValueError(
f"vendor '{v.get('name')}' is missing scores for: {', '.join(missing)}"
)
for n in names:
s = float(scores[n])
if not 0 <= s <= 10:
raise ValueError(
f"vendor '{v.get('name')}' scored {s} on '{n}'; scores must be 0-10"
)
def weighted_score(vendor: Dict[str, Any], criteria: List[Dict[str, Any]]) -> float:
"""Return a vendor's weighted score normalised to a 0-100 scale."""
total_weight = sum(float(c.get("weight", 0)) for c in criteria)
raw = sum(
float(vendor["scores"][c["name"]]) * float(c.get("weight", 0)) for c in criteria
)
return raw / total_weight * 10.0
def disqualifications(vendor: Dict[str, Any], must_haves: List[str]) -> List[str]:
"""Return the must-have requirements this vendor fails."""
met = vendor.get("meets_must_haves", {})
return [m for m in must_haves if not met.get(m, False)]
def sensitivity_check(
vendors: List[Dict[str, Any]], criteria: List[Dict[str, Any]], leader: str
) -> List[Dict[str, Any]]:
"""Re-score with each criterion's weight swung up and down; report leader flips."""
flips: List[Dict[str, Any]] = []
for target in criteria:
for direction, factor in (("up", 1 + SENSITIVITY_SWING), ("down", 1 - SENSITIVITY_SWING)):
adjusted = [
{**c, "weight": float(c.get("weight", 0)) * (factor if c is target else 1.0)}
for c in criteria
]
ranked = sorted(
vendors, key=lambda v: weighted_score(v, adjusted), reverse=True
)
if ranked and ranked[0]["name"] != leader:
flips.append(
{
"criterion": target["name"],
"direction": direction,
"new_leader": ranked[0]["name"],
}
)
return flips
def analyse(data: Dict[str, Any]) -> Dict[str, Any]:
"""Score all candidates, gate on must-haves, and test the result's stability."""
validate(data)
criteria = data.get("criteria", [])
must_haves = data.get("must_haves", [])
total_weight = sum(float(c.get("weight", 0)) for c in criteria)
scored: List[Dict[str, Any]] = []
for v in data["vendors"]:
failures = disqualifications(v, must_haves)
score = weighted_score(v, criteria)
cost = float(v.get("annual_cost", 0))
scored.append(
{
"name": v.get("name", "unnamed"),
"weighted_score": round(score, 2),
"annual_cost": cost,
"value_ratio": round(score / (cost / 100000), 2) if cost else None,
"disqualified": bool(failures),
"failed_must_haves": failures,
"scores": {c["name"]: float(v["scores"][c["name"]]) for c in criteria},
"notes": v.get("notes", ""),
}
)
qualified = [s for s in scored if not s["disqualified"]]
qualified.sort(key=lambda s: -s["weighted_score"])
scored.sort(key=lambda s: (s["disqualified"], -s["weighted_score"]))
findings: List[str] = []
recommendation: Optional[Dict[str, Any]] = None
flips: List[Dict[str, Any]] = []
if not qualified:
findings.append(
"Every candidate fails at least one must-have. Either the must-have list is "
"aspirational, or this market cannot serve the requirement — revisit before re-running."
)
else:
leader = qualified[0]
raw_vendors = [v for v in data["vendors"] if v.get("name") in {q["name"] for q in qualified}]
flips = sensitivity_check(raw_vendors, criteria, leader["name"])
if len(qualified) > 1:
runner_up = qualified[1]
gap = (leader["weighted_score"] - runner_up["weighted_score"]) / leader["weighted_score"]
if gap < TIE_THRESHOLD:
margin = (
"score identically"
if gap == 0
else f"are separated by only {gap:.1%}"
)
findings.append(
f"{leader['name']} and {runner_up['name']} {margin} — inside the noise floor "
"of subjective scoring. Treat as a tie and decide on commercial terms, exit "
"cost, or reference checks."
)
if runner_up["annual_cost"] and leader["annual_cost"] > runner_up["annual_cost"] * 1.3:
findings.append(
f"{leader['name']} costs {leader['annual_cost'] / runner_up['annual_cost']:.1f}x "
f"{runner_up['name']} for a {gap:.1%} score advantage. Confirm the delta is "
"worth the premium before committing."
)
if flips:
criteria_flipped = sorted({f["criterion"] for f in flips})
findings.append(
f"Result is weight-sensitive: the leader changes if weighting on "
f"{', '.join(criteria_flipped)} moves by 50%. Re-confirm those weights with the "
"decision owner before proceeding."
)
else:
findings.append(
"Result is stable under a 50% swing on every criterion weight."
)
recommendation = {
"vendor": leader["name"],
"weighted_score": leader["weighted_score"],
"annual_cost": leader["annual_cost"],
"stable": not flips,
}
dq = [s for s in scored if s["disqualified"]]
for d in dq:
findings.append(
f"{d['name']} disqualified on: {', '.join(d['failed_must_haves'])}."
)
return {
"decision": data.get("decision", "vendor selection"),
"criteria": [
{"name": c["name"], "weight": float(c.get("weight", 0)),
"weight_share": round(float(c.get("weight", 0)) / total_weight, 3)}
for c in criteria
],
"must_haves": must_haves,
"vendors": scored,
"qualified_count": len(qualified),
"sensitivity_flips": flips,
"recommendation": recommendation,
"findings": findings,
}
def output(result: Dict[str, Any], fmt: str) -> None:
"""Print the scorecard as JSON or a human-readable report."""
if fmt == "json":
print(json.dumps(result, indent=2))
return
print(f"VENDOR SCORECARD — {result['decision']}")
print("=" * 76)
print("Criteria: " + ", ".join(f"{c['name']} ({c['weight_share']:.0%})" for c in result["criteria"]))
if result["must_haves"]:
print("Must-haves: " + ", ".join(result["must_haves"]))
print()
print(f"{'Vendor':<26}{'Score':>8}{'Annual cost':>14}{'Value':>9} Status")
print("-" * 76)
for v in result["vendors"]:
status = "DISQUALIFIED" if v["disqualified"] else "qualified"
value = f"{v['value_ratio']:.1f}" if v["value_ratio"] is not None else "n/a"
print(
f"{v['name'][:25]:<26}{v['weighted_score']:>8.1f}{v['annual_cost']:>14,.0f}"
f"{value:>9} {status}"
)
print("-" * 76)
print("Score is 0-100 weighted. Value = score per 100k of annual cost.")
if result["recommendation"]:
r = result["recommendation"]
print()
print("RECOMMENDATION")
print(
f" {r['vendor']} — score {r['weighted_score']:.1f} at {r['annual_cost']:,.0f}/year "
f"({'stable' if r['stable'] else 'weight-sensitive'} result)"
)
if result["findings"]:
print()
print("FINDINGS")
for f in result["findings"]:
print(f" ! {f}")
def main() -> None:
"""Parse arguments, score the candidates, and print the result."""
parser = argparse.ArgumentParser(
description="Score vendor candidates against weighted criteria with must-have gating.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser.add_argument(
"--input",
required=True,
help="Path to a candidates JSON file (see assets/sample_vendor_candidates.json)",
)
parser.add_argument(
"--format", choices=["text", "json"], default="text", help="Output format"
)
args = parser.parse_args()
try:
data = json.loads(Path(args.input).read_text(encoding="utf-8"))
output(analyse(data), args.format)
except FileNotFoundError:
print(f"Error: input file not found: {args.input}", file=sys.stderr)
sys.exit(1)
except json.JSONDecodeError as exc:
print(f"Error: {args.input} is not valid JSON ({exc})", file=sys.stderr)
sys.exit(1)
except (ValueError, KeyError, TypeError) as exc:
print(f"Error: could not score vendors — {exc}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |