CUPID Checker
A skill for reviewing code against Dan North's five CUPID properties for joyful coding.
What is CUPID?
CUPID is a set of properties (not rules) that describe code that is a joy to work with. Code is never "CUPID compliant" or not — it is simply closer to or further from each property's centre. The five properties are:
| Letter |
Property |
One-liner |
| C |
Composable |
Plays well with others |
| U |
Unix philosophy |
Does one thing well |
| P |
Predictable |
Does what you expect |
| I |
Idiomatic |
Feels natural |
| D |
Domain-based |
Solution domain models the problem domain |
Read the full reference in references/cupid-properties.md for detailed sub-dimensions of each property.
Review Workflow
Step 1 — Understand Context
Before assessing, establish:
- Language / framework (affects Idiomatic assessment)
- Purpose of the code (affects Unix philosophy and Domain-based assessment)
- Team context (affects Local idioms under Idiomatic)
- Scope — single function, module, whole codebase?
If the user hasn't provided this context, ask briefly (one question is enough to get started).
Step 2 — Assess Each Property
For each of the five CUPID properties, produce an assessment section:
### C — Composable
**Rating:** 🟢 Strong / 🟡 Moderate / 🔴 Weak
**Observations:** What you notice (concrete, code-referenced)
**Suggestions:** How to move towards the centre
Use the sub-dimensions in references/cupid-properties.md as your lens. Always cite specific line numbers, function names, or patterns in the code — never give generic advice that could apply to any codebase.
Step 3 — Overall Summary
After all five properties, provide:
- A brief synthesis (2–4 sentences) of the overall picture
- The top 1–3 highest-leverage improvements — the changes most likely to positively affect multiple properties at once (since properties are mutually reinforcing)
- A note on what the code already does well — CUPID is about moving towards a centre, not tearing code apart
Step 4 — Optional: Refactoring Sketch
If the user wants to see improvements, offer a concrete refactoring sketch (not a full rewrite) demonstrating one or two of the highest-leverage changes. Keep it focused.
Tone and Framing
CUPID is explicitly not about rules or compliance. Frame all feedback as:
- Direction of travel, not pass/fail
- Trade-offs acknowledged — "more composable but at the cost of X"
- Respect for existing choices — assume earlier programmers made reasonable decisions in context
Avoid language like "this violates X" or "you must Y". Prefer: "moving towards more composable code might involve…", "one way to increase predictability here…".
Quick Reference: What to Look For
| Property |
Green flags |
Red flags |
| Composable |
Narrow focused API, clear intent from name/signature, few imports |
God objects, broad catch-all APIs, deep dependency trees |
| Unix philosophy |
One clear purpose, can describe in one sentence, no surprise side effects |
Does multiple unrelated things, hard to summarise purpose |
| Predictable |
Deterministic outputs, easy to test, observable (logs/metrics built in), handles edge cases visibly |
Hidden state, silent failures, non-deterministic behaviour, hard to test |
| Idiomatic |
Looks like other code in this language/codebase, uses standard library patterns, consistent naming |
Mixed paradigms, reinventing built-ins, inconsistent style |
| Domain-based |
Code reads like domain conversation, types named after domain concepts, structure mirrors use-cases |
CS-speak names (HashMap, Controller, Manager), structure mirrors framework not domain |
Read On Demand
references/cupid-properties.md — Full detail on each property's sub-dimensions + example review output; read when you need depth on a specific property
Benchmark
Scenario: .benchmarks/scenarios/cupid-checker-001-review.md
| Model |
Without |
With |
Delta |
| claude-opus-4-8 |
75% |
100% |
+25% |
| claude-sonnet-4-6 |
63% |
100% |
+37% |
| claude-haiku-4-5 |
75% |
100% |
+25% |
PASS (run 2026-06-25). Uniform gains (+25 to +37). Skill enforces the mandated 5-property output shape (per-property rating + observations + suggestions) that baselines skip. Gate per .agents/skills/skill-optimizer/rules/release-gates.md.
1---2name: cupid-checker3description: Review code against the CUPID properties for joyful coding: Composable, Unix philosophy, Predictable, Idiomatic, and Domain-based. Use this skill whenever the user wants to assess code quality using CUPID, asks "is this code CUPID?", wants a code review framed around CUPID principles, mentions any of the five CUPID properties by name, asks how to make code more joyful or habitable, or wants to refactor/improve code using Dan North's CUPID framework. Also trigger when the user pastes code and asks for feedback on structure, naming, dependencies, predictability, or domain alignment — even if they don't explicitly mention CUPID. DO NOT USE when: user wants specific refactoring techniques for code smells — use `refactoring` instead. DO NOT USE when: user wants SOLID principle analysis — use `object-oriented-programming` instead.4---56# CUPID Checker78A skill for reviewing code against Dan North's five CUPID properties for joyful coding.910## What is CUPID?1112CUPID is a set of **properties** (not rules) that describe code that is a joy to work with. Code is never "CUPID compliant" or not — it is simply closer to or further from each property's centre. The five properties are:1314| Letter | Property | One-liner |15| ------ | --------------- | ----------------------------------------- |16| **C** | Composable | Plays well with others |17| **U** | Unix philosophy | Does one thing well |18| **P** | Predictable | Does what you expect |19| **I** | Idiomatic | Feels natural |20| **D** | Domain-based | Solution domain models the problem domain |2122Read the full reference in `references/cupid-properties.md` for detailed sub-dimensions of each property.2324---2526## Review Workflow2728### Step 1 — Understand Context2930Before assessing, establish:3132- **Language / framework** (affects Idiomatic assessment)33- **Purpose of the code** (affects Unix philosophy and Domain-based assessment)34- **Team context** (affects Local idioms under Idiomatic)35- **Scope** — single function, module, whole codebase?3637If the user hasn't provided this context, ask briefly (one question is enough to get started).3839### Step 2 — Assess Each Property4041For each of the five CUPID properties, produce an assessment section:4243```44### C — Composable45**Rating:** 🟢 Strong / 🟡 Moderate / 🔴 Weak46**Observations:** What you notice (concrete, code-referenced)47**Suggestions:** How to move towards the centre48```4950Use the sub-dimensions in `references/cupid-properties.md` as your lens. Always cite specific line numbers, function names, or patterns in the code — never give generic advice that could apply to any codebase.5152### Step 3 — Overall Summary5354After all five properties, provide:5556- A brief synthesis (2–4 sentences) of the overall picture57- The **top 1–3 highest-leverage improvements** — the changes most likely to positively affect multiple properties at once (since properties are mutually reinforcing)58- A note on what the code already does _well_ — CUPID is about moving towards a centre, not tearing code apart5960### Step 4 — Optional: Refactoring Sketch6162If the user wants to see improvements, offer a concrete refactoring sketch (not a full rewrite) demonstrating one or two of the highest-leverage changes. Keep it focused.6364---6566## Tone and Framing6768CUPID is explicitly _not_ about rules or compliance. Frame all feedback as:6970- **Direction of travel**, not pass/fail71- **Trade-offs acknowledged** — "more composable but at the cost of X"72- **Respect for existing choices** — assume earlier programmers made reasonable decisions in context7374Avoid language like "this violates X" or "you must Y". Prefer: "moving towards more composable code might involve…", "one way to increase predictability here…".7576---7778## Quick Reference: What to Look For7980| Property | Green flags | Red flags |81| ------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |82| **Composable** | Narrow focused API, clear intent from name/signature, few imports | God objects, broad catch-all APIs, deep dependency trees |83| **Unix philosophy** | One clear purpose, can describe in one sentence, no surprise side effects | Does multiple unrelated things, hard to summarise purpose |84| **Predictable** | Deterministic outputs, easy to test, observable (logs/metrics built in), handles edge cases visibly | Hidden state, silent failures, non-deterministic behaviour, hard to test |85| **Idiomatic** | Looks like other code in this language/codebase, uses standard library patterns, consistent naming | Mixed paradigms, reinventing built-ins, inconsistent style |86| **Domain-based** | Code reads like domain conversation, types named after domain concepts, structure mirrors use-cases | CS-speak names (HashMap, Controller, Manager), structure mirrors framework not domain |8788---8990## Read On Demand9192- `references/cupid-properties.md` — Full detail on each property's sub-dimensions + example review output; read when you need depth on a specific property9394---9596## Benchmark9798Scenario: `.benchmarks/scenarios/cupid-checker-001-review.md`99100| Model | Without | With | Delta |101| ----------------- | ------- | ---- | ----- |102| claude-opus-4-8 | 75% | 100% | +25% |103| claude-sonnet-4-6 | 63% | 100% | +37% |104| claude-haiku-4-5 | 75% | 100% | +25% |105106> **PASS** (run 2026-06-25). Uniform gains (+25 to +37). Skill enforces the mandated 5-property output shape (per-property rating + observations + suggestions) that baselines skip. Gate per `.agents/skills/skill-optimizer/rules/release-gates.md`.
bsene