{"id":"c5cf0a3c-8fd6-4862-99aa-1ac28b744301","shortId":"F8DAKw","kind":"skill","title":"audit-necessity","tagline":"Use when cutting code in a folder that doesn't earn its keep — whether a solution is over-engineered, where maintenance cost can be reduced, or where a feature should be removed entirely.","description":"target_path = $ARGUMENTS\n\nIf no target path provided, ask for one. This skill requires a concrete scope — \"the whole repo\" produces shallow findings.\n\n## Purpose\n\nEvery line of code is a liability — read, understood, maintained, debugged, migrated. This skill makes maintenance cost visible and cuts code that doesn't earn its keep.\n\nThis is not a correctness review or a style review. The question: **should this code exist at all, and if so, at this size?**\n\n## Reconnaissance\n\nBefore spawning reviewers, build the brief they all share:\n\n1. Map the scope — file count, total LOC, directory structure, entry points\n2. Identify the feature set — what user-facing capabilities does this code provide? List concretely.\n3. Detect the stack — languages, frameworks, key dependencies\n4. Find existing docs — any stated purpose or architecture rationale\n\n## Teammates\n\nSpawn all three from `${CLAUDE_SKILL_DIR}/agents/` **in parallel**. All are **read-only** — analysis only, no edits. Each gets the full brief plus all file paths in the target.\n\n| Teammate | Agent file | Lens |\n|----------|-----------|------|\n| YAGNI Enforcer | `yagni.md` | What here solves a problem nobody actually has? |\n| Cost Auditor | `cost-auditor.md` | What's the maintenance burden vs. the value delivered? |\n| Alternatives Scout | `alternatives.md` | What existing libraries, services, or simpler architectures could replace this? |\n\n## Synthesis\n\n### Credibility Filter\n\nDiscard findings that fail any of these:\n\n- **Evidence-based** — references specific files, line counts, complexity metrics, or usage patterns. Speculation is not a finding.\n- **Proportionate** — a 30-line utility being \"unnecessary\" isn't worth reporting; a 500-line abstraction wrapping a 10-line operation is. The model's instinct is to report everything it finds — resist this. Only surface findings where the cost/value mismatch is material.\n- **Alternative-bearing** — \"delete this\" is not actionable. \"Replace this 400-line custom parser with `{library}`\" is.\n- **Honest about migration cost** — removing/replacing code has a cost too. Acknowledge it.\n\nDiscard findings where the reviewer misunderstood the feature's purpose. Discard findings about code that's necessary but could be slightly shorter — that's refactoring territory, not this skill's job.\n\n### Severity & action\n\n| Level | Meaning | Action |\n|-------|---------|--------|\n| **CUT-internal** | Maintenance cost clearly exceeds value, no user-facing capability removed (dead code, unused abstraction, internal helper). | Auto-apply. |\n| **CUT-user-facing** | Removes an endpoint, tool, CLI command, public API, or feature users can call. | Surface for sign-off — usage outside the codebase can't be verified from inside it. |\n| **SHRINK** | Feature is justified but implementation is 3-10x larger than necessary. Behavior preserved. | Auto-apply. |\n| **QUESTION** | Unclear whether this earns its keep. Needs user context — state the specific question. | Surface, do not edit. |\n| **KEEP** | Reviewers challenged it and it survived. Note what was challenged and why it stood — this builds trust that the review is fair, not just aggressive. | No action. |\n\n## Acting\n\nRun tests first. If they fail, stop — cutting requires a passing baseline.\n\nApply SHRINK and CUT-internal in one pass. Fix all import references; run lint + tests after the batch.\n\nDo not act on CUT-user-facing or QUESTION items. List them in the report for the user's call.\n\n### Report Structure\n\n1. **Scope summary** — what was reviewed (files, LOC, features)\n2. **Headline** — one sentence: lean, reasonable, or bloated?\n3. **Applied** — `git diff --stat`, the SHRINK and CUT-internal changes, reduction percentage\n4. **Awaiting sign-off** — CUT-user-facing list with alternatives and estimated LOC reduction\n5. **QUESTION list** — what needs user context (state the specific question)\n6. **KEEP list** — what survived the challenge\n7. **If starting fresh** — knowing what we know now, what's the minimal architecture delivering the same capabilities?\n\n### Failure Modes\n\n- **Drive-by severity inflation.** The model tends to rate everything CUT or SHRINK to look thorough. A report with zero KEEP items signals the review failed, not that the code is bad. Calibrate: most well-maintained codebases have more KEEP than CUT.\n- **Ignoring migration cost.** \"Replace with library X\" sounds clean until you account for the API surface, test rewrite, and behavior differences. Every recommendation must acknowledge what the switch costs.\n- **Misreading domain code as over-engineering.** Domain-specific abstractions (workflow engines, rule systems, protocol handlers) look like speculative architecture to a generalist reviewer. When code serves a domain you don't fully understand, classify as QUESTION, not CUT.","tags":["audit","necessity","dotclaude","jhostalek","agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli"],"capabilities":["skill","source-jhostalek","skill-audit-necessity","topic-agent-skills","topic-ai-coding","topic-anthropic","topic-claude","topic-claude-code","topic-claude-code-skills","topic-code-review","topic-codex-cli","topic-cursor","topic-developer-tools","topic-git-workflow","topic-multi-agent"],"categories":["dotclaude"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JHostalek/dotclaude/audit-necessity","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JHostalek/dotclaude","source_repo":"https://github.com/JHostalek/dotclaude","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (4,796 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:14.722Z","embedding":null,"createdAt":"2026-05-18T13:20:30.753Z","updatedAt":"2026-05-18T19:13:14.722Z","lastSeenAt":"2026-05-18T19:13:14.722Z","tsv":"'-10':440 '/agents':177 '1':123,551 '10':286 '2':135,560 '3':151,439,568 '30':271 '4':159,582 '400':321 '5':598 '500':281 '6':609 '7':616 'abstract':283,393,719 'account':691 'acknowledg':338,704 'act':496,530 'action':318,372,375,495 'actual':214 'agent':202 'aggress':493 'altern':228,312,593 'alternative-bear':311 'alternatives.md':230 'analysi':185 'api':410,694 'appli':398,449,509,569 'architectur':167,237,629,729 'argument':40 'ask':46 'audit':2 'audit-necess':1 'auditor':217 'auto':397,448 'auto-appli':396,447 'await':583 'bad':668 'base':253 'baselin':508 'batch':527 'bear':313 'behavior':445,699 'bloat':567 'brief':119,193 'build':117,484 'burden':223 'calibr':669 'call':415,548 'capabl':144,388,633 'challeng':470,478,615 'chang':579 'classifi':744 'claud':174 'clean':688 'clear':381 'cli':407 'code':7,65,82,103,147,333,353,391,666,711,735 'codebas':424,674 'command':408 'complex':259 'concret':53,150 'context':459,604 'correct':93 'cost':26,78,216,331,336,380,682,708 'cost-auditor.md':218 'cost/value':307 'could':238,358 'count':128,258 'credibl':242 'custom':323 'cut':6,81,377,400,504,513,533,577,588,647,679,748 'cut-intern':376,512,576 'cut-user-fac':399,532,587 'dead':390 'debug':72 'delet':314 'deliv':227,630 'depend':158 'detect':152 'diff':571 'differ':700 'dir':176 'directori':131 'discard':244,340,350 'doc':162 'doesn':12,84 'domain':710,717,738 'domain-specif':716 'drive':637 'drive-bi':636 'earn':14,86,454 'edit':188,467 'endpoint':405 'enforc':206 'engin':23,715,721 'entir':37 'entri':133 'estim':595 'everi':62,701 'everyth':297,646 'evid':252 'evidence-bas':251 'exceed':382 'exist':104,161,232 'face':143,387,402,535,590 'fail':247,502,662 'failur':634 'fair':490 'featur':33,138,347,412,433,559 'file':127,196,203,256,557 'filter':243 'find':60,160,245,268,299,304,341,351 'first':499 'fix':518 'folder':10 'framework':156 'fresh':619 'full':192 'fulli':742 'generalist':732 'get':190 'git':570 'handler':725 'headlin':561 'helper':395 'honest':328 'identifi':136 'ignor':680 'implement':437 'import':520 'inflat':640 'insid':430 'instinct':293 'intern':378,394,514,578 'isn':276 'item':538,658 'job':370 'justifi':435 'keep':16,88,456,468,610,657,677 'key':157 'know':620,623 'languag':155 'larger':442 'lean':564 'len':204 'level':373 'liabil':68 'librari':233,326,685 'like':727 'line':63,257,272,282,287,322 'lint':523 'list':149,539,591,600,611 'loc':130,558,596 'look':651,726 'maintain':71,673 'mainten':25,77,222,379 'make':76 'map':124 'materi':310 'mean':374 'metric':260 'migrat':73,330,681 'minim':628 'mismatch':308 'misread':709 'misunderstood':345 'mode':635 'model':291,642 'must':703 'necess':3 'necessari':356,444 'need':457,602 'nobodi':213 'note':475 'one':48,516,562 'oper':288 'outsid':422 'over-engin':21,713 'parallel':179 'parser':324 'pass':507,517 'path':39,44,197 'pattern':263 'percentag':581 'plus':194 'point':134 'preserv':446 'problem':212 'produc':58 'proportion':269 'protocol':724 'provid':45,148 'public':409 'purpos':61,165,349 'question':100,450,463,537,599,608,746 'rate':645 'rational':168 'read':69,183 'read-on':182 'reason':565 'recommend':702 'reconnaiss':113 'reduc':29 'reduct':580,597 'refactor':364 'refer':254,521 'remov':36,389,403 'removing/replacing':332 'replac':239,319,683 'repo':57 'report':279,296,543,549,654 'requir':51,505 'resist':300 'review':94,98,116,344,469,488,556,661,733 'rewrit':697 'rule':722 'run':497,522 'scope':54,126,552 'scout':229 'sentenc':563 'serv':736 'servic':234 'set':139 'sever':371,639 'shallow':59 'share':122 'shorter':361 'shrink':432,510,574,649 'sign':419,585 'sign-off':418,584 'signal':659 'simpler':236 'size':112 'skill':50,75,175,368 'skill-audit-necessity' 'slight':360 'solut':19 'solv':210 'sound':687 'source-jhostalek' 'spawn':115,170 'specif':255,462,607,718 'specul':264,728 'stack':154 'start':618 'stat':572 'state':164,460,605 'stood':482 'stop':503 'structur':132,550 'style':97 'summari':553 'surfac':303,416,464,695 'surviv':474,613 'switch':707 'synthesi':241 'system':723 'target':38,43,200 'teammat':169,201 'tend':643 'territori':365 'test':498,524,696 'thorough':652 'three':172 'tool':406 'topic-agent-skills' 'topic-ai-coding' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-code-skills' 'topic-code-review' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-git-workflow' 'topic-multi-agent' 'total':129 'trust':485 'unclear':451 'understand':743 'understood':70 'unnecessari':275 'unus':392 'usag':262,421 'use':4 'user':142,386,401,413,458,534,546,589,603 'user-fac':141,385 'util':273 'valu':226,383 'verifi':428 'visibl':79 'vs':224 'well':672 'well-maintain':671 'whether':17,452 'whole':56 'workflow':720 'worth':278 'wrap':284 'x':441,686 'yagni':205 'yagni.md':207 'zero':656","prices":[{"id":"dc6dbeff-840c-4bab-886c-c65b06809465","listingId":"c5cf0a3c-8fd6-4862-99aa-1ac28b744301","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JHostalek","category":"dotclaude","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:30.753Z"}],"sources":[{"listingId":"c5cf0a3c-8fd6-4862-99aa-1ac28b744301","source":"github","sourceId":"JHostalek/dotclaude/audit-necessity","sourceUrl":"https://github.com/JHostalek/dotclaude/tree/main/skills/audit-necessity","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:30.753Z","lastSeenAt":"2026-05-18T19:13:14.722Z"}],"details":{"listingId":"c5cf0a3c-8fd6-4862-99aa-1ac28b744301","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JHostalek","slug":"audit-necessity","github":{"repo":"JHostalek/dotclaude","stars":8,"topics":["agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor","developer-tools","git-workflow","multi-agent","prompt-engineering","skill-md"],"license":"cc0-1.0","html_url":"https://github.com/JHostalek/dotclaude","pushed_at":"2026-05-17T15:07:41Z","description":"Agent skills for agentic coding tools. Extremely opinionated. Updated (almost) daily.","skill_md_sha":"28748654708c74efde7ba899e36b1d48d5705b22","skill_md_path":"skills/audit-necessity/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JHostalek/dotclaude/tree/main/skills/audit-necessity"},"layout":"multi","source":"github","category":"dotclaude","frontmatter":{"name":"audit-necessity","description":"Use when cutting code in a folder that doesn't earn its keep — whether a solution is over-engineered, where maintenance cost can be reduced, or where a feature should be removed entirely."},"skills_sh_url":"https://skills.sh/JHostalek/dotclaude/audit-necessity"},"updatedAt":"2026-05-18T19:13:14.722Z"}}