detect-refactor-markers

Table of Contents

Quick Start → What Is This | When to Use | Simple Example

Validation Flow → Find Markers | Validate ADRs | Health Report

Help → Troubleshooting | Anti-Patterns | Best Practices

Reference → Health Categories | Remediation Guide

Purpose

Monitors refactor health by detecting all active REFACTOR markers in the codebase, validating their associated ADRs exist, and identifying issues such as stale markers (>30 days old), orphaned markers (missing ADR), and completed-but-not-removed markers. Essential for maintaining clean refactor tracking, preventing technical debt accumulation, and ensuring refactor work is properly documented and completed.

When to Use

Use this skill when:

• User asks "what's the status" or "how's the refactor going"
• Before marking a feature as complete (@feature-completer)
• During progress checks (@statuser)
• Performing architecture health audits (@architecture-guardian)
• User mentions "refactor" or "markers"
• Weekly health check (scheduled monitoring)
• Before starting a new refactor (check existing work)
• User asks to "check refactor status" or "audit markers"

Core Sections (Detailed TOC)

• Quick Start - Check refactor marker health across codebase
• Instructions - 5-step detection and validation process
  • Step 1: Find All REFACTOR Markers - Grep for file-level and method-level markers
  • Step 2: Parse Marker Information - Extract ADR number, status, dates
  • Step 3: Validate Associated ADRs - Check ADR file existence
  • Step 4: Detect Stale Markers - Calculate age and completion status
  • Step 5: Generate Health Report - Categorized report with recommendations
• Health Categories - Marker health classification
  • Healthy Marker ✅ - Valid ADR, age < 30 days
  • Stale Marker ⚠️ - Age > 30 days, needs review
  • Orphaned Marker ❌ - Missing ADR, needs cleanup
  • Should Be Removed 🔴 - ADR complete, markers remain
• Usage Patterns - Integration with agents and workflows
  • Pattern 1: Status Check Integration (@statuser)
  • Pattern 2: Pre-Completion Check (@feature-completer)
  • Pattern 3: Refactor Health Audit
  • Pattern 4: Proactive Monitoring

Supporting Resources

• Health Categories Guide - Detailed health classification logic
• Remediation Guide - Step-by-step fix instructions
• Edge Cases - Handling special scenarios
• Integration Points - Integration with other skills and agents
• Anti-Patterns - What NOT to do
• Best Practices - Recommended approaches
• Success Criteria - Quality metrics
• Troubleshooting - Common issues and solutions
• Output Format - Report structure examples
• Requirements - Dependencies and project context

Quick Start

Check refactor marker health across your codebase:

# Find all REFACTOR markers (file-level and method-level)
grep -rn "^# REFACTOR:" src/ --include="*.py"
grep -rn "# REFACTOR(" src/ --include="*.py"

# Validate ADR existence
test -f docs/adr/in_progress/027-service-result-migration.md && echo "ADR exists" || echo "ADR missing"

# Calculate marker age (if STARTED date present)
# Current date - STARTED date > 30 days = STALE

Typical output:

• ✅ Healthy: All markers have valid ADRs, age < 30 days
• ⚠️ Stale: Markers > 30 days old (needs review)
• ❌ Orphaned: Markers with missing ADRs (needs cleanup)
• 🔴 Should Remove: ADR complete but markers remain

Instructions

Step 1: Find All REFACTOR Markers

Use grep to locate both marker types:

File-level markers:

grep -rn "^# REFACTOR:" src/ --include="*.py" --include="*.ts" --include="*.js"

Method-level markers:

grep -rn "# REFACTOR(" src/ --include="*.py" --include="*.ts" --include="*.js"

Extract from each match:

• File path
• Line number
• ADR number (format: ADR-XXX)
• Status (if present: IN_PROGRESS, BLOCKED, REVIEW)
• STARTED date (if present: YYYY-MM-DD)

Step 2: Parse Marker Information

File-level marker format:

# REFACTOR: ADR-027 - ServiceResult Migration
# STATUS: IN_PROGRESS
# STARTED: 2025-10-10
# PERMANENT_RECORD: docs/adr/in_progress/027-service-result-migration.md

Method-level marker format:

# REFACTOR(ADR-027): Migrate to ServiceResult pattern
def get_user(user_id: int):
    pass

Parsing logic:

• Extract ADR number using regex: ADR-(\d+)
• Extract status from # STATUS: line
• Extract start date from # STARTED: line (YYYY-MM-DD)
• Extract ADR path from # PERMANENT_RECORD: line
• Store unique ADR numbers for validation

Step 3: Validate Associated ADRs

For each unique ADR number found:

Check ADR existence:

# Search for ADR file in all ADR directories
find docs/adr -name "*027-*.md" -type f

Validation outcomes:

• ✅ Valid: ADR file exists, marker is healthy
• ❌ Orphaned: ADR file not found (deleted, moved, or wrong number)

ADR location patterns to check:

docs/adr/in_progress/XXX-title.md     # Active refactors
docs/adr/implemented/XXX-title.md     # Completed refactors
docs/adr/deprecated/XXX-title.md      # Deprecated refactors

Step 4: Detect Stale Markers

Calculate marker age:

# For markers with STARTED date
STARTED_DATE="2025-09-01"
CURRENT_DATE=$(date +%Y-%m-%d)
AGE_DAYS=$((( $(date -d "$CURRENT_DATE" +%s) - $(date -d "$STARTED_DATE" +%s) ) / 86400))

# Check if stale
if [ $AGE_DAYS -gt 30 ]; then
    echo "⚠️ STALE: Marker is $AGE_DAYS days old"
fi

Staleness criteria:

• Age > 30 days = ⚠️ STALE
• ADR status IN_PROGRESS but no recent updates = ⚠️ STALE
• Consider stale if work appears abandoned

Check ADR completion status:

# If ADR moved to implemented/ but markers remain
if [ -f docs/adr/implemented/027-*.md ]; then
    echo "🔴 Should be removed: ADR complete but markers present"
fi

Step 5: Generate Health Report

Report structure:

health: GOOD | ATTENTION_NEEDED | CRITICAL
active_refactors:
  - adr: ADR-XXX
    title: Title from ADR
    files: Count of files with markers
    markers: Total marker count
    age_days: Age since STARTED date
    status: IN_PROGRESS | BLOCKED | REVIEW
    adr_valid: true | false
stale_markers: []
orphaned_markers: []
should_be_removed: []
summary: Human-readable summary

Health classification:

• GOOD: All markers valid, no stale/orphaned, all ADRs active
• ATTENTION_NEEDED: Stale markers present (>30 days)
• CRITICAL: Orphaned markers or should-be-removed issues

Health Categories

Healthy Marker ✅

• ADR file exists and is valid
• ADR status matches marker status
• Age < 30 days (if STARTED date present)
• Active tracking in place
• No blocking issues

Stale Marker ⚠️

• Age > 30 days since STARTED date
• Still shows IN_PROGRESS status
• No recent updates in ADR file
• Refactor taking longer than expected
• Action: Review progress, update ADR, or complete work

Orphaned Marker ❌

• ADR file doesn't exist (404)
• ADR was deleted without removing markers
• Marker references non-existent ADR number
• Incorrect ADR number in marker
• Action: Find correct ADR or remove markers

Should Be Removed 🔴

• ADR status is COMPLETE or IMPLEMENTED
• ADR moved to docs/adr/implemented/
• Markers still present in source code
• Refactor work done but cleanup incomplete
• Action: Remove all markers (use manage-refactor-markers)

Usage Patterns

Pattern 1: Status Check Integration (@statuser)

User: "What's my progress on the feature?"

@statuser workflow:
1. Check todo.md status (TodoRead)
2. Check quality metrics (pytest, pyright)
3. Invoke detect-refactor-markers skill
4. Include refactor health in status report

Report includes:
- Task completion percentage
- Quality gate status
- Refactor health status
- Blockers or issues

Pattern 2: Pre-Completion Check (@feature-completer)

User: "Mark feature complete"

@feature-completer workflow:
1. Verify all tasks complete
2. Verify quality gates pass
3. Invoke detect-refactor-markers skill
4. Block completion if markers present

Decision logic:
- If active markers found: ❌ Block completion
  - Reason: "Cannot complete feature with active refactor markers"
  - Action: "Complete or remove markers first"
- If no markers: ✅ Allow completion

Pattern 3: Refactor Health Audit

User: "How's the refactor going?" OR "Check refactor status"

Agent workflow:
1. Invoke detect-refactor-markers skill
2. Generate comprehensive health report
3. Recommend actions for each issue

Report sections:
- Active refactors summary
- Stale markers (prioritized by age)
- Orphaned markers (needs immediate cleanup)
- Completion suggestions

Pattern 4: Proactive Monitoring

Agents that should auto-invoke this skill:

• @statuser (every status check)
• @architecture-guardian (architecture health audits)
• @feature-completer (before marking complete)
• @implementer (optional: before starting new refactor)

Trigger conditions:

• User asks for "status" or "progress"
• User asks to "complete" or "finish" feature
• User mentions "refactor" or "markers"
• Weekly health check (scheduled)

Examples

The Output Format section below shows comprehensive report examples including:

• Healthy refactor status
• Stale marker detection
• Orphaned marker detection
• Should-be-removed detection
• Multi-ADR scenarios

See references/health-categories-guide.md for detailed health classification logic.

See references/remediation-guide.md for step-by-step fix instructions for each issue type.

Edge Cases

No Markers Found

# Grep returns no results
grep -rn "^# REFACTOR:" src/ --include="*.py"
# (no output)

Report:
✅ No active refactors (healthy state)
All code is clean, no ongoing migrations.

Markers Without STARTED Date

# Old marker format (missing STARTED field)
# REFACTOR: ADR-015 - Database Migration
# STATUS: IN_PROGRESS
# (no STARTED date)

Handling:
- Can't calculate age
- Report as "Unknown age (missing STARTED date)"
- Recommend adding STARTED date

Method-Only Markers (No File-Level Marker)

# Valid: Method markers can exist without file marker
# REFACTOR(ADR-027): Migrate to ServiceResult
def get_user():
    pass

# REFACTOR(ADR-027): Migrate to ServiceResult
def update_user():
    pass

Report:
✅ Valid markers (method-only is allowed)
File: src/services/user_service.py
Markers: 2 method-level (no file-level)

Multiple ADRs in One File

# Valid: Multiple refactors can overlap
# REFACTOR: ADR-027 - ServiceResult Migration
# STATUS: IN_PROGRESS
# STARTED: 2025-10-10

# REFACTOR(ADR-042): Payment Service Refactor
def process_payment():
    pass

Report:
✅ Multiple active refactors in file
File: src/services/payment_service.py
- ADR-027: ServiceResult Migration (file-level)
- ADR-042: Payment Refactor (1 method marker)

ADR Moved Between Directories

# Marker references old path
# PERMANENT_RECORD: docs/adr/in_progress/027-service-result-migration.md

# But ADR actually at:
docs/adr/implemented/027-service-result-migration.md

Detection:
🔴 Should be removed: ADR moved to implemented/
Action: Remove markers (refactor complete)

Integration Points

With manage-refactor-markers skill:

• detect-refactor-markers identifies issues
• manage-refactor-markers fixes them (remove, update)
• Workflow: detect → report → manage → verify

With validate-refactor-adr skill:

• Both validate ADR existence
• detect-refactor-markers: Batch validation (all markers)
• validate-refactor-adr: Single ADR validation (detailed)

With @statuser agent:

• Primary integration point
• Included in every status check
• Refactor health added to status reports

With @architecture-guardian agent:

• Architecture health audits
• Detects refactor debt accumulation
• Enforces completion policies

With @feature-completer agent:

• Blocks feature completion if markers present
• Ensures clean completion (no pending refactors)
• Validates all work finished

Anti-Patterns

❌ DON'T: Ignore orphaned markers

• Reason: Pollutes codebase, confuses developers
• Impact: Technical debt accumulation
• Fix: Remove immediately

❌ DON'T: Let markers go stale without action

• Reason: Indicates stuck or abandoned work
• Impact: Blocks future refactors, unclear ownership
• Fix: Review progress, update ADR, or complete

❌ DON'T: Remove markers that still have work to do

• Reason: Loses tracking of incomplete migrations
• Impact: Partial refactors, inconsistent codebase
• Fix: Complete work first, then remove markers

❌ DON'T: Forget to check all file types

• Reason: TypeScript/JavaScript markers missed
• Impact: Incomplete health picture
• Fix: Always check .py, .ts, .js files

❌ DON'T: Skip ADR validation

• Reason: Assumes ADR exists without checking
• Impact: False health reports, orphaned markers undetected
• Fix: Always validate with find or test -f

Best Practices

✅ DO: Run health checks regularly

• Frequency: Weekly or before feature completion
• Integration: Part of status checks
• Automation: @statuser auto-invokes

✅ DO: Clean up orphaned markers immediately

• Critical issues require immediate action
• Use manage-refactor-markers remove
• Validate cleanup with re-detection

✅ DO: Review stale markers monthly

• Assess if work should continue
• Update ADR status or complete work
• Close abandoned refactors

✅ DO: Validate ADRs exist before trusting markers

• Never assume ADR presence
• Use find docs/adr -name "*XXX-*.md"
• Report missing ADRs as critical

✅ DO: Remove markers when ADR complete

• Check docs/adr/implemented/ directory
• Clean removal prevents technical debt
• Use manage-refactor-markers for batch removal

Success Criteria

• ✅ All markers found (grep successful across all file types)
• ✅ ADR validation accurate (correct exists/missing determination)
• ✅ Staleness calculation correct (age > 30 days detection)
• ✅ Clear health report (categorized issues with counts)
• ✅ Actionable recommendations (specific next steps for each issue)
• ✅ Integration with agent workflows (status checks, completion gates)

Troubleshooting

Issue: Grep finds no markers but you know they exist

# Possible causes:
# 1. Wrong directory (not in project root)
pwd  # Check current directory
cd /path/to/project/root

# 2. Wrong pattern (marker format different)
# Try broader search:
grep -rn "REFACTOR" src/

# 3. Markers in different file types
grep -rn "REFACTOR" src/ --include="*.py" --include="*.ts" --include="*.js" --include="*.tsx"

Issue: ADR validation always reports "missing"

# Check ADR directory structure
ls -R docs/adr/

# Expected structure:
# docs/adr/in_progress/
# docs/adr/implemented/
# docs/adr/deprecated/

# If different structure, adjust validation paths

Issue: Age calculation fails

# Check date format in marker
# Expected: YYYY-MM-DD (2025-10-16)
# If different format, parsing will fail

# Verify date command works
date +%Y-%m-%d

# For macOS vs Linux compatibility:
# macOS: date -j -f "%Y-%m-%d" "2025-10-16" +%s
# Linux: date -d "2025-10-16" +%s

Issue: Multiple marker formats in codebase

# Handle variation:
# Format 1: # REFACTOR: ADR-027 - Title
# Format 2: # REFACTOR(ADR-027): Description
# Format 3: # REFACTOR [ADR-027] Title

# Use flexible regex:
grep -rn "REFACTOR.*ADR-[0-9]" src/

# Extract ADR number with sed:
sed -n 's/.*ADR-\([0-9]\+\).*/\1/p'

Output Format

Healthy Report:

health: GOOD
active_refactors:
  - adr: ADR-027
    title: ServiceResult Migration
    files: 2
    markers: 10
    age_days: 6
    status: IN_PROGRESS
    adr_valid: true
    adr_path: docs/adr/in_progress/027-service-result-migration.md
stale_markers: []
orphaned_markers: []
should_be_removed: []
summary: All refactors healthy. 1 active refactor (ADR-027) with 10 markers across 2 files.

Unhealthy Report:

health: CRITICAL
active_refactors:
  - adr: ADR-027
    title: ServiceResult Migration
    files: 2
    markers: 10
    age_days: 6
    status: IN_PROGRESS
    adr_valid: true
stale_markers:
  - adr: ADR-015
    title: Database Migration
    file: src/infrastructure/database.py
    age_days: 45
    started: 2025-09-01
    status: IN_PROGRESS
    issue: Stale (>30 days without completion)
    action: Review progress, update ADR status, or complete work
orphaned_markers:
  - adr: ADR-042
    file: src/services/payment_service.py
    markers: 4
    issue: ADR file not found in any docs/adr directory
    possible_causes:
      - ADR deleted without removing markers
      - ADR moved to different directory
      - Incorrect ADR number in markers
    action: |
      1. Search for ADR: find docs/adr -name "*payment*"
      2. If found: Update marker ADR numbers
      3. If not found: Remove markers using manage-refactor-markers
should_be_removed:
  - adr: ADR-028
    title: Cache Layer Implementation
    files: 4
    markers: 12
    adr_status: COMPLETE
    adr_path: docs/adr/implemented/028-cache-layer.md
    issue: ADR complete and moved to implemented/ but markers remain
    action: Remove all markers using manage-refactor-markers remove
summary: |
  3 critical issues requiring attention:
  - 1 stale marker (ADR-015, 45 days old)
  - 1 orphaned marker set (ADR-042, 4 markers)
  - 1 should-be-removed set (ADR-028, 12 markers)

  Recommended priority:
  1. Remove orphaned ADR-042 markers (critical)
  2. Remove completed ADR-028 markers (cleanup)
  3. Review stale ADR-015 refactor (assess continuation)

Requirements

No external dependencies required. This skill uses only built-in tools:

• grep: Find markers in source files
• find: Locate ADR files
• test -f: Validate file existence
• date: Calculate marker age

Project context required:

• .claude/refactor-marker-guide.md: Marker format reference
• docs/adr/: ADR directory structure
• Source files in src/ directory

See also:

• references/health-categories-guide.md - Health classification details
• references/remediation-guide.md - Fix instructions for each issue type