{"id":"e70c393a-8260-441d-8200-c7e9b7e40e3a","shortId":"HFRfsK","kind":"skill","title":"managing-tech-debt","tagline":"Produce a Tech Debt Management Pack (debt register, scoring, refactor vs rewrite memo, paydown plan).","description":"# Managing Tech Debt\n\n## Scope\n\n**Covers**\n- Identifying and making technical debt **visible** (including user-visible symptoms)\n- Prioritizing debt work using a **transparent scoring model**\n- Deciding **refactor vs migrate vs rebuild vs deprecate** with explicit criteria\n- Planning **incremental modernization** (avoid “rewrite traps”)\n- Building a **business case** for hard-to-measure investments (metrics + small tests)\n- Creating an execution-ready **paydown plan** with risks, milestones, and comms\n\n**When to use**\n- “Create a tech debt register and prioritize what to fix next quarter.”\n- “We’re considering a rewrite/migration—help us make the call and plan it safely.”\n- “Our legacy system slows delivery—build a paydown plan with milestones and metrics.”\n- “Leadership won’t fund refactors—quantify impact and propose a measurable plan.”\n\n**When NOT to use**\n- You need to respond to an active incident (use incident response/runbooks).\n- You only need to fix a small localized bug or a single refactor (just do the work).\n- You need a full architecture redesign from scratch without existing constraints (separate architecture/design process).\n- You need roadmap prioritization across many product bets (use `technical-roadmaps` or `prioritizing-roadmap`).\n- You are designing a new platform or infrastructure system, not modernizing an existing one (use `platform-infrastructure`).\n- You need to cut scope on an active project to hit a deadline (use `scoping-cutting`).\n- The real problem is engineering process, culture, or team dysfunction, not code (use `engineering-culture`).\n\n## Inputs\n\n**Minimum required**\n- System/service(s) in scope + brief description\n- Primary pain: reliability risk, velocity tax, scalability/perf, security/compliance, operability, UX fragmentation, cost\n- Time horizon (e.g., “6 weeks”, “next quarter”, “12 months”) + any fixed deadlines\n- Stakeholders + decision-maker(s) (Eng/PM/Design/Leadership)\n- Constraints: team capacity, freeze windows, compliance/security requirements\n\n**Missing-info strategy**\n- Ask up to 5 questions from [references/INTAKE.md](references/INTAKE.md), then proceed with explicit assumptions.\n- If estimates are unavailable, use **ranges** and label confidence.\n- Do not request secrets/credentials; use redacted or synthetic identifiers if needed.\n\n## Outputs (deliverables)\n\nProduce a **Tech Debt Management Pack** in Markdown (in-chat; or as files if requested):\n\n1) **Context snapshot** (scope, pains, constraints, stakeholders, success definition)\n2) **Tech Debt Register** (inventory table with owners, symptoms, impact, effort range, risks)\n3) **Scoring + prioritization** (model + ranked list + rationale)\n4) **Strategy decision(s)** (refactor/migrate/rebuild/deprecate) with explicit criteria\n5) **Execution plan** (incremental milestones, sequencing, resourcing, decommission plan)\n6) **Migration + rollback plan** (if applicable; includes “dual-run” cost/plan)\n7) **Metrics plan** (baseline, targets, leading indicators, instrumentation gaps, small tests)\n8) **Risks / Open questions / Next steps** (always included)\n\nTemplates: [references/TEMPLATES.md](references/TEMPLATES.md)\n\n## Workflow (8 steps)\n\n### 1) Intake + decision framing\n- **Inputs:** User context; [references/INTAKE.md](references/INTAKE.md).\n- **Actions:** Confirm the decision(s) to be made, scope boundaries, time horizon, and constraints. Define what “success” means (e.g., fewer incidents, faster deploys, simpler UX integration).\n- **Outputs:** Context snapshot (draft).\n- **Checks:** A stakeholder can answer: “What will we decide/do differently after reading this?”\n\n### 2) Surface the “debt symptoms” (user + engineering)\n- **Inputs:** Known pain points; incident/perf history if available; qualitative reports.\n- **Actions:** List user-visible symptoms (inconsistent UX, broken integrations, slow workflows) and engineering symptoms (deploy pain, flaky tests, high MTTR, brittle dependencies). Map symptoms → suspected debt sources.\n- **Outputs:** Symptoms → suspected causes map (bullet list).\n- **Checks:** At least 1 symptom is tied to a measurable signal (latency, errors, cycle time, support volume) or explicitly marked “needs instrumentation”.\n\n### 3) Build the Tech Debt Register (inventory)\n- **Inputs:** Repos/services/components in scope; symptoms map.\n- **Actions:** Create a debt register with a consistent schema (type, location, current workaround, impact, risk, rough effort, dependencies, owner). Separate “must fix” from “nice to have.”\n- **Outputs:** Tech Debt Register (table).\n- **Checks:** Every item has an owner, an impact statement, and an effort **range** (even if coarse).\n\n### 4) Score and prioritize (make trade-offs explicit)\n- **Inputs:** Debt register.\n- **Actions:** Score items on impact and risk (user harm, reliability, security, velocity tax) vs effort and sequencing constraints. Produce a ranked list and explain the top 5–10.\n- **Outputs:** Scoring model + prioritized list.\n- **Checks:** Top-ranked items are defensible: rationale references symptoms/signals and constraints, not “taste”.\n\n### 5) Decide strategy per top item: refactor vs migrate vs rebuild vs deprecate\n- **Inputs:** Top-ranked debt items; constraints; required capabilities (incl. operational flexibility).\n- **Actions:** For each top item, pick a strategy and document options + criteria. If proposing a rebuild, include a plan to avoid the rewrite trap: migration phases, parallel support cost, cutover and decommission.\n- **Outputs:** Strategy decision(s) + decision memo(s).\n- **Checks:** For any “rebuild/migrate” decision, the plan includes a **decommission path** and acknowledges **dual-run** cost.\n\n### 6) Create the incremental execution plan\n- **Inputs:** Strategy decisions; constraints; dependencies.\n- **Actions:** Convert work into milestones (thin slices), define sequencing, and set resourcing/capacity (e.g., % per sprint). Add explicit “done means decommissioned” criteria for migrations.\n- **Outputs:** Execution plan (milestones + owners + timeline).\n- **Checks:** Each milestone has a measurable acceptance criterion and a rollback/stop condition.\n\n### 7) Quantify value: metrics + small tests\n- **Inputs:** Baselines (or estimates); execution plan.\n- **Actions:** Define metrics that make the investment fundable (e.g., incident rate, MTTR, p95 latency, deploy frequency, lead time, cost). Where impact is hard to measure, propose a small test (limited rollout, canary, instrumentation spike).\n- **Outputs:** Metrics plan (baseline → target → measurement method).\n- **Checks:** Metrics include at least 1 leading indicator and 1 guardrail; instrumentation gaps are listed with owners.\n\n### 8) Align stakeholders + quality gate + finalization\n- **Inputs:** Draft pack.\n- **Actions:** Add stakeholder cadence (updates, review gates). Run [references/CHECKLISTS.md](references/CHECKLISTS.md) and score using [references/RUBRIC.md](references/RUBRIC.md). Finalize **Risks / Open questions / Next steps**.\n- **Outputs:** Final Tech Debt Management Pack.\n- **Checks:** Plan is incrementally executable, risks are explicit, and the first milestone can start immediately.\n\n## Anti-patterns (common failure modes)\n\n1. **\"Big bang\" rewrite** — Proposing a full rewrite without migration phases, dual-run cost estimates, or decommission criteria. Result: the rewrite takes 2x longer, the old system lives on, and you maintain both indefinitely.\n2. **Debt register without owners** — Cataloging debt items without assigning an owner or linking to user-visible symptoms. Result: the register becomes a graveyard document that nobody acts on.\n3. **Prioritizing by developer frustration** — Ranking debt by what annoys engineers most rather than by impact on users, reliability, or velocity. Result: high-visibility-but-low-impact items consume the budget while critical reliability debt festers.\n4. **Metrics theater** — Defining improvement metrics (deploy frequency, MTTR) without baselines or instrumentation. Result: you cannot prove the investment worked, eroding future funding for debt work.\n5. **Invisible paydown plan** — Doing debt work silently without stakeholder communication or milestone reviews. Result: leadership sees no progress, cancels the effort, and the team loses credibility for future proposals.\n\n## Quality gate (required)\n- Use [references/CHECKLISTS.md](references/CHECKLISTS.md) and [references/RUBRIC.md](references/RUBRIC.md).\n- Always include: **Risks**, **Open questions**, **Next steps**.\n\n## Examples\n\n**Example 1 (quarterly planning):** “Use `managing-tech-debt`. System: payments-service. Pain: frequent incidents + slow delivery. Horizon: next quarter. Output: a Tech Debt Management Pack with a prioritized register and paydown plan.”\n\n**Example 2 (rewrite decision):** “We want to rebuild our pricing engine. Compare refactor vs rebuild, include migration phases, dual-run costs, rollback plan, and a metrics-based justification.”\n\n**Boundary example (redirect — generic question):** “Tell me whether tech debt is bad and how to avoid it.”\nResponse: This skill produces an actionable management pack, not general advice. Ask for a specific system, pain point, and time horizon. Otherwise provide a minimal intake checklist and an example register schema.\n\n**Boundary example (redirect — neighbor skill):** “Our roadmap has too many competing priorities and we cannot decide what to build next quarter.”\nResponse: This is a roadmap prioritization problem, not a tech debt management task. Redirect to `technical-roadmaps` or `prioritizing-roadmap` for a prioritization framework. If tech debt items are among the competing priorities, return here to produce the debt register and paydown plan.","tags":["managing","tech","debt","lenny","skills","plus","liqiongyu","agent-skills","ai-agents","automation","claude","codex"],"capabilities":["skill","source-liqiongyu","skill-managing-tech-debt","topic-agent-skills","topic-ai-agents","topic-automation","topic-claude","topic-codex","topic-prompt-engineering","topic-refoundai","topic-skillpack"],"categories":["lenny_skills_plus"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/liqiongyu/lenny_skills_plus/managing-tech-debt","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add liqiongyu/lenny_skills_plus","source_repo":"https://github.com/liqiongyu/lenny_skills_plus","install_from":"skills.sh"}},"qualityScore":"0.474","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 49 github stars · SKILL.md body (9,716 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-04-22T00:56:23.071Z","embedding":null,"createdAt":"2026-04-18T22:16:41.258Z","updatedAt":"2026-04-22T00:56:23.071Z","lastSeenAt":"2026-04-22T00:56:23.071Z","tsv":"'1':354,436,543,872,876,941,1117 '10':661 '12':281 '2':363,488,976,1151 '2x':964 '3':376,562,1006 '4':383,622,1043 '5':306,391,660,681,1069 '6':277,400,762 '7':411,814 '8':422,434,884 'accept':808 'acknowledg':757 'across':190 'act':1004 'action':445,505,575,634,706,773,826,893,1202 'activ':150,227 'add':788,894 'advic':1207 'align':885 'alway':428,1108 'among':1281 'annoy':1015 'answer':479 'anti':936 'anti-pattern':935 'applic':405 'architectur':176 'architecture/design':184 'ask':303,1208 'assign':985 'assumpt':315 'avail':502 'avoid':58,726,1195 'bad':1191 'bang':943 'base':1178 'baselin':414,821,863,1053 'becom':998 'bet':193 'big':942 'boundari':454,1180,1229 'brief':260 'brittl':526 'broken':513 'budget':1037 'bug':163 'build':61,120,563,1247 'bullet':538 'busi':63 'cadenc':896 'call':110 'canari':857 'cancel':1088 'cannot':1058,1243 'capabl':702 'capac':294 'case':64 'catalog':981 'caus':536 'chat':348 'check':475,540,606,667,745,802,867,920 'checklist':1223 'coars':621 'code':248 'comm':85 'common':938 'communic':1079 'compar':1161 'compet':1239,1283 'compliance/security':297 'condit':813 'confid':324 'confirm':446 'consid':103 'consist':582 'constraint':182,292,359,458,651,678,700,771 'consum':1035 'context':355,442,472 'convert':774 'cost':273,734,761,844,955,1171 'cost/plan':410 'cover':24 'creat':74,89,576,763 'credibl':1095 'criteria':54,390,717,793,959 'criterion':809 'critic':1039 'cultur':243,252 'current':586 'cut':223,236 'cutov':735 'cycl':553 'deadlin':232,285 'debt':4,8,11,22,29,37,92,341,365,491,531,566,578,603,632,698,917,977,982,1012,1041,1067,1074,1124,1140,1189,1260,1278,1290 'decid':44,682,1244 'decide/do':483 'decis':288,385,438,448,740,742,749,770,1153 'decision-mak':287 'decommiss':398,737,754,792,958 'defens':673 'defin':459,780,827,1046 'definit':362 'deliver':337 'deliveri':119,1133 'depend':527,592,772 'deploy':467,520,840,1049 'deprec':51,693 'descript':261 'design':204 'develop':1009 'differ':484 'document':715,1001 'done':790 'draft':474,891 'dual':408,759,953,1169 'dual-run':407,758,952,1168 'dysfunct':246 'e.g':276,463,785,834 'effort':373,591,617,648,1090 'eng/pm/design/leadership':291 'engin':241,251,494,518,1016,1160 'engineering-cultur':250 'erod':1063 'error':552 'estim':317,823,956 'even':619 'everi':607 'exampl':1115,1116,1150,1181,1226,1230 'execut':77,392,766,797,824,924 'execution-readi':76 'exist':181,214 'explain':657 'explicit':53,314,389,558,630,789,927 'failur':939 'faster':466 'fester':1042 'fewer':464 'file':351 'final':889,908,915 'first':930 'fix':98,159,284,596 'flaki':522 'flexibl':705 'fragment':272 'frame':439 'framework':1275 'freez':295 'frequenc':841,1050 'frequent':1130 'frustrat':1010 'full':175,947 'fund':131,1065 'fundabl':833 'futur':1064,1097 'gap':419,879 'gate':888,899,1100 'general':1206 'generic':1183 'graveyard':1000 'guardrail':877 'hard':67,848 'hard-to-measur':66 'harm':642 'help':106 'high':524,1029 'high-visibility-but-low-impact':1028 'histori':500 'hit':230 'horizon':275,456,1134,1217 'identifi':25,333 'immedi':934 'impact':134,372,588,613,638,846,1021,1033 'improv':1047 'in-chat':346 'incid':151,153,465,835,1131 'incident/perf':499 'incl':703 'includ':31,406,429,722,752,869,1109,1165 'inconsist':511 'increment':56,394,765,923 'indefinit':975 'indic':417,874 'info':301 'infrastructur':209,219 'input':253,440,495,569,631,694,768,820,890 'instrument':418,561,858,878,1055 'intak':437,1222 'integr':470,514 'inventori':367,568 'invest':70,832,1061 'invis':1070 'item':608,636,671,686,699,710,983,1034,1279 'justif':1179 'known':496 'label':323 'latenc':551,839 'lead':416,842,873 'leadership':128,1084 'least':542,871 'legaci':116 'limit':855 'link':989 'list':381,506,539,655,666,881 'live':969 'local':162 'locat':585 'longer':965 'lose':1094 'low':1032 'made':452 'maintain':973 'make':27,108,626,830 'maker':289 'manag':2,9,20,342,918,1122,1141,1203,1261 'managing-tech-debt':1,1121 'mani':191,1238 'map':528,537,574 'mark':559 'markdown':345 'mean':462,791 'measur':69,138,549,807,850,865 'memo':17,743 'method':866 'metric':71,127,412,817,828,861,868,1044,1048,1177 'metrics-bas':1176 'migrat':47,401,689,730,795,950,1166 'mileston':83,125,395,777,799,804,931,1081 'minim':1221 'minimum':254 'miss':300 'missing-info':299 'mode':940 'model':43,379,664 'modern':57,212 'month':282 'mttr':525,837,1051 'must':595 'need':145,157,173,187,221,335,560 'neighbor':1232 'new':206 'next':99,279,426,912,1113,1135,1248 'nice':598 'nobodi':1003 'off':629 'old':967 'one':215 'open':424,910,1111 'oper':270,704 'option':716 'otherwis':1218 'output':336,471,533,601,662,738,796,860,914,1137 'owner':370,593,611,800,883,980,987 'p95':838 'pack':10,343,892,919,1142,1204 'pain':263,358,497,521,1129,1213 'parallel':732 'path':755 'pattern':937 'paydown':18,79,122,1071,1148,1293 'payment':1127 'payments-servic':1126 'per':684,786 'phase':731,951,1167 'pick':711 'plan':19,55,80,112,123,139,393,399,403,413,724,751,767,798,825,862,921,1072,1119,1149,1173,1294 'platform':207,218 'platform-infrastructur':217 'point':498,1214 'price':1159 'primari':262 'priorit':36,95,189,200,378,625,665,1007,1145,1255,1270,1274 'prioriti':1240,1284 'prioritizing-roadmap':199,1269 'problem':239,1256 'proceed':312 'process':185,242 'produc':5,338,652,1200,1288 'product':192 'progress':1087 'project':228 'propos':136,719,851,945,1098 'prove':1059 'provid':1219 'qualit':503 'qualiti':887,1099 'quantifi':133,815 'quarter':100,280,1118,1136,1249 'question':307,425,911,1112,1184 'rang':321,374,618 'rank':380,654,670,697,1011 'rate':836 'rather':1018 'rational':382,674 're':102 'read':486 'readi':78 'real':238 'rebuild':49,691,721,1157,1164 'rebuild/migrate':748 'redact':330 'redesign':177 'redirect':1182,1231,1263 'refactor':14,45,132,167,687,1162 'refactor/migrate/rebuild/deprecate':387 'refer':675 'references/checklists.md':901,902,1103,1104 'references/intake.md':309,310,443,444 'references/rubric.md':906,907,1106,1107 'references/templates.md':431,432 'regist':12,93,366,567,579,604,633,978,997,1146,1227,1291 'reliabl':264,643,1024,1040 'report':504 'repos/services/components':570 'request':327,353 'requir':255,298,701,1101 'resourc':397 'resourcing/capacity':784 'respond':147 'respons':1197,1250 'response/runbooks':154 'result':960,995,1027,1056,1083 'return':1285 'review':898,1082 'rewrit':16,59,728,944,948,962,1152 'rewrite/migration':105 'risk':82,265,375,423,589,640,909,925,1110 'roadmap':188,197,201,1235,1254,1267,1271 'rollback':402,1172 'rollback/stop':812 'rollout':856 'rough':590 'run':409,760,900,954,1170 'safe':114 'scalability/perf':268 'schema':583,1228 'scope':23,224,235,259,357,453,572 'scoping-cut':234 'score':13,42,377,623,635,663,904 'scratch':179 'secrets/credentials':328 'secur':644 'security/compliance':269 'see':1085 'separ':183,594 'sequenc':396,650,781 'servic':1128 'set':783 'signal':550 'silent':1076 'simpler':468 'singl':166 'skill':1199,1233 'skill-managing-tech-debt' 'slice':779 'slow':118,515,1132 'small':72,161,420,818,853 'snapshot':356,473 'sourc':532 'source-liqiongyu' 'specif':1211 'spike':859 'sprint':787 'stakehold':286,360,477,886,895,1078 'start':933 'statement':614 'step':427,435,913,1114 'strategi':302,384,683,713,739,769 'success':361,461 'support':555,733 'surfac':489 'suspect':530,535 'symptom':35,371,492,510,519,529,534,544,573,994 'symptoms/signals':676 'synthet':332 'system':117,210,968,1125,1212 'system/service':256 'tabl':368,605 'take':963 'target':415,864 'task':1262 'tast':680 'tax':267,646 'team':245,293,1093 'tech':3,7,21,91,340,364,565,602,916,1123,1139,1188,1259,1277 'technic':28,196,1266 'technical-roadmap':195,1265 'tell':1185 'templat':430 'test':73,421,523,819,854 'theater':1045 'thin':778 'tie':546 'time':274,455,554,843,1216 'timelin':801 'top':659,669,685,696,709 'top-rank':668,695 'topic-agent-skills' 'topic-ai-agents' 'topic-automation' 'topic-claude' 'topic-codex' 'topic-prompt-engineering' 'topic-refoundai' 'topic-skillpack' 'trade':628 'trade-off':627 'transpar':41 'trap':60,729 'type':584 'unavail':319 'updat':897 'us':107 'use':39,88,143,152,194,216,233,249,320,329,905,1102,1120 'user':33,441,493,508,641,992,1023 'user-vis':32,507,991 'ux':271,469,512 'valu':816 'veloc':266,645,1026 'visibl':30,34,509,993,1030 'volum':556 'vs':15,46,48,50,647,688,690,692,1163 'want':1155 'week':278 'whether':1187 'window':296 'without':180,949,979,984,1052,1077 'won':129 'work':38,171,775,1062,1068,1075 'workaround':587 'workflow':433,516","prices":[{"id":"dec19e35-f3f4-4880-9cbf-d4c1b2aadb71","listingId":"e70c393a-8260-441d-8200-c7e9b7e40e3a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"liqiongyu","category":"lenny_skills_plus","install_from":"skills.sh"},"createdAt":"2026-04-18T22:16:41.258Z"}],"sources":[{"listingId":"e70c393a-8260-441d-8200-c7e9b7e40e3a","source":"github","sourceId":"liqiongyu/lenny_skills_plus/managing-tech-debt","sourceUrl":"https://github.com/liqiongyu/lenny_skills_plus/tree/main/skills/managing-tech-debt","isPrimary":false,"firstSeenAt":"2026-04-18T22:16:41.258Z","lastSeenAt":"2026-04-22T00:56:23.071Z"}],"details":{"listingId":"e70c393a-8260-441d-8200-c7e9b7e40e3a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"liqiongyu","slug":"managing-tech-debt","github":{"repo":"liqiongyu/lenny_skills_plus","stars":49,"topics":["agent-skills","ai-agents","automation","claude","codex","prompt-engineering","refoundai","skillpack"],"license":"apache-2.0","html_url":"https://github.com/liqiongyu/lenny_skills_plus","pushed_at":"2026-04-04T06:30:11Z","description":"86 agent-executable skill packs converted from RefoundAI’s Lenny skills (unofficial). Works with Codex + Claude Code.","skill_md_sha":"6b6fc523689ae81057ab5b2086e3296540b4862e","skill_md_path":"skills/managing-tech-debt/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/liqiongyu/lenny_skills_plus/tree/main/skills/managing-tech-debt"},"layout":"multi","source":"github","category":"lenny_skills_plus","frontmatter":{"name":"managing-tech-debt","description":"Produce a Tech Debt Management Pack (debt register, scoring, refactor vs rewrite memo, paydown plan)."},"skills_sh_url":"https://skills.sh/liqiongyu/lenny_skills_plus/managing-tech-debt"},"updatedAt":"2026-04-22T00:56:23.071Z"}}