quality-detect-refactor-markers

What this skill does

# detect-refactor-markers

## Table of Contents

**Quick Start** → [What Is This](#purpose) | [When to Use](#when-to-use) | [Simple Example](#quick-start)

**Validation Flow** → [Find Markers](#step-1-find-all-refactor-markers) | [Validate ADRs](#step-3-validate-associated-adrs) | [Health Report](#step-5-generate-health-report)

**Help** → [Troubleshooting](#troubleshooting) | [Anti-Patterns](#anti-patterns) | [Best Practices](#best-practices)

**Reference** → [Health Categories](./references/health-categories-guide.md) | [Remediation Guide](./references/remediation-guide.md)

## 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](#quick-start) - Check refactor marker health across codebase
- [Instructions](#instructions) - 5-step detection and validation process
  - [Step 1: Find All REFACTOR Markers](#step-1-find-all-refactor-markers) - Grep for file-level and method-level markers
  - [Step 2: Parse Marker Information](#step-2-parse-marker-information) - Extract ADR number, status, dates
  - [Step 3: Validate Associated ADRs](#step-3-validate-associated-adrs) - Check ADR file existence
  - [Step 4: Detect Stale Markers](#step-4-detect-stale-markers) - Calculate age and completion status
  - [Step 5: Generate Health Report](#step-5-generate-health-report) - Categorized report with recommendations
- [Health Categories](#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](#usage-patterns) - Integration with agents and workflows
  - [Pattern 1: Status Check Integration (@statuser)](#pattern-1-status-check-integration-statuser)
  - [Pattern 2: Pre-Completion Check (@feature-completer)](#pattern-2-pre-completion-check-feature-completer)
  - [Pattern 3: Refactor Health Audit](#pattern-3-refactor-health-audit)
  - [Pattern 4: Proactive Monitoring](#pattern-4-proactive-monitoring)

### Supporting Resources
- [Health Categories Guide](./references/health-categories-guide.md) - Detailed health classification logic
- [Remediation Guide](./references/remediation-guide.md) - Step-by-step fix instructions
- [Edge Cases](#edge-cases) - Handling special scenarios
- [Integration Points](#integration-points) - Integration with other skills and agents
- [Anti-Patterns](#anti-patterns) - What NOT to do
- [Best Practices](#best-practices) - Recommended approaches
- [Success Criteria](#success-criteria) - Quality metrics
- [Troubleshooting](#troubleshooting) - Common issues and solutions
- [Output Format](#output-format) - Report structure examples
- [Requirements](#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