detect-refactor-markers

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

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:

bash

# 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:

bash

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

Method-level markers:

bash

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:

python

# 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:

python

# 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:

bash

# 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:

bash

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:

bash

# 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:

bash

# 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:

yaml

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)

code

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)

code

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

code

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

bash

# 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

python

# 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)

python

# 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

python

# 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

bash

# 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

bash

# 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"

bash

# 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

bash

# 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

bash

# 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:

yaml

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:

yaml

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

quality-detect-refactor-markers

detect-refactor-markers

Table of Contents

Purpose

When to Use

Core Sections (Detailed TOC)

Supporting Resources

Quick Start

Instructions

Step 1: Find All REFACTOR Markers

Step 2: Parse Marker Information

Step 3: Validate Associated ADRs

Step 4: Detect Stale Markers

Step 5: Generate Health Report

Health Categories

Healthy Marker ✅

Stale Marker ⚠️

Orphaned Marker ❌

Should Be Removed 🔴

Usage Patterns

Pattern 1: Status Check Integration (@statuser)

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

Pattern 3: Refactor Health Audit

Pattern 4: Proactive Monitoring

Examples

Edge Cases

No Markers Found

Markers Without STARTED Date

Method-Only Markers (No File-Level Marker)

Multiple ADRs in One File

ADR Moved Between Directories

Integration Points

Anti-Patterns

Best Practices

Success Criteria

Troubleshooting

Output Format

Requirements