refactor-archeology_skill

Overview

This skill investigates code history and hidden rationale to inform safe refactoring. It synthesizes git blame, commit logs, comments, and other historical artifacts to reveal constraints and design decisions that affect change risk. The output is a focused report that highlights potential breaking points and recommends mitigation priorities.

How this skill works

The skill runs targeted git history analysis (blame, log, churn) on specified files and functions, extracts reasoning from commit messages and PR descriptions, and surfaces comments like TODO/FIXME that contain historical context. It identifies hidden constraints such as timing dependencies, platform-specific behavior, and undocumented business rules, then categorizes findings with impact ratings (Breaking, High, Medium, Low). The final report lists actionable remediation steps and preservation guidelines for safe refactoring.

When to use it

• Before a planned refactor touching unfamiliar or long-lived code
• When tests pass but failures appear after small changes
• To evaluate risk after inheriting legacy code or a new module
• When resolving flaky production incidents with unclear root causes
• Prior to removing compatibility shims or deprecated patterns

Best practices

• Start with git blame and trace recent and frequent authors for institutional knowledge
• Prioritize findings marked Breaking or High before code changes
• Cross-check commit messages with linked issues and PR descriptions for explicit rationale
• Document discovered invariants and add tests that capture them before refactoring
• Preserve timing or ordering semantics in tests if historical commits indicate sensitivity

Example use cases

• Discovering a subtle ordering dependency introduced to work around an external API rate limit
• Finding an undocumented performance optimization that tests rely on
• Uncovering a deprecated compatibility shim left to support an old deployment target
• Identifying frequent-churn hotspots that should be redesigned rather than refactored superficially
• Extracting tribal knowledge from long-ago commits to avoid reintroducing regressions