How do I install the Pragmatism Audit skill?

Run npx skillmds@latest add ronniepinnell/pragmatism-audit in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Pragmatism Audit safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Pragmatism Audit?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Pragmatism Audit free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Pragmatism Audit?

ronniepinnell (@ronniepinnell) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Pragmatism Audit by ronniepinnell — Agent Skill

Name: Pragmatism Audit
Author: ronniepinnell

Pragmatism Audit

Over-engineering review. Examines recently written code for complexity that the project's actual scale and needs don't justify, and proposes the smallest design that still works. Use after implementing a feature or making an architectural decision, before completion review.

ronniepinnell Updated Sep 17, 2026

File contents

/pragmatism-audit — Is All This Complexity Earning Its Keep?

The orienting question for every abstraction, layer, and dependency: what breaks if this is deleted? Anything that can be removed or flattened without losing essential behavior should be. Complexity is judged against the project's ACTUAL scale (MVP vs enterprise), not against theoretical best practice.

Report format, ruling grammar, severity tiers, JSON trailer, degradation rules, and routing table: see _shared/audit-report-contract.md.

Invocation

/pragmatism-audit                    # review recent changes
/pragmatism-audit src/cache/         # review an area or decision

Procedure

Establish the scale context. Read the project brief/context (.claude/project-context.md, plan docs) for actual requirements, users, and load. Complexity proportional to a need that exists is fine.
Sweep the changed code for the complexity classes: abstraction stacks and wrappers around simple logic; enterprise infrastructure (caching layers, resilience frameworks, heavy middleware) with no demonstrated need; premature abstraction, speculative flags, compatibility shims for code nothing uses; a heavier tech choice where a simpler one meets the requirement; process/tooling overhead disproportionate to project size; decisions contradicting earlier banked decisions (check the decision log via the storage adapter); dependency/version mismatches causing avoidable friction; blind spec-following where a practical adaptation was warranted.
Test each candidate by deletion. The ruling grammar applies: CONFIRMED over-engineering (the simpler form demonstrably suffices — show it), REFUTED (the complexity is justified; say why), UNVERIFIED. Every finding: severity tier, file:line, code evidence.
Rank and propose. Overall complexity rating (low/medium/high) with justification; the top ~5 most impactful problems; a concrete simplification per problem with before/after sketches where useful; the highest-leverage 1–3 called out as priority actions.
Report: the above plus the JSON trailer (findings are a subtype of the shared schema so /completion-audit can consume them), verdict line logged via /verdict:

AUDIT: pragmatism-audit | <scope> | <pass|fail|inconclusive> | <blocking>/<total> findings

Rules

Deletion proposals must preserve essential behavior — prove it or mark the proposal UNVERIFIED and route to /validate-completion after the cut.
Complexity mandated by a spec is challenged at the spec (route: spec-audit), not silently ripped out; rule-mandated structure is not a finding (route conflicts: rules-audit).
Under-engineering is out of scope here — fragility findings route to completion-audit / validate-completion.

Judgment weave

Each "is this justified?" call on a big design is /door material; log the keep/cut adjudications to /verdict and reuse them via /precedent.
A simplification estimated > 2× its claimed effort gets a /gate before anyone starts it.

Composes with

/completion-audit — over-engineering is one of its gap types; it consumes this trailer.
/simplify — applies fixes; this audit decides which fixes are worth it.
/altitude — recurring complexity in one layer usually means the problem lives at another.

---name: pragmatism-auditdescription: Over-engineering review. Examines recently written code for complexity that the project's actual scale and needs don't justify, and proposes the smallest design that still works. Use after implementing a feature or making an architectural decision, before completion review.---# /pragmatism-audit — Is All This Complexity Earning Its Keep?The orienting question for every abstraction, layer, and dependency: whatbreaks if this is deleted? Anything that can be removed or flattened withoutlosing essential behavior should be. Complexity is judged against theproject's ACTUAL scale (MVP vs enterprise), not against theoretical bestpractice.Report format, ruling grammar, severity tiers, JSON trailer, degradationrules, and routing table: see `_shared/audit-report-contract.md`.## Invocation```/pragmatism-audit # review recent changes/pragmatism-audit src/cache/ # review an area or decision```## Procedure1. **Establish the scale context.** Read the project brief/context (`.claude/project-context.md`, plan docs) for actual requirements, users, and load. Complexity proportional to a need that exists is fine.2. **Sweep the changed code for the complexity classes:** abstraction stacks and wrappers around simple logic; enterprise infrastructure (caching layers, resilience frameworks, heavy middleware) with no demonstrated need; premature abstraction, speculative flags, compatibility shims for code nothing uses; a heavier tech choice where a simpler one meets the requirement; process/tooling overhead disproportionate to project size; decisions contradicting earlier banked decisions (check the decision log via the storage adapter); dependency/version mismatches causing avoidable friction; blind spec-following where a practical adaptation was warranted.3. **Test each candidate by deletion.** The ruling grammar applies: CONFIRMED over-engineering (the simpler form demonstrably suffices — show it), REFUTED (the complexity is justified; say why), UNVERIFIED. Every finding: severity tier, file:line, code evidence.4. **Rank and propose.** Overall complexity rating (low/medium/high) with justification; the top ~5 most impactful problems; a concrete simplification per problem with before/after sketches where useful; the highest-leverage 1–3 called out as priority actions.5. **Report:** the above plus the JSON trailer (findings are a subtype of the shared schema so `/completion-audit` can consume them), verdict line logged via `/verdict`:```AUDIT: pragmatism-audit | <scope> | <pass|fail|inconclusive> | <blocking>/<total> findings```## Rules- Deletion proposals must preserve essential behavior — prove it or mark the proposal UNVERIFIED and route to `/validate-completion` after the cut.- Complexity mandated by a spec is challenged at the spec (route: spec-audit), not silently ripped out; rule-mandated structure is not a finding (route conflicts: rules-audit).- Under-engineering is out of scope here — fragility findings route to completion-audit / validate-completion.## Judgment weave- Each "is this justified?" call on a big design is `/door` material; log the keep/cut adjudications to `/verdict` and reuse them via `/precedent`.- A simplification estimated > 2× its claimed effort gets a `/gate` before anyone starts it.## Composes with- `/completion-audit` — over-engineering is one of its gap types; it consumes this trailer.- `/simplify` — applies fixes; this audit decides which fixes are worth it.- `/altitude` — recurring complexity in one layer usually means the problem lives at another.

Frequently asked questions