Skip to content
cccskills
FreePublished on GitHub

tech-debt

Document and prioritize technical debt. Use when the user says "tech debt", "legacy code", "this code is a mess", "refactoring plan", "we need to clean this up", "paying down debt", "this is hard to change", "how do we fix this codebase", or has code that's difficult to understand or modify - even if they don't explicitly say "technical debt".

The English summary is being prepared. Showing the original description.

See how to install

Files included (1)

  • SKILL.md4.1 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Overview

Based on "Working Effectively with Legacy Code" by Michael Feathers. Feathers' definition: legacy code is code without tests. His central technique: find the "seams" - places where you can insert test coverage without changing the code under test. Once a seam has test coverage, you can safely refactor. The discipline: never refactor without a safety net. Never add features to untested code without first covering it.

Workflow

Step 1: Define the debt

Before prioritizing, describe the debt specifically:

Debt item: [name]
Location: [file:line or module]
What it is: [one sentence description]
Why it's a problem: [what it makes harder]
Symptom: [what developers experience because of it]

Vague debt ("the codebase is messy") can't be prioritized. Specific debt can.

Step 2: Classify the debt type

TypeDescriptionUrgency
Reckless/DeliberateShortcuts taken knowingly ("we'll fix it later")High
Reckless/InadvertentMistakes made without knowing betterHigh
Prudent/DeliberateConscious tradeoff: ship now, fix laterMedium
Prudent/InadvertentLearned better approach after the factLow

Step 3: Find the seams (Feathers)

A seam is a place where you can change behavior without editing existing code - typically a function call boundary or an interface.

For each debt item:

  • Where is the seam that would let you add tests without changing production code?
  • What would you need to mock or stub to isolate this code?
  • What's the minimum test coverage needed before safe refactoring?

Step 4: Estimate the cost of the debt

DimensionQuestions
Cost of carryHow much does this slow development each sprint?
Cost of fixHow many days to resolve?
Blast radiusHow many systems/teams are affected?
Risk if ignoredWhat breaks if this is never fixed?

Step 5: Prioritize the backlog

Prioritize debt that:

  • Has high cost of carry (slows the team every sprint)
  • Sits in high-change areas (touched frequently)
  • Blocks a planned feature

Deprioritize debt in stable areas that are rarely touched.

Step 6: Write the debt ticket

Title: [specific debt item]
Location: [file/module]
Type: [reckless/prudent x deliberate/inadvertent]
Impact: [what this costs the team per sprint]
Fix plan:
  1. Add seam tests: [specific tests to write first]
  2. Refactor: [what to change once tests exist]
  3. Verify: [how to confirm the refactor is safe]
Effort estimate: [days]
Priority: [P1/P2/P3]

Anti-Patterns

1. Refactoring without tests Bad: "Let me clean this up" without adding test coverage first. Good: Find the seam. Write tests. Then refactor. Tests prove you didn't break behavior.

2. Big bang rewrites Bad: "We'll rewrite the whole module from scratch." Good: Feathers: big rewrites fail. Incrementally improve with seam-by-seam coverage. Ship working code at every step.

3. Paying debt in high-risk sprints Bad: Refactoring core payment code the week before a major release. Good: Pay debt in low-risk windows. Prioritize timing as much as priority.

4. Debt without business context Bad: "This code is bad, we need to fix it." (to a PM or stakeholder) Good: "This debt costs us 2 days per sprint. Fixing it is a 5-day investment that pays back in 3 sprints."

Quality Checklist

  • Debt is described specifically (file, module, or function - not "the codebase")
  • Debt type classified
  • Seam identified for each item (where to add tests safely)
  • Cost of carry estimated in developer-days per sprint
  • Cost to fix estimated
  • Highest priority items are in high-change areas
  • Debt ticket includes fix plan with seam tests as first step

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Rate any product, feature, or experience on the 11-star scale (Brian Chesky's Airbnb thought experiment). Use when user says "rate this experience", "11-star", "star rating", "experience audit", "how good is this", "experience rating", "product audit", "quality assessment", or wants to evaluate product quality and identify improvement paths. Also trigger when user wants to benchmark a feature, assess where a product stands, or map out what "great" looks like - even if they don't explicitly say "11-star".

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Generate A/B copy variants grounded in Eugene Schwartz's awareness and market-sophistication stages and John Caples' tested-headline discipline. Every variant declares its angle, the awareness stage it targets, and a falsifiable hypothesis, and the skill recommends which pair to test first and what delta counts as signal. Use when the user says "A/B test this", "write variants", "give me options", "test different angles", "copy variants", "ab copy", "test this headline", "multiple versions", "which version is better", or wants to test copy before publishing. For reviewing copy that already exists, see copy-review. For sample size and stopping rules, see growth-experiment. For diagnosing a page rather than its words, see page-cro. For full paid ad sets by platform, see ad-campaign-writer.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Design statistically rigorous experiments to test data science hypotheses. Use when the user says "design an A/B test", "run an experiment", "test this hypothesis", "is this difference significant", "how many samples do I need", "randomized controlled trial", "causal inference", "uplift test", "holdout group", "significance test", "power calculation", "avoid p-hacking", or needs to determine whether an observed effect is real before making a product or model decision. For lean build-measure-learn product experiments without the statistics, use experiment-design instead.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Write measurable acceptance criteria for requirements or user stories. Use when the user says "write acceptance criteria", "definition of done", "how do we test this", "fit criteria", "given when then", "Gherkin scenarios", "what does done look like", "testable conditions", "how will we know this works" - even if they don't explicitly say "acceptance criteria".

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Build a strategic account plan for winning, retaining, or expanding a named account. Use when the user says "build an account plan", "strategic account planning", "how do I grow this account", "account expansion strategy", "whitespace analysis", "QBR prep", "key account review", "map the stakeholders in this account", "land and expand plan", "how do I break into [company]", or wants a structured strategy for a specific account.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Write paid ad copy for LinkedIn, Google, Meta, and YouTube. Produces multiple variants per platform, each targeting a different Eugene Schwartz awareness level and Cialdini persuasion principle. Use when the user asks for ad copy, ad variants, "write LinkedIn ads", Google ads, Meta ads, paid social copy, ad headlines, or wants creative for a paid campaign. Reads brand voice, ICP, and positioning from knowledge/. For organic social posts, see linkedin-post or social-calendar. For the landing page the ad points at, see landing-page-writer. For testing variants, see ab-copy-writer.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

See all skills by qa-aman

Report a problem with this skill