{"id":"30afdad6-1e06-487a-a76c-1f34a96579bc","shortId":"DUmDKS","kind":"skill","title":"simplifying-code","tagline":">-","description":"# Simplifying Code\n\n## Principles\n\n| Principle | Rule |\n|-----------|------|\n| **Preserve behavior** | Output must do exactly what the input did -- no silent feature additions or removals. Specifically preserve: async/sync boundaries (do not convert sync to async or reverse), error propagation paths (do not alter strategy), logging/telemetry/guards/retries that encode operational intent, and domain-specific steps (do not collapse into generic helpers that hide intent) |\n| **Explicit over clever** | Prefer explicit variables over nested expressions. Readable beats compact |\n| **Simplicity over cleanliness** | Prefer straightforward code over pattern-heavy \"clean\" code. Three similar lines beat a premature abstraction |\n| **Surgical changes** | Touch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding code |\n| **Surface assumptions** | Before changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same pass |\n\n## Process\n\n1. **Read first** -- understand the full file and its dependents before changing anything. Apply Chesterton's Fence: if you see code that looks unnecessary but don't understand why it's there, check `git blame` before removing it. First understand the reason, then decide if the reason still applies.\n2. **Identify invariants** -- what must stay the same? Public API, return types, side effects, error behavior\n3. **Identify targets** -- find the highest-impact simplification opportunities. Impact = readability and maintainability; prioritize: control flow -> naming -> duplication -> types (see Smell -> Fix table)\n4. **Apply in order** -- control flow → naming → duplication → data shaping → types. Structural changes first, cosmetic last\n5. **Verify** -- confirm no behavior change: tests pass, types check, imports resolve\n6. **Pre-submit scope audit** -- walk every changed line and ask \"does the requested task explicitly require this line?\" If no, revert it and list it as a follow-up under Residual Risks. Drive-by edits belong in a separate change, not the current patch. For the pre-edit complement on ambiguous-scope requests (\"simplify my project\"), see `ia-verification-before-completion`'s Scope Confirmation gate.\n\n## Smell → Fix\n\n| Smell | Fix |\n|-------|-----|\n| Deep nesting (>2 levels) | Guard clauses with early returns |\n| Long function (>20 lines) | Extract into named functions by responsibility |\n| Too many parameters (>3) | Group into an options/config object |\n| Duplicated block (**3+** occurrences) | Extract shared function. Two copies = leave inline; wait for the third |\n| Magic numbers/strings | Named constants |\n| Complex conditional | Extract to descriptively-named boolean or function |\n| Dense transform chain (3+ chained methods) | Break into named intermediates for debuggability |\n| Dead code / unreachable branches | Delete entirely -- no commented-out code |\n| Unnecessary `else` after return | Remove `else`, dedent |\n\n## AI Slop Removal\n\nWhen simplifying AI-generated code, specifically target:\n\n- **Redundant comments** that restate the code (`// increment counter` above `counter++`) -- delete them\n- **Unnecessary defensive checks** for conditions that cannot occur in context -- remove the guard\n- **Gratuitous type casts** (`as any`, `as unknown as T`) -- fix the actual type or use a proper generic\n- **Over-abstraction** (factory for 2 objects, wrapper around a single call, util file with 1 function) -- inline the code\n- **Inconsistent style** that drifts from the file's existing conventions -- match the file\n- **Placeholder stubs** (`// ...`, `// rest of code`, `// similar to above`, `// continue pattern`, `// add more as needed`) -- leave unsimplified code as-is rather than replacing it with stubs\n- **Redundant error wrapping** (`catch(e) { throw e; }`, `catch(e) { throw new Error(e.message); }`) that strips the original stack for no reason -- remove the try/catch entirely and let errors propagate\n- **Verbose stdlib reimplementations** (hand-rolled loops that replicate `array_filter`, `Array.from`, `Collection::pluck()`, `itertools`) -- replace with the stdlib/framework one-liner\n\n## Stop Conditions\n\nStop and ask before proceeding when:\n- Simplification requires changing a public API (function signatures, return types, exports)\n- Behavior parity cannot be verified (no tests exist and behavior is non-obvious)\n- Code is intentionally complex for domain reasons (performance-critical, protocol compliance)\n- Scope implies a redesign rather than a simplification\n\n## Constraints\n\n- Only simplify what was requested -- do not add features, expand scope, or introduce new dependencies\n- Leave unchanged code untouched -- do not add comments, docstrings, or type annotations to lines that were not simplified\n- Do not bundle unrelated cleanups into one patch -- each simplification should be a coherent, reviewable unit\n- Do not introduce framework-wide patterns while simplifying a small local change\n- Do not replace understandable duplication with opaque utility layers -- three similar lines are better than a premature abstraction\n- Keep comments that explain intent, invariants, or non-obvious constraints. Remove comments that restate obvious code behavior.\n- If a simplification would make the code harder to understand, skip it\n- Watch for over-simplification: inlining too aggressively removes names that gave concepts meaning; combining unrelated logic into one function hides distinct responsibilities; removing abstractions that exist for testability breaks the test suite\n- When unsure whether a block is dead code, ask instead of deleting\n\n## Verify\n\n- Tests pass and types check after changes\n- No behavior change (same inputs produce same outputs)\n- Scope limited to requested files -- no drive-by cleanups\n- Match test scope to the importer count surfaced in step 1 (Surface assumptions). Zero external importers: scoped tests on the changed paths. One or more external importers, or shared/utility code edited: run tests covering each importer. Run the full suite when the test runner has no path-scoping mechanism.\n\n## Orchestrator Mode (When Chained With Other Skills)\n\nWhen this skill is invoked by an orchestrator that also runs `ia-code-review`, `ia-writing-tests`, or `ia-verification-before-completion` on the same scope, each sub-skill re-resolving scope independently wastes tokens and risks drift. Avoid this by resolving scope exactly once and passing a canonical block to every sub-skill.\n\n**Resolved scope format** — the orchestrator builds this once, before dispatching any sub-skill:\n\n```\n## Resolved scope\nFiles:\n- path/to/file-a.ts\n- path/to/file-b.ts\n\nCommit range: HEAD~3..HEAD (or \"uncommitted\")\n\nIntent: [one-sentence description pulled from the user request or PR description]\n\nConstraints:\n- Preserve public API\n- No behavior change\n- [other constraints specific to this run]\n```\n\nEvery chained sub-skill receives this block verbatim in its prompt and uses it as the source of truth — no re-running `git diff --name-only`, no re-parsing the user request, no independent scope resolution. Sub-skills accept `--no-verify --no-report` flags when chained so verification and reporting happen once at the end of the chain, not per-skill. The last sub-skill in the chain runs verification; the orchestrator trusts that result rather than re-verifying.\n\nThis prevents two failure modes: scope drift (sub-skill A simplifies one set of files, sub-skill B reviews a different set) and double work (every sub-skill rediscovers the same facts).\n\n## Integration\n\n- `ia-code-simplicity-reviewer` agent -- analysis-only pass producing a simplification report (no code changes). Use before refactoring to identify targets.\n\n## Output\n\nAfter simplifying, report:\n- **Scope touched**: files and functions modified\n- **Key simplifications**: what changed and why (one line each)\n- **Verification**: tests pass, types check, no behavior change\n- **Residual risks**: assumptions made, areas not touched that may need attention","tags":["simplifying","code","skills","iliaal","agent-skills","ai-coding-assistant","ai-tools","claude-code"],"capabilities":["skill","source-iliaal","skill-simplifying-code","topic-agent-skills","topic-ai-coding-assistant","topic-ai-tools","topic-claude-code","topic-skills"],"categories":["ai-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/iliaal/ai-skills/simplifying-code","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add iliaal/ai-skills","source_repo":"https://github.com/iliaal/ai-skills","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 13 github stars · SKILL.md body (8,056 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:07:03.909Z","embedding":null,"createdAt":"2026-05-09T01:05:36.922Z","updatedAt":"2026-05-18T19:07:03.909Z","lastSeenAt":"2026-05-18T19:07:03.909Z","tsv":"'1':137,486,826 '2':186,332,476 '20':341 '3':202,352,360,390 '4':226 '5':242 '6':254 'abstract':93,473,714,769 'accept':1028 'actual':464 'add':514,642,656 'addit':22 'agent':1115 'aggress':752 'ai':417,423 'ai-gener':422 'also':882 'alter':42 'ambigu':310 'ambiguous-scop':309 'analysi':1117 'analysis-on':1116 'annot':661 'anyth':149 'api':195,594,975 'appli':150,185,227 'area':1164 'around':479 'array':568 'array.from':570 'as-i':521 'ask':265,585,786 'assumpt':113,828,1162 'async':34 'async/sync':27 'attent':1170 'audit':259 'avoid':916 'b':1093 'beat':73,90 'behavior':10,201,246,600,609,732,799,977,1158 'belong':293 'better':710 'blame':171 'block':117,359,782,927,992 'boolean':384 'boundari':28 'branch':402 'break':393,774 'build':938 'bundl':670 'call':482 'cannot':446,602 'canon':926 'cast':455 'catch':533,537 'chain':389,391,869,986,1037,1049,1061 'chang':95,115,148,238,247,262,297,591,696,797,800,836,978,1126,1146,1159 'check':169,251,442,795,1156 'chesterton':151 'claus':335 'clean':85 'cleanli':77 'cleanup':672,815 'clever':65 'code':3,5,80,86,111,157,400,409,425,433,490,508,520,614,652,731,739,785,845,886,1112,1125 'coher':681 'collaps':56 'collect':571 'combin':759 'comment':407,429,657,716,727 'commented-out':406 'commit':952 'compact':74 'complement':307 'complet':321,897 'complex':377,617 'complianc':625 'concept':757 'condit':378,444,582 'confirm':244,324 'constant':376 'constraint':634,725,972,980 'context':449 'continu':512 'control':217,230 'convent':105,500 'convert':31 'copi':366 'cosmet':240 'count':822 'counter':435,437 'cover':128,849 'critic':623 'current':300 'data':234 'dead':399,784 'debugg':398 'decid':180 'dedent':416 'deep':330 'defens':441 'delet':403,438,789 'dens':387 'depend':131,146,649 'descript':382,963,971 'descriptively-nam':381 'diff':1010 'differ':1096 'dispatch':942 'distinct':766 'docstr':658 'domain':51,619 'domain-specif':50 'doubl':1099 'drift':494,915,1080 'drive':290,813 'drive-bi':289,812 'duplic':220,233,358,701 'e':534,536,538 'e.message':542 'earli':337 'edit':130,292,306,846 'effect':199 'els':411,415 'encod':46 'end':1046 'entir':404,554 'error':37,200,531,541,557 'everi':261,929,985,1101 'exact':14,921 'exist':102,499,607,771 'expand':644 'explain':718 'explicit':63,67,270 'export':599 'express':71 'extern':830,841 'extract':343,362,379 'fact':1108 'factori':474 'failur':1077 'featur':21,643 'fenc':153 'file':143,484,497,503,810,949,1089,1139 'filter':569 'find':205 'first':139,175,239 'fix':224,327,329,462 'flag':1035 'flow':218,231 'follow':284 'follow-up':283 'format':107,935 'framework':688 'framework-wid':687 'full':142,854 'function':340,346,364,386,487,595,764,1141 'gate':325 'gave':756 'generat':424 'generic':58,470 'git':170,1009 'gratuit':453 'group':353 'guard':334,452 'hand':563 'hand-rol':562 'happen':1042 'harder':740 'head':954,956 'heavi':84 'helper':59 'hide':61,765 'highest':208 'highest-impact':207 'ia':318,885,889,894,1111 'ia-code-review':884 'ia-code-simplicity-review':1110 'ia-verification-before-complet':317,893 'ia-writing-test':888 'identifi':118,187,203,1131 'impact':209,212 'impli':627 'import':120,124,252,821,831,842,851 'inconsist':491 'increment':434 'independ':910,1022 'inlin':368,488,750 'input':17,802 'instead':787 'integr':1109 'intent':48,62,616,719,959 'intermedi':396 'introduc':647,686 'invari':188,720 'invok':877 'itertool':573 'keep':715 'key':1143 'last':241,1055 'layer':705 'leav':367,518,650 'let':556 'level':333 'limit':807 'line':89,263,273,342,663,708,1150 'liner':580 'list':279 'local':695 'logging/telemetry/guards/retries':44 'logic':761 'long':339 'look':159 'loop':565 'made':1163 'magic':373 'maintain':215 'make':737 'mani':350 'match':101,501,816 'may':1168 'mean':758 'mechan':865 'method':392 'mode':867,1078 'modifi':1142 'must':12,190 'name':104,219,232,345,375,383,395,754,1012 'name-on':1011 'need':99,517,1169 'nest':70,331 'new':540,648 'no-report':1032 'no-verifi':1029 'non':612,723 'non-obvi':611,722 'numbers/strings':374 'object':357,477 'obvious':613,724,730 'occur':447 'occurr':361 'one':579,674,763,838,961,1086,1149 'one-lin':578 'one-sent':960 'opaqu':703 'oper':47 'opportun':211 'options/config':356 'orchestr':866,880,937,1065 'order':229 'origin':546 'output':11,805,1133 'over-abstract':471 'over-simplif':747 'paramet':351 'pariti':601 'pars':1017 'pass':135,249,792,924,1119,1154 'patch':301,675 'path':39,837,863 'path-scop':862 'path/to/file-a.ts':950 'path/to/file-b.ts':951 'pattern':83,513,690 'pattern-heavi':82 'per':1052 'per-skil':1051 'perform':622 'performance-crit':621 'placehold':504 'pluck':572 'pr':970 'pre':256,305 'pre-edit':304 'pre-submit':255 'prefer':66,78 'prematur':92,713 'preserv':9,26,973 'prevent':1075 'principl':6,7 'priorit':216 'proceed':587 'process':136 'produc':803,1120 'project':315 'prompt':996 'propag':38,558 'proper':469 'protocol':624 'public':194,593,974 'pull':964 'rang':953 'rather':524,630,1069 're':907,1007,1016,1072 're-pars':1015 're-resolv':906 're-run':1006 're-verifi':1071 'read':138 'readabl':72,213 'reason':178,183,550,620 'receiv':990 'redesign':629 'rediscov':1105 'redund':428,530 'refactor':1129 'reimplement':561 'remov':24,173,414,419,450,551,726,753,768 'replac':526,574,699 'replic':567 'report':1034,1041,1123,1136 'request':268,312,639,809,968,1020 'requir':271,590 'residu':287,1160 'resolut':1024 'resolv':253,908,919,933,947 'respons':348,767 'rest':506 'restat':431,729 'result':1068 'return':196,338,413,597 'revers':36 'revert':276 'review':682,887,1094,1114 'risk':288,914,1161 'roll':564 'rule':8 'run':847,852,883,984,1008,1062 'runner':859 'scope':258,311,323,626,645,806,818,832,864,901,909,920,934,948,1023,1079,1137 'see':156,222,316 'sentenc':962 'separ':296 'set':1087,1097 'shape':235 'share':363 'shared/utility':844 'side':198 'signatur':596 'silent':20 'similar':88,509,707 'simplic':75,1113 'simplif':210,589,633,677,735,749,1122,1144 'simplifi':2,4,100,313,421,636,667,692,1085,1135 'simplifying-cod':1 'singl':481 'skill':872,875,905,932,946,989,1027,1053,1058,1083,1092,1104 'skill-simplifying-code' 'skip':743 'slop':418 'small':694 'smell':223,326,328 'sourc':1002 'source-iliaal' 'specif':25,52,426,981 'stack':547 'stay':191 'stdlib':560 'stdlib/framework':577 'step':53,825 'still':184 'stop':581,583 'straightforward':79 'strategi':43 'strip':544 'structur':237 'stub':505,529 'style':103,492 'sub':904,931,945,988,1026,1057,1082,1091,1103 'sub-skil':903,930,944,987,1025,1056,1081,1090,1102 'submit':257 'suit':777,855 'surfac':112,823,827 'surgic':94 'surround':110 'sync':32 'tabl':225 'target':204,427,1132 'task':269 'test':127,248,606,776,791,817,833,848,858,891,1153 'testabl':773 'third':372 'three':87,706 'throw':535,539 'token':912 'topic-agent-skills' 'topic-ai-coding-assistant' 'topic-ai-tools' 'topic-claude-code' 'topic-skills' 'touch':96,1138,1166 'transform':388 'trust':1066 'truth':1004 'try/catch':553 'two':365,1076 'type':197,221,236,250,454,465,598,660,794,1155 'unchang':651 'uncommit':958 'understand':140,164,176,700,742 'unit':683 'unknown':459 'unnecessari':160,410,440 'unreach':401 'unrel':671,760 'unsimplifi':519 'unsur':779 'untouch':653 'use':467,998,1127 'user':967,1019 'util':483,704 'variabl':68 'verbatim':993 'verbos':559 'verif':319,895,1039,1063,1152 'verifi':243,604,790,1031,1073 'wait':369 'walk':260 'wast':911 'watch':745 'whether':780 'wide':689 'work':1100 'would':736 'wrap':532 'wrapper':478 'write':890 'zero':829 '~3':955","prices":[{"id":"a3e7af07-1b09-452c-a47a-798c54e4591f","listingId":"30afdad6-1e06-487a-a76c-1f34a96579bc","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"iliaal","category":"ai-skills","install_from":"skills.sh"},"createdAt":"2026-05-09T01:05:36.922Z"}],"sources":[{"listingId":"30afdad6-1e06-487a-a76c-1f34a96579bc","source":"github","sourceId":"iliaal/ai-skills/simplifying-code","sourceUrl":"https://github.com/iliaal/ai-skills/tree/master/skills/simplifying-code","isPrimary":false,"firstSeenAt":"2026-05-09T01:05:36.922Z","lastSeenAt":"2026-05-18T19:07:03.909Z"}],"details":{"listingId":"30afdad6-1e06-487a-a76c-1f34a96579bc","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"iliaal","slug":"simplifying-code","github":{"repo":"iliaal/ai-skills","stars":13,"topics":["agent-skills","ai-coding-assistant","ai-tools","claude-code","skills"],"license":"mit","html_url":"https://github.com/iliaal/ai-skills","pushed_at":"2026-05-16T13:15:17Z","description":"Curated collection of agent skills for AI coding assistants.","skill_md_sha":"8b63cbc642423af0e24cc4cbbb4ea98272b431de","skill_md_path":"skills/simplifying-code/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/iliaal/ai-skills/tree/master/skills/simplifying-code"},"layout":"multi","source":"github","category":"ai-skills","frontmatter":{"name":"simplifying-code","description":">-"},"skills_sh_url":"https://skills.sh/iliaal/ai-skills/simplifying-code"},"updatedAt":"2026-05-18T19:07:03.909Z"}}