quality-detect-refactor-markers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

detect-refactor-markers

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.

通过检测代码库中所有活跃的REFACTOR标记、验证相关ADR是否存在，以及识别过期标记（超过30天）、孤立标记（缺失ADR）和已完成但未移除的标记等问题，来监控重构健康状况。这对于保持清晰的重构跟踪、防止技术债务累积，以及确保重构工作得到妥善记录和完成至关重要。

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"

在以下场景中使用本工具：

用户询问“what's the status”或“how's the refactor going”
标记功能完成前（@feature-completer）
进度检查期间（@statuser）
执行架构健康审计时（@architecture-guardian）
用户提及“refactor”或“markers”
每周健康检查（定时监控）
开始新重构前（检查现有工作）
用户要求“check refactor status”或“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

快速入门 - 检查代码库中REFACTOR标记的健康状况
操作说明 - 5步检测与验证流程
- 步骤1：查找所有REFACTOR标记 - 使用grep查找文件级和方法级标记
- 步骤2：解析标记信息 - 提取ADR编号、状态、日期
- 步骤3：验证关联ADR - 检查ADR文件是否存在
- 步骤4：检测过期标记 - 计算标记存在时长和完成状态
- 步骤5：生成健康报告 - 分类报告及建议
健康分类 - 标记健康状况分类
- 健康标记 ✅ - ADR有效，存在时长<30天
- 过期标记 ⚠️ - 存在时长>30天，需复查
- 孤立标记 ❌ - 缺失ADR，需清理
- 应移除标记 🔴 - ADR已完成，但标记仍存在
使用模式](#使用模式) - 与Agent和工作流的集成

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

健康分类指南 - 详细健康分类逻辑
修复指南 - 分步修复说明
边缘场景 - 特殊场景处理
集成点 - 与其他工具和Agent的集成
反模式 - 禁止操作
最佳实践 - 推荐方法
成功标准 - 质量指标
故障排查 - 常见问题与解决方案
输出格式 - 报告结构示例
要求 - 依赖项和项目上下文

Quick Start

快速入门

Check refactor marker health across your codebase:

bash

undefined

检查代码库中的REFACTOR标记健康状况：

bash

undefined

Find all REFACTOR markers (file-level and method-level)

查找所有REFACTOR标记（文件级和方法级）

grep -rn "^# REFACTOR:" src/ --include=".py" grep -rn "# REFACTOR(" src/ --include=".py"

Validate ADR existence

验证ADR是否存在

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

Calculate marker age (if STARTED date present)

计算标记存在时长（如果包含STARTED日期）

Current date - STARTED date > 30 days = STALE

当前日期 - STARTED日期 > 30天 = 过期


**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


**典型输出：**
- ✅ 健康：所有标记均有有效ADR，存在时长<30天
- ⚠️ 过期：标记存在时长>30天（需复查）
- ❌ 孤立：标记缺失对应ADR（需清理）
- 🔴 应移除：ADR已完成但标记仍存在

Instructions

操作说明

Step 1: Find All REFACTOR Markers

步骤1：查找所有REFACTOR标记

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)

使用grep定位两种类型的标记：

文件级标记：

bash

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

方法级标记：

bash

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

从每个匹配项中提取：

文件路径
行号
ADR编号（格式：ADR-XXX）
状态（如果存在：IN_PROGRESS、BLOCKED、REVIEW）
开始日期（如果存在：YYYY-MM-DD）

Step 2: Parse Marker Information

步骤2：解析标记信息

File-level marker format:

python

undefined

文件级标记格式：

python

undefined

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


**方法级标记格式：**
```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

def get_user(user_id: int): pass


**解析逻辑：**
- 使用正则表达式提取ADR编号：`ADR-(\\d+)`
- 从`# STATUS:`行提取状态
- 从`# STARTED:`行提取开始日期（YYYY-MM-DD）
- 从`# PERMANENT_RECORD:`行提取ADR路径
- 存储唯一ADR编号用于验证

Step 3: Validate Associated ADRs

步骤3：验证关联ADR

For each unique ADR number found:

Check ADR existence:

bash

undefined

对于每个找到的唯一ADR编号：

检查ADR是否存在：

bash

undefined

Search for ADR file in all ADR directories

在所有ADR目录中搜索ADR文件

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

find docs/adr -name "027-.md" -type f


**验证结果：**
- ✅ 有效：ADR文件存在，标记健康
- ❌ 孤立：未找到ADR文件（已删除、移动或编号错误）

**需检查的ADR位置模式：**
```bash
docs/adr/in_progress/XXX-title.md     # 活跃重构
docs/adr/implemented/XXX-title.md     # 已完成重构
docs/adr/deprecated/XXX-title.md      # 已弃用重构

Step 4: Detect Stale Markers

步骤4：检测过期标记

Calculate marker age:

bash

undefined

计算标记存在时长：

bash

undefined

For markers with STARTED date

对于包含STARTED日期的标记

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 [ $AGE_DAYS -gt 30 ]; then echo "⚠️ 过期：标记已存在$AGE_DAYS天" fi


**过期判定标准：**
- 存在时长>30天 = ⚠️ 过期
- ADR状态为IN_PROGRESS但无近期更新 = ⚠️ 过期
- 若工作看似已停滞，也判定为过期

**检查ADR完成状态：**
```bash

If ADR moved to implemented/ but markers remain

若ADR已移至implemented/但标记仍存在

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

undefined

if [ -f docs/adr/implemented/027-*.md ]; then echo "🔴 应移除：ADR已完成但标记仍存在" fi

undefined

Step 5: Generate Health Report

步骤5：生成健康报告

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

报告结构：

yaml

health: GOOD | ATTENTION_NEEDED | CRITICAL
active_refactors:
  - adr: ADR-XXX
    title: 来自ADR的标题
    files: 包含标记的文件数量
    markers: 标记总数
    age_days: 从STARTED日期起的时长
    status: IN_PROGRESS | BLOCKED | REVIEW
    adr_valid: true | false
stale_markers: []
orphaned_markers: []
should_be_removed: []
summary: 可读摘要

健康分类：

GOOD（良好）： 所有标记有效，无过期/孤立标记，所有ADR均活跃
ATTENTION_NEEDED（需关注）： 存在过期标记（>30天）
CRITICAL（严重）： 存在孤立标记或应移除标记问题

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

ADR文件存在且有效
ADR状态与标记状态匹配
存在时长<30天（若包含STARTED日期）
有活跃跟踪机制
无阻塞问题

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

自STARTED日期起存在时长>30天
状态仍显示为IN_PROGRESS
ADR文件无近期更新
重构耗时超出预期
操作建议： 复查进度、更新ADR或完成工作

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

ADR文件不存在（404）
ADR已删除但未移除标记
标记引用不存在的ADR编号
标记中的ADR编号错误
操作建议： 查找正确ADR或移除标记

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)

ADR状态为COMPLETE或IMPLEMENTED
ADR已移至
```
docs/adr/implemented/
```
目录
标记仍存在于源代码中
重构工作已完成但未清理标记
操作建议： 使用manage-refactor-markers工具移除所有标记

Usage Patterns

使用模式

Pattern 1: Status Check Integration (@statuser)

模式1：状态检查集成（@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

用户：“我的功能进度如何？”

@statuser工作流：
1. 检查todo.md状态（TodoRead）
2. 检查质量指标（pytest、pyright）
3. 调用detect-refactor-markers工具
4. 在状态报告中包含重构健康状况

报告包含：
- 任务完成百分比
- 质量门状态
- 重构健康状况
- 阻塞问题

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

模式2：完成前检查（@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

用户：“标记功能为已完成”

@feature-completer工作流：
1. 验证所有任务已完成
2. 验证质量门已通过
3. 调用detect-refactor-markers工具
4. 若存在标记则阻止完成

决策逻辑：
- 若存在活跃标记：❌ 阻止完成
  - 原因：“存在活跃重构标记，无法完成功能”
  - 操作：“先完成或移除标记”
- 若不存在标记：✅ 允许完成

Pattern 3: Refactor Health Audit

模式3：重构健康审计

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

用户：“重构进展如何？” 或 “检查重构状态”

Agent工作流：
1. 调用detect-refactor-markers工具
2. 生成全面健康报告
3. 针对每个问题推荐操作

报告章节：
- 活跃重构摘要
- 过期标记（按存在时长排序优先级）
- 孤立标记（需立即清理）
- 完成建议

Pattern 4: Proactive Monitoring

模式4：主动监控

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)

应自动调用本工具的Agent：

@statuser（每次状态检查）
@architecture-guardian（架构健康审计）
@feature-completer（标记完成前）
@implementer（可选：开始新重构前）

触发条件：

用户询问“状态”或“进度”
用户要求“完成”或“结束”功能
用户提及“refactor”或“markers”
每周健康检查（定时）

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.

下方输出格式章节展示了全面的报告示例，包括：

健康重构状态
过期标记检测
孤立标记检测
应移除标记检测
多ADR场景

详细健康分类逻辑请参考references/health-categories-guide.md。

每种问题类型的分步修复说明请参考references/remediation-guide.md。

Edge Cases

边缘场景

No Markers Found

未找到任何标记

bash

undefined

bash

undefined

Grep returns no results

Grep无返回结果

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

(no output)

（无输出）

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

undefined

报告： ✅ 无活跃重构（健康状态）代码库整洁，无进行中的迁移工作。

undefined

Markers Without STARTED Date

无STARTED日期的标记

python

undefined

python

undefined

Old marker format (missing STARTED field)

旧标记格式（缺失STARTED字段）

REFACTOR: ADR-015 - Database Migration

STATUS: IN_PROGRESS

(no STARTED date)

（无STARTED日期）

Handling:

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

undefined

处理方式：

无法计算存在时长
报告为“存在时长未知（缺失STARTED日期）”
建议添加STARTED日期

undefined

Method-Only Markers (No File-Level Marker)

仅存在方法级标记（无文件级标记）

python

undefined

python

undefined

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)

undefined

def update_user(): pass

报告： ✅ 有效标记（仅方法级）文件：src/services/user_service.py 标记：2个方法级标记（无文件级标记）

undefined

Multiple ADRs in One File

单个文件中存在多个ADR标记

python

undefined

python

undefined

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)

undefined

def process_payment(): pass

报告： ✅ 文件中存在多个活跃重构文件：src/services/payment_service.py

ADR-027: ServiceResult Migration（文件级）
ADR-042: Payment Refactor（1个方法级标记）

undefined

ADR Moved Between Directories

ADR在目录间移动

bash

undefined

bash

undefined

Marker references old path

标记引用旧路径

PERMANENT_RECORD: docs/adr/in_progress/027-service-result-migration.md

But ADR actually at:

但ADR实际位于：

docs/adr/implemented/027-service-result-migration.md

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

undefined

docs/adr/implemented/027-service-result-migration.md

检测结果： 🔴 应移除：ADR已移至implemented/目录操作：移除标记（重构已完成）

undefined

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

与manage-refactor-markers工具集成：

detect-refactor-markers识别问题
manage-refactor-markers修复问题（移除、更新）
工作流：检测 → 报告 → 管理 → 验证

与validate-refactor-adr工具集成：

两者均验证ADR存在性
detect-refactor-markers：批量验证（所有标记）
validate-refactor-adr：单个ADR验证（详细）

与@statuser Agent集成：

主要集成点
包含在每次状态检查中
重构健康状况添加至状态报告

与@architecture-guardian Agent集成：

架构健康审计
检测重构债务累积
强制执行完成策略

与@feature-completer Agent集成：

若存在标记则阻止功能完成
确保干净完成（无未完成重构）
验证所有工作已完成

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
```

❌ 禁止： 忽略孤立标记

原因：污染代码库，混淆开发者
影响：技术债务累积
修复：立即移除

❌ 禁止： 标记过期却不处理

原因：表明工作已停滞或被放弃
影响：阻碍未来重构，所有权不明确
修复：复查进度、更新ADR或完成工作

❌ 禁止： 移除仍有未完成工作的标记

原因：丢失未完成迁移的跟踪
影响：重构不完整，代码库不一致
修复：先完成工作，再移除标记

❌ 禁止： 遗漏检查所有文件类型

原因：TypeScript/JavaScript标记可能被忽略
影响：健康状况视图不完整
修复：始终检查.py、.ts、.js文件

❌ 禁止： 跳过ADR验证

原因：默认假设ADR存在
影响：健康报告不准确，孤立标记未被检测
修复：始终使用
```
find
```
或
```
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

✅ 推荐： 定期运行健康检查

频率：每周或功能完成前
集成：作为状态检查的一部分
自动化：@statuser自动调用

✅ 推荐： 立即清理孤立标记

严重问题需立即处理
使用manage-refactor-markers工具移除
重新检测验证清理结果

✅ 推荐： 每月复查过期标记

评估工作是否应继续
更新ADR状态或完成工作
关闭已放弃的重构

✅ 推荐： 信任标记前先验证ADR存在性

绝不默认假设ADR存在
使用
```
find docs/adr -name "*XXX-*.md"
```
进行检查
将缺失ADR报告为严重问题

✅ 推荐： ADR完成后移除标记

检查
```
docs/adr/implemented/
```
目录
干净移除可防止技术债务
使用manage-refactor-markers工具批量移除

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)

✅ 找到所有标记（grep成功遍历所有文件类型）
✅ ADR验证准确（正确判定存在/缺失）
✅ 过期判定正确（检测存在时长>30天的标记）
✅ 健康报告清晰（分类问题并统计数量）
✅ 建议可执行（针对每个问题提供具体下一步操作）
✅ 与Agent工作流集成（状态检查、完成门禁）

Troubleshooting

故障排查

Issue: Grep finds no markers but you know they exist

bash

undefined

问题：Grep未找到标记但已知标记存在

bash

undefined

Possible causes:

可能原因：

1. Wrong directory (not in project root)

pwd # Check current directory cd /path/to/project/root

pwd # 检查当前目录 cd /path/to/project/root

2. Wrong pattern (marker format different)

2. 模式错误（标记格式不同）

Try broader search:

尝试更宽泛的搜索：

grep -rn "REFACTOR" src/

3. Markers in different file types

3. 标记存在于其他文件类型中

grep -rn "REFACTOR" src/ --include=".py" --include=".ts" --include=".js" --include=".tsx"


**Issue:** ADR validation always reports "missing"
```bash

grep -rn "REFACTOR" src/ --include=".py" --include=".ts" --include=".js" --include=".tsx"


**问题：ADR验证始终报告“缺失”**
```bash

Check ADR directory structure

检查ADR目录结构

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


**问题：时长计算失败**
```bash

Check date format in marker

检查标记中的日期格式

Expected: YYYY-MM-DD (2025-10-16)

预期格式：YYYY-MM-DD（2025-10-16）

If different format, parsing will fail

若格式不同，解析会失败

Verify date command works

验证date命令可用

date +%Y-%m-%d

For macOS vs Linux compatibility:

macOS与Linux兼容性：

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


**问题：代码库中存在多种标记格式**
```bash

Handle variation:

处理格式差异：

Format 1: # REFACTOR: ADR-027 - Title

格式1: # REFACTOR: ADR-027 - Title

Format 2: # REFACTOR(ADR-027): Description

格式2: # REFACTOR(ADR-027): Description

Format 3: # REFACTOR [ADR-027] Title

格式3: # REFACTOR [ADR-027] Title

Use flexible regex:

使用灵活的正则表达式：

grep -rn "REFACTOR.*ADR-[0-9]" src/

Extract ADR number with sed:

使用sed提取ADR编号：

sed -n 's/.ADR-([0-9]+)./\1/p'

undefined

sed -n 's/.ADR-$[0-9]\+$./\1/p'

undefined

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)

健康报告：

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: 所有重构均健康。1个活跃重构（ADR-027），在2个文件中包含10个标记。

不健康报告：

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: 过期（超过30天未完成）
    action: 复查进度、更新ADR状态或完成工作
orphaned_markers:
  - adr: ADR-042
    file: src/services/payment_service.py
    markers: 4
    issue: 在所有docs/adr目录中未找到ADR文件
    possible_causes:
      - ADR已删除但未移除标记
      - ADR已移至其他目录
      - 标记中的ADR编号错误
    action: |
      1. 搜索ADR：find docs/adr -name "*payment*"
      2. 若找到：更新标记中的ADR编号
      3. 若未找到：使用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已完成并移至implemented/目录，但标记仍存在
    action: 使用manage-refactor-markers工具移除所有标记
summary: |
  存在3个严重问题需处理：
  - 1个过期标记（ADR-015，已存在45天）
  - 1组孤立标记（ADR-042，4个标记）
  - 1组应移除标记（ADR-028，12个标记）

  推荐处理优先级：
  1. 移除孤立的ADR-042标记（严重）
  2. 移除已完成的ADR-028标记（清理）
  3. 复查过期的ADR-015重构（评估是否继续）

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

无需外部依赖。 本工具仅使用内置工具：

```
grep
```
: 在源文件中查找标记
```
find
```
: 定位ADR文件
```
test -f
```
: 验证文件存在性
```
date
```
: 计算标记存在时长

需要项目上下文：

```
.claude/refactor-marker-guide.md
```
: 标记格式参考
```
docs/adr/
```
: ADR目录结构
源文件位于
```
src/
```
目录

另请参阅：

references/health-categories-guide.md - 健康分类详情
references/remediation-guide.md - 每种问题类型的修复说明",

quality-detect-refactor-markers

Original

Translation

detect-refactor-markers

detect-refactor-markers

Table of Contents

目录

Purpose

用途

When to Use

适用场景

Core Sections (Detailed TOC)

核心章节（详细目录）

Supporting Resources

支持资源

Quick Start

快速入门

Find all REFACTOR markers (file-level and method-level)

查找所有REFACTOR标记（文件级和方法级）

Validate ADR existence

验证ADR是否存在

Calculate marker age (if STARTED date present)

计算标记存在时长（如果包含STARTED日期）

Current date - STARTED date > 30 days = STALE

当前日期 - STARTED日期 > 30天 = 过期

Instructions

操作说明

Step 1: Find All REFACTOR Markers

步骤1：查找所有REFACTOR标记

Step 2: Parse Marker Information

步骤2：解析标记信息

REFACTOR: ADR-027 - ServiceResult Migration

REFACTOR: ADR-027 - ServiceResult Migration

STATUS: IN_PROGRESS

STATUS: IN_PROGRESS

STARTED: 2025-10-10

STARTED: 2025-10-10

PERMANENT_RECORD: docs/adr/in_progress/027-service-result-migration.md

PERMANENT_RECORD: docs/adr/in_progress/027-service-result-migration.md

REFACTOR(ADR-027): Migrate to ServiceResult pattern

REFACTOR(ADR-027): Migrate to ServiceResult pattern

Step 3: Validate Associated ADRs

步骤3：验证关联ADR

Search for ADR file in all ADR directories

在所有ADR目录中搜索ADR文件

Step 4: Detect Stale Markers

步骤4：检测过期标记

For markers with STARTED date

对于包含STARTED日期的标记

Check if stale

检查是否过期

If ADR moved to implemented/ but markers remain

若ADR已移至implemented/但标记仍存在

Step 5: Generate Health Report

步骤5：生成健康报告

Health Categories

健康分类

Healthy Marker ✅

健康标记 ✅

Stale Marker ⚠️

过期标记 ⚠️

Orphaned Marker ❌

孤立标记 ❌

Should Be Removed 🔴

应移除标记 🔴

Usage Patterns

使用模式

Pattern 1: Status Check Integration (@statuser)

模式1：状态检查集成（@statuser）

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

模式2：完成前检查（@feature-completer）

Pattern 3: Refactor Health Audit

模式3：重构健康审计

Pattern 4: Proactive Monitoring

模式4：主动监控

Examples

示例

Edge Cases

边缘场景

No Markers Found