code-archaeologist

Code Archaeologist Skill

CRITICAL: This skill provides proactive intelligence BEFORE code changes to prevent bugs, maintain consistency, and learn from history.

When to Use This Skill (Auto-Invocation Guide)

🚨 ALWAYS Before Modifying Code

Trigger: User asks to fix, modify, refactor, or change any existing code

Commands to run:

# 1. Smart analysis - CRITICAL for risk assessment
python3 .claude/skills/code_archaeologist/skill.py smart <folder> --question "$ARGUMENTS"

# 2. File analysis - Check if function is a hotspot
python3 .claude/skills/code_archaeologist/skill.py file <file_path> --function <function_name>

3. Pattern compliance - Ensure consistency

python3 .claude/skills/code_archaeologist/skill.py pattern-adoption


**What to look for in output**:
- ⚠️ **REVERTS DETECTED**: Previous attempts failed - escalate to HIGH risk
- ⚠️ **HOTSPOT**: Function modified >20 times - bug-prone, needs comprehensive tests
- ⚠️ **GOD OBJECT**: File >2000 lines or >50 dependencies - refactor first
- ⚠️ **PATTERN VIOLATIONS**: Missing patterns used in >50% of files - enforce

### 🎯 Before Adding New Features
**Trigger**: User wants to add new functionality to existing folder

**Commands to run**:
```bash
# 1. Pattern requirements
python3 .claude/skills/code_archaeologist/skill.py pattern-adoption <folder>

# 2. Architecture constraints
python3 .claude/skills/code_archaeologist/skill.py dep-graph <folder>

# 3. Historical context
python3 .claude/skills/code_archaeologist/skill.py smart <folder>

# 4. Optional: Generate design doc with historical intelligence
python3 .claude/skills/code_archaeologist/skill.py design <folder> \
  --feature "$FEATURE_NAME" \
  --description "$FEATURE_DESC"

🤔 When User Asks "Why" Questions

Trigger: User asks "why", "how did", "what is the history"

Command to run:

python3 .claude/skills/code_archaeologist/skill.py context <folder> --question "$ARGUMENTS"

Provides:

Creation story and evolution
Similar past issues (keyword search)
Revert detection with failure reasons
Architectural decisions from commit messages

Available Commands

1. `smart` - Adaptive Risk Analysis (MOST IMPORTANT)

When: Before ANY code modification What it does: Intelligent analysis with auto-calculated commit limits, risk scoring, revert detection

python3 skill.py smart src/auth --question "Fix OAuth bug"

Output:

🧠 Adaptive Intelligence (smart commit limit, reasoning, confidence)
📊 Risk Assessment (CRITICAL/HIGH/MEDIUM/LOW with score 0-100)
⚠️ Revert History (failed previous attempts)
🔍 Similar Issues (keyword-based commit search)
📅 Timeline (condensed or full depending on history size)
✅ Recommended Actions (based on risk level)

Critical for: Preventing repeat failures, understanding risk, knowing what was tried before

2. `file` - Function-Level Hotspot Detection

When: Before modifying specific functions What it does: Identifies bug-prone functions, complexity growth, coupling

python3 skill.py file src/router.py --function handle_streaming

Output:

🔥 Hotspots (most frequently modified functions)
📈 Complexity Growth (functions that grew significantly)
🔗 Function Coupling (what changes together)
📅 Function Lifecycle (when added/modified/removed)

Critical for: Knowing if a function is high-risk before touching it

3. `pattern-adoption` - Consistency Enforcement

When: Before adding code to a folder What it does: Shows mandatory patterns, identifies violations

python3 skill.py pattern-adoption src/auth

Output:

📊 Pattern adoption statistics (percentage for each pattern)
✅ Common patterns (>50% adoption = mandatory)
⚠️ Pattern violations (files missing common patterns)
💡 Recommendations for new code

Detects 14 patterns: Async/Await, Structured Error Handling, Context Manager, Input Validation, Logging, Decorator, Factory, Dependency Injection, Retry, Caching, Singleton, Observer, Rate Limiting, Circuit Breaker

Critical for: Maintaining codebase consistency

4. `dep-graph` - Circular Dependency Detection

When: Before refactoring or adding imports What it does: Detects god objects, circular dependencies, fan-in/fan-out

python3 skill.py dep-graph src/auth

Output:

🎯 God Objects (files with >10 dependents)
🔁 Circular Dependencies (import cycles)
📊 Fan-in/Fan-out metrics
🏝️ Isolated Modules

Critical for: Understanding blast radius, avoiding circular imports

5. `context` - Historical Context

When: User asks "why" questions What it does: Provides targeted historical information

python3 skill.py context src/auth \
  --question "Why was JWT authentication chosen?"

Output:

⚠️ Revert warnings
🔍 Similar issues (keyword search)
📖 Evolution summary
🏗️ Design decisions

6. `design` - Design Doc Generation

When: Planning new features What it does: Generates design doc with historical intelligence

python3 skill.py design src/auth \
  --feature "OAuth 2.0 Authentication" \
  --description "Add OAuth 2.0 support for enterprise customers"

Output:

Historical context (reverts, activity, risk)
Pattern requirements (mandatory patterns)
Architectural constraints (god objects to avoid)
Similar features (prior art references)
Risk assessment

Critical for: Avoiding past mistakes, learning from similar features

7. `analyze` - Standard Timeline

When: Understanding component evolution What it does: Generates full timeline of folder changes

python3 skill.py analyze src/auth --format markdown

8. `dependencies` - Import Evolution

When: Understanding dependency history What it does: Tracks when each import was added/removed

python3 skill.py dependencies src/main.py

9. `patterns` - Pattern Introduction Timeline

When: Understanding when patterns were adopted What it does: Shows when each pattern first appeared

python3 skill.py patterns src/router.py

10. `discover` - Folder Discovery

When: Exploring unfamiliar codebase What it does: Categorizes and recommends folders to analyze

python3 skill.py discover
python3 skill.py suggest  # Top recommendations

Workflow Examples

Example 1: Fixing a Bug

User: "Fix the streaming timeout in router.py"

Claude automatically runs:

# Step 1: Risk analysis
python3 skill.py smart src/router --question "Fix streaming timeout"

# Output: "⚠️ CRITICAL RISK:
# - Previous REVERT on 2025-06-14
# - router.py is GOD OBJECT (12 dependents)
# - Risk Score: 87/100"

# Step 2: Function analysis
python3 skill.py file src/router.py --function handle_streaming

# Output: "🔥 HOTSPOT: handle_streaming() modified 47 times"

# Step 3: Pattern requirements
python3 skill.py pattern-adoption src/router

# Output: "MUST use: async (100%), error handling (100%), logging (50%)"

Claude then:

Informs user of CRITICAL risk findings
Recommends: Feature flag + comprehensive tests + senior review
Implements fix following ALL discovered patterns
Writes tests based on hotspot analysis

Example 2: Adding New Feature

User: "Add OAuth 2.0 authentication to proxy/auth"

Claude automatically runs:

# Step 1: Pattern requirements
python3 skill.py pattern-adoption src/auth

# Output: "Mandatory patterns: Input Validation (83%), Error Handling (100%), Logging (67%)"

# Step 2: Architecture check
python3 skill.py dep-graph src/auth

# Output: "⚠️ WARNING: auth/__init__.py is GOD OBJECT (15 dependents)"

# Step 3: Generate design doc
python3 skill.py design src/auth \
  --feature "OAuth 2.0" \
  --description "Add OAuth 2.0 authentication"

# Output: Complete design doc with historical context, risks,
# and local prior art references

Claude then:

Shows user the design doc
Explains architectural constraints (avoid adding to god object)
Implements following mandatory patterns
Creates new module to avoid god object growth

Example 3: Answering "Why" Question

User: "Why is authentication implemented with JWT instead of sessions?"

Claude automatically runs:

python3 skill.py context src/auth \
  --question "Why JWT instead of sessions"

# Output:
# - Historical context from commit messages
# - Design decision from 2024-03: "Use JWT for stateless auth"
# - Similar issues mentioning "session", "jwt", "stateless"

Critical Warnings

When the skill outputs these warnings, STOP and inform the user:

⚠️ REVERTS DETECTED

Meaning: Previous attempts to modify this code failed and were reverted Action:

Escalate risk to HIGH/CRITICAL
Require tests BEFORE fix
Recommend feature flag
Get senior engineer review
Ask user if they want to proceed with caution

⚠️ GOD OBJECT

Meaning: File >2000 lines OR >10 files depend on it Action:

Warn about blast radius
Test all dependents after changes
Consider refactoring before adding features
Recommend creating new module instead

⚠️ HOTSPOT

Meaning: Function modified >20 times in history Action:

Mark as bug-prone
Require comprehensive tests
Consider refactoring/simplification
Extra scrutiny in code review

⚠️ PATTERN VIOLATIONS

Meaning: File missing patterns used in >50% of similar files Action:

Enforce pattern compliance in new code
List mandatory patterns to user
Reject code that violates established conventions

Output Interpretation

Risk Levels

Score	Level	Actions Required
0-25	LOW	Standard testing, normal review
26-50	MEDIUM	Standard testing, careful review
51-75	HIGH	Feature flag, extra tests, senior review
76-100	CRITICAL	Feature flag, comprehensive tests, senior + principal review, gradual rollout

Pattern Adoption Thresholds

Adoption	Meaning	Action
>80%	Strong consensus	MUST use in all new code
50-80%	Established pattern	SHOULD use in new code
20-50%	Emerging pattern	Consider using
<20%	Rare/experimental	Optional

Supporting Documentation

README.md: Complete feature documentation
FINAL_SYSTEM_OVERVIEW.md: Architecture and value proposition
CLAUDE_CODE_INTEGRATION.md: Integration guide for Claude Code
FILE_LEVEL_ANALYSIS.md: Function evolution details
COUNTERFACTUAL_VALUE.md: Proof of value methodology

Performance

Small folders (<100 commits): <1 second
Medium folders (100-500 commits): 2-5 seconds
Large folders (>500 commits): 5-10 seconds
Full repo discovery: 10-30 seconds

All commands default to analyzing last 500 commits for performance.

Dependencies

Python 3.8+
Git (for history analysis)
Repository must be a git repository

Troubleshooting

No commits found: Ensure you're in a git repository and folder path is correct

Slow performance: Use --format compact or reduce commit depth

Function not found: Function detection uses regex, may not find all functions in complex syntax

Remember: This skill's value is PROACTIVE use BEFORE changes, not reactive use AFTER problems occur. Always run smart analysis before modifying code!

About this skill

When to Use This Skill (Auto-Invocation Guide)

🚨 ALWAYS Before Modifying Code

🤔 When User Asks "Why" Questions

Available Commands

1. smart - Adaptive Risk Analysis (MOST IMPORTANT)

2. file - Function-Level Hotspot Detection

3. pattern-adoption - Consistency Enforcement

4. dep-graph - Circular Dependency Detection

5. context - Historical Context

6. design - Design Doc Generation

7. analyze - Standard Timeline

8. dependencies - Import Evolution

9. patterns - Pattern Introduction Timeline

10. discover - Folder Discovery

Workflow Examples

Example 1: Fixing a Bug

Example 2: Adding New Feature

Example 3: Answering "Why" Question

Critical Warnings

⚠️ REVERTS DETECTED

⚠️ GOD OBJECT

⚠️ HOTSPOT

⚠️ PATTERN VIOLATIONS

Output Interpretation

Risk Levels

Pattern Adoption Thresholds

Supporting Documentation

Performance

Dependencies

Troubleshooting

1. `smart` - Adaptive Risk Analysis (MOST IMPORTANT)

2. `file` - Function-Level Hotspot Detection

3. `pattern-adoption` - Consistency Enforcement

4. `dep-graph` - Circular Dependency Detection

5. `context` - Historical Context

6. `design` - Design Doc Generation

7. `analyze` - Standard Timeline

8. `dependencies` - Import Evolution

9. `patterns` - Pattern Introduction Timeline

10. `discover` - Folder Discovery