Applies CUPID properties (Composable, Unix philosophy, Predictable, Idiomatic, Domain-based) to structure code reviews and refactoring in any language beyond SOLID.
npx claudepluginhub habitat-thinking/ai-literacy-superpowers --plugin ai-literacy-superpowersThis skill uses the workspace's default tool permissions.
CUPID is a set of five properties — **C**omposable, **U**nix philosophy, **P**redictable, **I**diomatic, **D**omain-based — described by Daniel Terhorst-North as things good code *tends toward*, not rules it must comply with. That makes them ideal review lenses: you are asking "how strongly does this code exhibit this property?" and "what would moving it further in this direction look like?"
Evaluates code quality for complexity, readability, design principles, testability, maintainability, error handling, and code smells in reviews.
Applies universal code quality principles like KISS, DRY, single responsibility, descriptive naming, and clean code during writing or reviewing any code.
Provides code review guidelines on checks to perform, constructive feedback techniques, and comment standards for PRs and critiques.
Share bugs, ideas, or general feedback.
CUPID is a set of five properties — Composable, Unix philosophy, Predictable, Idiomatic, Domain-based — described by Daniel Terhorst-North as things good code tends toward, not rules it must comply with. That makes them ideal review lenses: you are asking "how strongly does this code exhibit this property?" and "what would moving it further in this direction look like?"
Use them as questions, not verdicts.
Code is composable when it can be combined with other code in many contexts without modification.
Review questions:
Refactoring signals:
Move toward: Smaller surface area. Dependencies injected. Works in isolation.
Not just single responsibility — the function does its one thing completely and well, with a clear, nameable purpose.
Review questions:
Refactoring signals:
Move toward: One clear responsibility. Name that earns no qualification. Flat abstraction level.
Given its name and context, the code behaves consistently, without surprises. Deterministic where possible. Fails loudly rather than silently.
Review questions:
Refactoring signals:
Move toward: Behaviour matches name. Side effects visible in signature. Loud failure.
Code that fits its language, ecosystem, and team conventions. A reader familiar with the context should not be surprised by the patterns used.
Review questions:
Refactoring signals:
Move toward: Follows the grain of the language. Uses established patterns. No surprises for the familiar reader.
The code uses the language of the business or problem domain. Names come from the domain, not from technical implementation details.
Review questions:
dataList vs invoices)?Refactoring signals:
data, item, manager, handler, util, helperUserRecord instead of CustomerMove toward: Names from the domain. Structure that reflects domain relationships. Code a domain expert could navigate.
| Property | Core question | Primary smell |
|---|---|---|
| Composable | Can I use this anywhere without baggage? | Hidden dependencies, large surface area |
| Unix | Does it do one thing, completely? | "and" in name, mixed abstraction levels |
| Predictable | Does it behave as its name suggests? | Hidden side effects, silent failure |
| Idiomatic | Does it feel natural here? | Reinventing the wheel, inconsistent patterns |
| Domain-based | Does it speak the domain's language? | Generic or technical names for business concepts |
Work through each property in turn for the code under review. For each one:
Avoid framing as pass/fail. The goal is: "this code is more Predictable than Composable — what would make it more Composable?"
When deciding where to start refactoring:
After completing a CUPID assessment, offer to add or update a CUPID Status section in the project's README. Do not add it automatically — offer it and let the user decide.
Add a shields.io static badge to the project's badge row (alongside CI and language badges) that links to the #cupid-status section. Update the date whenever the assessment is refreshed:
[](README.md#cupid-status)
The goldenrod colour (DAA520) is intentional — it matches the CUPID five-star rating aesthetic and is visually distinct from the green CI badges. The badge links directly to the status table in the same README.
If the project has a GitHub repository, ensure a CUPID assessed label exists for tagging PRs that include a CUPID review. Create it once with:
gh label create "CUPID assessed" --color "DAA520" --description "PR includes a CUPID code quality assessment" --repo <owner>/<repo>
Apply the label when opening a PR that includes a full CUPID review or a targeted CUPID-guided refactoring.
Add a ## CUPID Status section (or update it if already present) using this template:
## CUPID Status
Last assessed: YYYY-MM-DD
| Property | Strength | Top opportunity |
| --------- | -------- | --------------- |
| Composable | ★★★★☆ | Brief description |
| Unix philosophy | ★★★☆☆ | Brief description |
| Predictable | ★★★★★ | — |
| Idiomatic | ★★★☆☆ | Brief description |
| Domain-based | ★★★★☆ | Brief description |
Strength ratings: use ★ symbols on a 1–5 scale. A — in the opportunity column means no meaningful opportunity was identified.
Top opportunity: one sentence describing the single most impactful change for that property. Keep it specific enough to be actionable, not a restatement of the property definition.
Insert the section after any existing badges, overview, or quick-start content, and before detailed technical documentation. It should be easy to find at a glance — near the top, not buried at the bottom.
The badge belongs in the badge row at the very top of the README, after language/CI badges.
If the project uses a branch/PR workflow (e.g. a CLAUDE.md that requires working on branches), follow that workflow to add the addendum: create a branch, make the change, open a PR. Do not commit directly to main if the project convention says otherwise.