home / skills / shotaiuchi / dotclaude / refactor-archeology

refactor-archeology skill

safe

This skill analyzes git blame, commit history, and legacy comments to uncover rationale, constraints, and decisions guiding future refactors.

npx playbooks add skill shotaiuchi/dotclaude --skill refactor-archeology

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: refactor-archeology
description: >-
  Code history and rationale investigation for refactoring. Apply when
  researching git blame, commit history, code comments, hidden constraints,
  and historical design decisions.
user-invocable: false
---

# Code Archeologist Analysis

Research the history of the code to understand why decisions were made and identify hidden constraints.

## Analysis Checklist

### Git History Analysis
- Run git blame on target files to identify authors and change dates
- Review commit messages for rationale behind key decisions
- Trace the evolution of critical functions through git log
- Identify code that has been frequently modified (churn analysis)

### Decision Rationale
- Extract reasoning from commit messages and PR descriptions
- Check for linked issues or tickets explaining requirements
- Identify comments that document "why" rather than "what"
- Look for TODO/FIXME/HACK comments with historical context

### Hidden Constraints
- Detect workarounds for external system limitations
- Identify timing-sensitive code or ordering dependencies
- Find platform-specific behavior that constrains refactoring
- Check for undocumented business rules embedded in logic

### Legacy Pattern Identification
- Identify deprecated patterns still in use
- Find abandoned migration attempts (partial rewrites)
- Detect compatibility shims that may no longer be needed
- Map code that predates current architecture conventions

### Knowledge Preservation
- Document tribal knowledge found in comments and commit messages
- Record undocumented invariants that tests rely upon
- Capture performance constraints discovered through history
- List external system dependencies revealed by past incidents

## Output Format

Report findings with impact ratings:

| Impact | Description |
|--------|-------------|
| Breaking | Hidden constraint that will cause failures if not preserved |
| High | Historical decision with active dependencies on its behavior |
| Medium | Legacy pattern that should be updated but carries risk |
| Low | Historical artifact safe to remove or modernize |

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

FAQ

What output format does the skill produce?

A concise report listing findings, their impact rating (Breaking/High/Medium/Low), recommended mitigations, and suggested tests or documentation to add.

How do I reduce false positives from TODO or FIXME comments?

Cross-reference comment context with commit history and associated issues; mark as low impact only after confirming no runtime dependency or linked incidents.