| name | refactoring-lifecycle-management |
| description | RLM (Refactoring Lifecycle Management): Systematic methodology for managing the complete lifecycle of software refactoring initiatives through 6 phases (PROPOSAL → PLANNING → EXECUTION → VALIDATION → INTEGRATION → MONITORING) with bi-directional traceability, quality gates, and metrics-driven measurement. Use when managing multiple refactoring iterations, improving plan-execution alignment, establishing refactoring dashboard and traceability matrix, or coordinating team refactoring efforts. |
| argument-hint | ["phase|task-name"] |
| allowed-tools | Read, Glob, Grep, Bash, Edit, Write |
Refactoring Lifecycle Management (RLM)
Version: 1.1 (Integration Updates)
Status: ✅ Enhanced (V_instance=0.82, V_meta=0.85 + Skill Integration)
Domain: Refactoring process management
Author: Extracted from gemini-live-scribe BAIME experiment
Overview
Refactoring Lifecycle Management (RLM) is a systematic methodology for managing the complete lifecycle of software refactoring initiatives. RLM addresses the unique challenges of refactoring: temporal evolution, uncertainty in planning, multiple stakeholder audiences, and bi-directional traceability between process and state.
When to Use RLM
Use RLM when:
- Your project has multiple refactoring iterations (5+ planned or completed)
- Plan-execution alignment is poor (>40% deviation from original plans)
- Stakeholders need 20+ minutes to understand refactoring progress
- You can't trace which refactoring changed which architecture component
- Completion reports are inconsistent or missing key sections
Don't use RLM for:
- Generic documentation management (file organization, naming conventions)
- Single refactoring efforts (use simple completion report instead)
- Projects without refactoring artifacts (nothing to manage yet)
Key Benefits
Proven Results (from gemini-live-scribe validation):
- Discovery Efficiency: 10.9x improvement (180s → 16.5s average query time)
- Plan-Execution Alignment: 0.40 → 0.60 (+50% improvement)
- Traceability Coverage: 90% bi-directional (40/45 links working)
- Stakeholder Visibility: <5 minutes to understand progress (vs 20-30 minutes baseline)
Methodology Components
- 6-Phase Lifecycle Templates: PROPOSAL → PLANNING → EXECUTION → VALIDATION → INTEGRATION → MONITORING
- Refactoring Dashboard: Single entry point with metrics, timeline, status (650 lines)
- Traceability Matrix: Bi-directional mapping (plans ↔ executions ↔ state)
- Quality Gates: 6 checkpoints ensuring completeness before phase transitions
- Measurement System: V_instance (domain quality) + V_meta (methodology quality)
Skill Integration
Related Skills Overview
RLM coordinates with complementary skills for complete refactoring lifecycle management. This section explains how RLM integrates with other skills and when to use each one.
code-refactoring (Technical Methods):
- Purpose: Technical methods for code refactoring (TDD, patterns, metrics)
- Used in RLM Phases:
- EXECUTION phase: TDD workflow, refactoring patterns, metrics tracking
- VALIDATION phase: Metrics comparison, regression detection
- INTEGRATION phase: Merge to main, tag release, post-merge validation
- MONITORING phase: Metrics trend analysis, continuous improvement
- Skill Location: code-refactoring SKILL.md
- Quick Start: See "Quick Start with RLM" section in code-refactoring skill
- Key Value: Provides technical "HOW-TO" for refactoring implementation
documentation-management (Documentation Quality):
- Purpose: Write high-quality refactoring documentation
- Used in RLM Phases:
- EXECUTION phase: Quality checklists, documentation sync
- VALIDATION phase: Documentation quality validation, peer review
- INTEGRATION phase: Completion report writing, documentation updates
- Skill Location: documentation-management SKILL.md
- Key Value: Ensures documentation completeness and quality
documentation-organization (Documentation Structure):
- Purpose: Organize refactoring documentation effectively
- Used in RLM Phases:
- INTEGRATION phase: Evolution history, structure validation, cross-references
- MONITORING phase: Link validation, freshness checks
- Skill Location: documentation-organization SKILL.md
- Key Value: Maintains documentation structure and integrity
When to Use Each Skill
Use code-refactoring when:
- You need technical guidance on HOW to refactor code
- Example: "How do I apply TDD to this refactoring?"
- Example: "What patterns should I use for this complexity?"
- Example: "How do I measure refactoring success with metrics?"
- Entry Point: Use code-refactoring skill's "Quick Start with RLM" section
- Independence: Can be used standalone for quick refactoring tasks (2-4 hours)
Use documentation-management when:
- You need guidance on HOW to write refactoring documentation
- Example: "What sections should my completion report have?"
- Example: "How do I validate my documentation quality?"
- Example: "What templates should I use for refactoring docs?"
- Entry Point: Use documentation-management skill templates
Use documentation-organization when:
- You need guidance on HOW TO ORGANIZE refactoring documentation
- Example: "How should I structure my refactoring directory?"
- Example: "What naming convention should I use?"
- Example: "How do I add evolution history to state docs?"
- Entry Point: Use documentation-organization skill guidelines
Use RLM when:
- You need guidance on HOW TO MANAGE the refactoring process
- Example: "What phases does my refactoring need?"
- Example: "How do I track refactoring progress?"
- Example: "How do I ensure bi-directional traceability?"
- Example: "How do I coordinate team members?"
- Entry Point: This skill (RLM) - see Quick Start below
Skill Relationship Diagram
┌─────────────────────────────────┐
│ Refactoring Lifecycle │
│ Management (RLM) │
│ - Process Management │
│ - 6-Phase Lifecycle │
│ - Quality Gates │
│ - Traceability │
│ - Dashboard & Metrics │
└─────────────┬───────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ code-refactoring │ │ doc-mgmt │ │ doc-org │
│ - Technical │ │ - Quality │ │ - Structure │
│ Methods │ │ Writing │ │ - Organization │
│ - TDD Workflow │ │ - Templates │ │ - Naming │
│ - Patterns │ │ - Validation │ │ - Cross-references │
│ - Metrics │ │ │ │ │
└───────────────────┘ └───────────────────┘ └───────────────────┘
Used in: Used in: Used in:
EXECUTION EXECUTION INTEGRATION
VALIDATION VALIDATION MONITORING
INTEGRATION INTEGRATION
MONITORING
Legend:
→ RLM coordinates all skills
→ code-refactoring: Technical execution
→ doc-mgmt: Documentation quality
→ doc-org: Documentation structure
Integration Workflow
Complete Refactoring Project (All Skills Orchestrated by RLM):
-
PROPOSAL Phase (RLM primary):
- RLM: Create proposal, define objectives, identify scope
- code-refactoring: Provide technical assessment (complexity, patterns)
- doc-mgmt: Identify documentation needs
- doc-org: Assess documentation impact
-
PLANNING Phase (RLM primary):
- RLM: Create detailed plan, identify risks, define milestones
- code-refactoring: Estimate complexity, choose patterns, identify technical dependencies
- doc-mgmt: Plan documentation deliverables
- doc-org: Plan documentation structure updates
-
PREPARATION Phase (RLM primary):
- RLM: Setup environment, prepare dashboard, define quality gates
- code-refactoring: Capture baseline metrics (complexity, coverage)
- doc-mgmt: Prepare documentation templates
- doc-org: Verify documentation structure
-
EXECUTION Phase (RLM + code-refactoring + doc-mgmt):
- RLM: Process management, progress tracking, work log, completion report draft
- code-refactoring: TDD workflow (RED → GREEN → REFACTOR → COMMIT), refactoring patterns, metrics tracking
- doc-mgmt: Documentation sync, quality checklists
- doc-org: Maintain documentation structure
-
VALIDATION Phase (RLM + code-refactoring + doc-mgmt):
- RLM: Process validation, quality gates (≥80% threshold), overall score calculation
- code-refactoring: Metrics comparison (current vs baseline), test validation, regression detection
- doc-mgmt: Documentation quality validation, peer review
- doc-org: Structure validation
-
INTEGRATION Phase (RLM + code-refactoring + doc-mgmt + doc-org):
- RLM: Merge coordination, tag management, completion report finalization
- code-refactoring: Code integration (merge to main, tag release, post-merge validation)
- doc-mgmt: Completion report writing, documentation updates
- doc-org: Evolution history in state docs, cross-references, structure validation
-
MONITORING Phase (RLM + code-refactoring + doc-org):
- RLM: Feedback collection, improvement tracking, stakeholder updates
- code-refactoring: Metrics trend analysis, regression detection, continuous improvement
- doc-mgmt: Documentation quality monitoring
- doc-org: Link validation, freshness checks
Skill Boundary Clarification
RLM Handles (Process Management):
- Project management (phases, timelines, milestones, resources)
- Documentation management (completion reports, traceability matrix, dashboard)
- Quality gates (≥80% validation threshold, phase transitions)
- Team coordination (peer review, knowledge transfer, stakeholder updates)
- Process tracking (plan-execution alignment, deviation tracking)
code-refactoring Handles (Technical Methods):
- Technical execution (TDD workflow, refactoring patterns, incremental commits)
- Metrics measurement (baseline, comparison, trend analysis)
- Code quality (tests, coverage, complexity, performance)
- Integration (merge, tag, post-validation)
Overlap Areas (Clear Division of Responsibility):
- Metrics: RLM defines WHAT to measure (process metrics), code-refactoring defines HOW to measure (technical metrics)
- Validation: RLM defines quality gates (≥80% threshold), code-refactoring provides validation data (metrics comparison)
- Documentation: RLM manages completion reports and traceability, doc-mgmt provides quality methods, doc-org provides structure
- Integration: RLM coordinates merge and tag, code-refactoring performs technical merge steps, doc-org adds evolution history
Quick Reference Table
| Your Question | Use This Skill | Why? |
|---|
| "How do I manage my refactoring project?" | RLM | RLM provides 6-phase process management |
| "How do I apply TDD to this refactoring?" | code-refactoring | code-refactoring provides TDD workflow |
| "What patterns should I use for this complexity?" | code-refactoring | code-refactoring provides pattern selection |
| "What sections should my completion report have?" | doc-mgmt | doc-mgmt provides completion report template |
| "How should I organize my refactoring docs?" | doc-org | doc-org provides organization methods |
| "What are the quality gates for refactoring?" | RLM | RLM defines quality gates (≥80%) |
| "How do I measure refactoring success?" | code-refactoring | code-refactoring provides metrics framework |
| "How do I ensure bi-directional traceability?" | RLM | RLM provides traceability matrix |
Quick Start
Step 1: Establish Baseline (4-6 hours)
Measure current refactoring management state:
Output: Calculate baseline V_instance (typically 0.25-0.40)
Step 2: Create Core Artifacts (8-10 hours)
cp -r templates/* docs/refactoring/templates/
Step 3: Apply to Existing Work (6-8 hours)
Step 4: Measure Improvement (1-2 hours)
Expected Results: V_instance improvement of +0.20-0.35 in first iteration
Core Methodology
Process vs State Documents
Process Documents (docs/refactoring/):
- Describe what was done and how it evolved
- Time-bound, specific to an iteration
- Examples: Plans, completion reports, validation reports
State Documents (docs/specs/, docs/guides/, CLAUDE.md):
- Describe what exists and how to use it
- Static until next refactoring changes it
- Examples: Feature specs, usage guides, architecture docs
RLM's Core Value: Maintain bi-directional traceability between process and state
6-Phase Lifecycle
Phase 1: PROPOSAL (Problem Identification)
- Deliverables: Problem statement, proposed solution, impact assessment, alternative analysis, recommendation
- Template:
templates/proposal-phase-template.md
- Quality Gate: Problem clarity, solution completeness, impact quantified, alternatives analyzed
Phase 2: PLANNING (Detailed Execution Plan)
- Deliverables: SMART objectives, scope definition, task breakdown, estimates, dependencies, risks, success criteria
- Template:
templates/planning-phase-template.md
- Quality Gate: Objectives SMART, scope bounded, tasks decomposed, estimates realistic
Phase 3: EXECUTION (Implementation)
- Deliverables: Code implementation, tests, completion report with "Impact on Architecture State" section
- Template:
templates/execution-phase-template.md
- Quality Gate: Code quality verified, test coverage met, documentation complete, bi-directional traceability established
EXECUTION Phase Structure (Enhanced with code-refactoring integration):
# EXECUTION Phase: [Task Name]
## Part 1: Technical Workflow (code-refactoring)
### TDD-Based Refactoring
Follow Test-Driven Development cycle for each refactoring step:
1. **RED**: Write failing test
- Identify refactoring target (function, class, module)
- Write test that documents expected behavior
- Verify test fails (RED)
2. **GREEN**: Make minimal changes to pass
- Apply refactoring pattern (Extract Method, Extract Class, etc.)
- Run test suite
- Ensure all tests pass (GREEN)
3. **REFACTOR**: Clean up code
- Remove duplication
- Improve names (variables, functions, classes)
- Extract methods/classes for clarity
- Ensure tests still pass
4. **COMMIT**: Incremental commit
- Commit message format: `refactor(scope): description`
- Reference related issue or proposal
- Include tests in commit
- Ensure build passes
**Detailed Guidance**: See [code-refactoring skill](../code-refactoring/SKILL.md#tdd-refactoring-workflow)
### Common Refactoring Patterns
**Structural Patterns**:
- **Extract Method**: Extract code fragment into separate method
- **Extract Class**: Extract responsibilities into new class
- **Inline Method**: Remove method and insert its body
- **Inline Class**: Merge class into another
**Compositional Patterns**:
- **Replace Conditional with Polymorphism**: Use polymorphism instead of switch/if-else
- **Introduce Parameter Object**: Group related parameters
- **Preserve Whole Object**: Pass entire object instead of fields
**Simplification Patterns**:
- **Decompose Conditional**: Break complex conditionals
- **Consolidate Conditional**: Combine duplicate conditionals
- **Replace Magic Number with Constant**: Use named constants
**Pattern Reference**: [code-refactoring skill](../code-refactoring/SKILL.md#refactoring-patterns)
### Metrics Tracking
**Pre-Execution Metrics** (from PREPARATION phase):
- Baseline complexity: [measure using tools]
- Baseline coverage: [measure using test tools]
- Baseline test count: [count tests]
**Mid-Execution Checkpoint** (optional, at 50% progress):
```bash
# Measure current metrics
./scripts/capture-metrics.sh > checkpoint/metrics.json
# Compare to baseline
./scripts/compare-metrics.sh baseline/metrics.json checkpoint/metrics.json
Decision Point:
- If complexity improving, coverage stable → ✅ Continue
- If complexity worsening, coverage dropping → ⚠️ Reassess approach
Metrics Guide: code-refactoring skill
Part 2: Execution Process Management (RLM)
Work Log
Maintain daily work log (5-10 minutes per day):
## Work Log: [Date]
### Files Modified
- `src/services/AudioCapture.ts` (+50, -100 lines)
- `src/services/SessionManager.ts` (NEW, 150 lines)
### Tests Added
- `src/services/AudioCapture.session.test.ts` (NEW, +10 tests)
- `src/services/SessionManager.test.ts` (NEW, +15 tests)
### Issues Encountered
- **Issue**: VAD mock not compatible with new structure
- **Resolution**: Updated factory pattern in TENVADetector.test.ts
- **Time lost**: 30 minutes
### Progress
- Planned: 5 sub-tasks
- Completed: 3 sub-tasks (60%)
- Blocked: 0
- At risk: 1 (running behind)
Completion Report Draft
Maintain completion report draft (update as you go):
# Completion Report: [Task Name]
**Status**: Draft (Last updated: YYYY-MM-DD)
## Objectives vs Results
| Objective | Planned | Actual | Status |
|-----------|---------|--------|--------|
| [Obj 1] | [What was planned] | [What was done] | ✅ | ⚠️ | ❌ |
## Work Completed
[Fill in as you go]
## Issues Encountered
[Document as they happen]
## Metrics
[Update at the end]
Part 3: Documentation Quality (documentation-management)
Code Quality Checks
Pre-Commit Checks (automated):
npm run lint
npm test
npm run build
Manual Checks (daily):
Documentation Sync
Keep Docs in Sync (update as you code):
Quick Sync Workflow:
git add docs/guides/[component].md
git commit -m "docs(component): update for refactoring"
Part 4: Progress Tracking (RLM)
Daily Dashboard Update
At end of each day, update dashboard:
## Recent Activity (Last 7 Days)
### YYYY-MM-DD
**[Task Name]** (XX% complete)
- **Work Completed**: [What did you do today?]
- **Tests**: [+X tests, Y/Y passing]
- **Issues**: [Any issues?]
- **Next**: [What's tomorrow?]
Weekly Status Report
Every Monday, send status report to team:
# Weekly Status: [Task Name]
**Week**: N (of M estimated weeks)
**Date**: YYYY-MM-DD
**Owner**: [Name]
## Progress Summary
- **Completed This Week**: [What did you accomplish?]
- **Planned Next Week**: [What's next?]
- **Overall Progress**: XX% (N/M weeks)
## Metrics
- **Complexity**: [Start] → [Current] (Δ: [change])
- **Coverage**: [Start]% → [Current]% (Δ: [+/-X%])
- **Tests**: [Start] → [Current] (Δ: [+/-X])
## Issues & Blockers
- **Issues**: [Any issues this week?]
- **Blockers**: [Any blockers?]
- **Help Needed**: [Do you need anything from the team?]
## Decision Point
**Continue**: ✅ | ⚠️ | ❌
**Rationale**: [Why continue/pivot/stop?]
**Phase 4: VALIDATION** (Testing and Validation)
- **Deliverables**: Functional tests, performance tests, regression tests, known issues document, rollback plan
- **Template**: `templates/validation-phase-template.md`
- **Quality Gate**: Validation tests passed, no regressions, performance validated, rollback plan tested
**VALIDATION Phase Structure** (Enhanced with code-refactoring integration):
```markdown
# VALIDATION Phase: [Task Name]
## Layer 1: Technical Validation (code-refactoring)
### Metrics Comparison
**Pre-Execution Baseline**: (from PREPARATION phase)
```json
{
"complexity": 12,
"coverage": 65%,
"test_count": 120
}
Post-Execution Actual: (capture now)
./scripts/capture-metrics.sh > validation/metrics-post.json
Comparison:
./scripts/compare-metrics.sh baseline/metrics.json validation/metrics-post.json
Acceptance Criteria:
Metrics Guide: code-refactoring skill
Test Validation
Test Suite Health:
Test Coverage:
npm run test:coverage
npm run test:coverage -- --component GeminiLiveService
npm run test:coverage -- --component AudioCapture
Acceptance Criteria:
Build & Runtime Validation
Build Validation:
Runtime Validation:
Automated Checks:
./scripts/validate-all.sh
Regression Detection
Automated Regression Tests (run weekly):
npm test -- --profiling
python scripts/check-regressions.py baseline/performance.json tests/performance.json
if regression_detected; then
echo "⚠️ REGRESSION ALERT" | slack-notify
fi
Alert Thresholds:
- 🔴 Red Alert: Metric regresses by >10% from baseline
- 🟡 Yellow Alert: Metric regresses by 5-10% from baseline
- 🟢 Green: Metric stable or improving
Regression Guide: code-refactoring skill
Layer 2: Documentation Validation (documentation-management)
Documentation Completeness
Checklist:
Tool-Assisted Check:
grep -r "TODO\|FIXME" docs/ --include="*.md"
./scripts/validate-examples.sh docs/
python .claude/skills/documentation-management/tools/validate-links.py docs/
Acceptance Criteria:
Documentation Quality
Quality Checklist (from documentation-management):
Peer Review:
Layer 3: Process Validation (RLM)
Plan Execution Fidelity
Planned vs Actual:
Deviations:
Stakeholder Feedback
Survey/Interview Results:
Qualitative Feedback:
- Positive: [What went well?]
- Negative: [What didn't go well?]
- Suggestions: [What should we do differently?]
Quality Gate Validation
Check all 6 Quality Gates (see RLM Quality Gates):
Validation Decision
Overall Status: ✅ VALIDATED | ⚠️ CONDITIONAL | ❌ FAILED
Scoring
Layer 1: Technical (Weight: 40%)
- Metrics comparison: [0-1 score]
- Test validation: [0-1 score]
- Build/Runtime: [0-1 score]
- Technical Score: [X]/3 → [percentage]%
Layer 2: Documentation (Weight: 30%)
- Completeness: [0-1 score]
- Quality: [0-1 score]
- Integration: [0-1 score]
- Documentation Score: [X]/3 → [percentage]%
Layer 3: Process (Weight: 30%)
- Fidelity: [0-1 score]
- Feedback: [0-1 score]
- Quality Gates: [0-1 score]
- Process Score: [X]/3 → [percentage]%
Overall Score: [Weighted sum] = [percentage]%
Criteria
VALIDATED (all required):
- Technical score ≥ 80%
- Documentation score ≥ 70%
- Process score ≥ 70%
- All critical acceptance criteria met
CONDITIONAL (minor issues):
- Overall score ≥ 70% but < 80%
- Minor gaps that can be addressed post-integration
- No critical blockers
FAILED (blockers):
- Overall score < 70%
- Critical acceptance criteria not met
- Technical or documentation blockers
**Phase 5: INTEGRATION** (Architecture State Updates)
- **Deliverables**: State doc updates, evolution history added, **bi-directional links established**, migration guide
- **Template**: `templates/integration-phase-template.md`
- **Quality Gate**: State docs updated, **bi-directional links established**, migration guide available
**INTEGRATION Phase Structure** (Enhanced with code-refactoring integration):
```markdown
# INTEGRATION Phase: [Task Name]
## Layer 1: Code Integration (code-refactoring)
### Merge to Main Branch
**Pre-Merge Checklist**:
- [ ] All tests passing (≥95%)
- [ ] Code reviewed and approved
- [ ] Validation report approved
- [ ] Documentation updated
- [ ] No merge conflicts (or resolved)
**Merge Process**:
```bash
# 1. Update main branch
git checkout main
git pull origin main
# 2. Merge feature branch
git merge refactor/[task-name]
# 3. Resolve conflicts (if any)
# [Manual resolution]
# 4. Run full test suite
npm test
# 5. Build
npm run build
# 6. Push
git push origin main
Tag Release
Create Git Tag:
git tag -a v[semantic-version] -m "Refactoring: [Task Name]"
git push origin v[semantic-version]
Tag Format:
- Major refactor:
v2.0.0 (breaking changes)
- Minor refactor:
v1.X.0 (new features)
- Patch refactor:
v1.X.Y (bug fixes, optimizations)
Integration Guide: code-refactoring skill
Post-Merge Validation
Smoke Tests:
Rollback Plan:
Layer 2: Documentation Integration (documentation-organization)
Update State Documentation
Add "Architecture Evolution History" to affected state docs:
## Architecture Evolution History
| Iteration | Date | State Change | Impact |
|-----------|------|-------------|--------|
| **[Task Name]** | YYYY-MM-DD | [What changed?] | [Impact] |
**Key Decision**: [Link to ADR if exists]
**Validation**: [Link to validation report]
---
## Previous Architecture State
- **[Previous State]**: [Description before this refactor]
- **Migration Guide**: [Link to migration guide if breaking]
Affected Docs (from VALIDATION phase):
Update Process Documentation
Update Refactoring Tracking Docs:
Create Completion Report (if not done in VALIDATION):
cp docs/refactoring/reports/completion/_template.md \
docs/refactoring/reports/completion/[task-name].md
Sync Documentation Structure
Ensure Docs Follow Conventions:
Validation:
./scripts/validate-doc-structure.sh docs/
./scripts/validate-crossrefs.sh docs/
Layer 3: Team Integration (knowledge-transfer)
Team Briefing
Schedule team meeting (30 minutes):
- Agenda:
- What was done (5 min)
- How it works (10 min)
- Migration guide (if breaking) (10 min)
- Q&A (5 min)
Slides/Notes:
- Create brief presentation (5-10 slides)
- Focus on: Why, What, How, Impact
Record Meeting:
Knowledge Transfer
For Critical Refactors (breaking changes or complex logic):
For Routine Refactors:
Integration Checklist
Code Integration (All Required)
Documentation Integration (All Required)
Team Integration (All Required)
**Phase 6: MONITORING** (Post-Integration Monitoring)
- **Deliverables**: Monitoring period (7-30 days), metrics collected, issues document, stability assessment, recommendations
- **Template**: `templates/monitoring-phase-template.md`
- **Quality Gate**: Monitoring period complete, metrics stable, issues resolved, stakeholder sign-off
**MONITORING Phase Structure** (Enhanced with code-refactoring integration):
```markdown
# MONITORING Phase: [Task Name]
## Part 1: Process Monitoring (RLM)
### Usage Metrics
**Daily/Weekly Metrics** (collect automatically if possible):
- **Adoption Rate**: % of team using new code/workflow
- **Error Rate**: Errors encountered per [time period]
- **Performance**: [metric] vs baseline
- **Feedback**: Positive/negative feedback ratio
**Data Collection**:
```bash
# Automated metrics collection (if configured)
./scripts/collect-metrics.sh --period weekly > metrics/weekly-[date].json
# Manual feedback collection
# Link to feedback form: https://[survey-tool]
Issue Tracking
Report Issues:
Issue Log Template:
## Issue Log: [Task Name] Monitoring
### Open Issues
| ID | Title | Category | Priority | Status | Opened | Assignee |
|----|-------|----------|----------|--------|--------|----------|
| #1 | [Issue description] | Bug | P1 | 🚧 Open | YYYY-MM-DD | [Name] |
| #2 | [Issue description] | Enhancement | P2 | 📋 Planned | YYYY-MM-DD | [Name] |
### Resolved Issues
| ID | Title | Resolution | Closed | Duration |
|----|-------|------------|--------|----------|
| #3 | [Issue description] | [Fix description] | YYYY-MM-DD | 2 days |
### Issue Metrics
- Total issues: [count]
- Resolved: [count] ([X]%)
- Open: [count] ([Y]%)
- Average resolution time: [X] days
Part 2: Performance Tracking (code-refactoring)
Metrics Trend Analysis
Weekly Metrics Comparison:
./scripts/capture-metrics.sh --period weekly > metrics/weekly-[date].json
python scripts/analyze-trends.py metrics/baseline.json metrics/weekly-*.json
Trend Report:
| Metric | Baseline | Week 1 | Week 2 | Week 3 | Week 4 | Trend |
|---|
| Complexity | 12 | 10 | 9 | 9 | 9 | ✅ Improving |
| Coverage | 65% | 70% | 75% | 78% | 80% | ✅ Improving |
| Build Time | 30s | 28s | 26s | 25s | 25s | ✅ Improving |
| Test Runtime | 45s | 42s | 40s | 40s | 40s | ✅ Stable |
| Error Rate | 2% | 1.5% | 1% | 0.8% | 0.5% | ✅ Improving |
Alert Thresholds:
- 🔴 Red Alert: Metric regresses by >10% from baseline
- 🟡 Yellow Alert: Metric regresses by 5-10% from baseline
- 🟢 Green: Metric stable or improving
Performance Guide: code-refactoring skill
Regression Detection
Automated Regression Tests (run weekly):
npm test -- --profiling
python scripts/check-regressions.py baseline/performance.json tests/performance.json
if regression_detected; then
echo "⚠️ REGRESSION ALERT" | slack-notify
fi
Decision:
- If regression detected → Return to EXECUTION phase (fix regression)
- If stable for 4 weeks → Extend monitoring period or close monitoring
Part 3: Documentation Health (documentation-organization)
Link Validation
Weekly Link Check:
python .claude/skills/documentation-management/tools/validate-links.py docs/
python scripts/find-orphans.sh docs/
Link Health Report:
- Total links: [count]
- Broken links: [count] ([X]%)
- Orphaned pages: [count] ([Y]%)
- Fixed this week: [count]
Content Freshness
Outdated Content Detection:
grep -r "TODO\|FIXME" docs/ --include="*.md" | wc -l
grep -r "version X.Y" docs/ --include="*.md" | grep -v "version [current]"
Freshness Metrics:
- TODO/FIXME count: [count] (target: 0)
- Outdated version refs: [count] (target: 0)
- Last updated: [date] (target: within last 3 months)
Part 4: Feedback Loop (RLM)
Continuous Improvement
Weekly Feedback Survey (send to team):
## Weekly Feedback: [Task Name]
**Week**: [N]
**Performance**:
1. How is the new code/workflow working? [1-5]
2. Have you encountered any issues? [Yes/No]
- If yes, please describe: [...]
**Documentation**:
3. Is the documentation clear and helpful? [1-5]
4. What's missing or confusing? [Open feedback]
**Suggestions**:
5. What should we improve?
**Overall**:
6. Would you recommend this refactor to others? [Yes/No]
7. Any other feedback? [Open feedback]
Feedback Analysis:
- Collect feedback (weekly or bi-weekly)
- Categorize: Praise | Problem | Suggestion
- Identify trends: Same issue mentioned 3+ times?
- Prioritize improvements
Iteration Planning
From Monitoring to PROPOSAL (Feedback Loop):
Issue Identified (from monitoring data):
- Problem: [What's the problem?]
- Frequency: [How often does it occur?]
- Impact: [What's the impact?]
Decision: Create new proposal?
- ✅ Yes: Create new PROPOSAL for improvement iteration
- ❌ No: Document issue, add to known issues list
### Bi-Directional Traceability
**Forward Traceability** (Process → State):
- **Question**: "Which state docs did this refactoring update?"
- **Implementation**: Completion report has "Impact on Architecture State" section
- **Example**:
```markdown
## Impact on Architecture State
**State Docs Updated**:
- `guides/state-inspection.md` (added 5-layer inspector documentation)
- `CLAUDE.md` (added Stage-Pipeline architecture section)
**Code Artifacts**:
- `src/pipeline/stages/StateInspectorStage.ts` (new)
- `src/pipeline/stages/__tests__/StateInspectorStage.test.ts` (113 tests)
Backward Traceability (State → Process):
- Question: "Which refactoring added this feature?"
- Implementation: State doc has "Architecture Evolution History" section
- Example:
## Architecture Evolution History
**Current State**: ✅ Implemented (Iterations 5.1-5.7, 2025-01-XX)
| Iteration | Date | State Change | Impact |
|-----------|------|-------------|--------|
| **5.4** | 2025-01-XX | State inspection system | 5-layer inspector |
| **5.6** | 2025-01-XX | Web integration | Dual-mode architecture |
**Key Decision**: [ADR-001: Stage-Pipeline Architecture](../refactoring/adr/001-stage-pipeline.md)
Plan-Execution Alignment
Problem: Plans are speculative, execution often deviates (60% deviation baseline)
RLM Solution:
- Document Deviations: When plan changes, document why
- Track Emergent Work: Separate planned vs emergent work
- Update Plans Regularly: Keep plans current with reality
- Accept Uncertainty: Plan deviation is normal, not failure
Example: Traceability Matrix Plan → Execution table
| Planned Iteration | Actual Execution | Status | Deviation Reason |
|-------------------|------------------|--------|------------------|
| Iteration 5.1-5.7 | Stage-Pipeline | ⚠️ Emergent | Not in original plan (technical discovery) |
Management Tools
Refactoring Dashboard
Location: docs/refactoring/DASHBOARD.md
Template: templates/dashboard-template.md
Purpose: Single entry point for refactoring progress
Key Sections (9 total):
- Quick Stats: Overall progress, hours spent, test pass rate
- Phase Status: Completed, In Progress, Planned
- Recent Activity: Last 7 days activity log
- Upcoming Work: Next 7 days planned work
- Test Coverage: Visual chart of test growth
- Architecture Evolution Timeline: Phase timeline
- Blocked Items: Active blockers
- Risks & Issues: Active risks
- Quick Links: All key docs
Update Frequency: After each phase completion
Time to Update: 10-15 minutes (extract from source docs)
Impact: Stakeholders understand progress in <5 minutes
Traceability Matrix
Location: docs/refactoring/TRACEABILITY.md
Template: templates/traceability-matrix-template.md
Purpose: Bi-directional mapping between plans, executions, and state
Key Tables (4 total):
- Plan → Execution: Which plans were executed?
- Execution → State: What state changes resulted?
- State → Documentation: Which docs describe the state?
- Decision → Architecture: Which ADRs affected architecture?
Update Frequency: After each phase completion
Time to Update: 20-30 minutes (add rows to tables)
Impact: 20-second lookups (vs 3-4 minutes without matrix)
Quality Gates
Location: templates/quality-gates-template.md
Purpose: Checkpoints ensuring completeness before phase transitions
6 Quality Gates:
- PROPOSAL → PLANNING: Problem clarity, solution completeness, impact quantified
- PLANNING → EXECUTION: Objectives SMART, scope bounded, tasks decomposed
- EXECUTION → VALIDATION: Code quality, test coverage, bi-directional traceability
- VALIDATION → INTEGRATION: Tests passed, no regressions, rollback plan tested
- INTEGRATION → MONITORING: State docs updated, bi-directional links established
- MONITORING → COMPLETE: Metrics stable, issues resolved, stakeholder sign-off
Target: ≥90% gate pass rate (≤10% bypasses)
Approval Process: Required approvers (tech lead, QA lead, engineering manager)
Bypass Procedure: Emergency bypass with approval and completion date
Measurement and Metrics
V_instance: Domain-Specific Quality
Definition: How well RLM manages refactoring for your project
Formula:
V_instance = 0.25×Alignment + 0.25×Traceability + 0.25×Discovery + 0.25×Visibility
Components:
-
Alignment (0.25): Plan-execution fit
- Target: ≥0.85 (85% alignment)
- Baseline: ~0.40
-
Traceability (0.25): Bi-directional linking
- Target: ≥0.90 (90% coverage)
- Baseline: ~0.21
-
Discovery (0.25): Time to find information
- Target: ≤30 seconds per query
- Baseline: ~3-5 minutes
-
Visibility (0.25): Stakeholder comprehension
- Target: ≤5 minutes for full picture
- Baseline: ~20-30 minutes
Overall Target: V_instance ≥ 0.80
V_meta: Methodology Quality
Definition: How well RLM works as a reusable framework
Formula:
V_meta = 0.25×Completeness + 0.25×Effectiveness + 0.25×Reusability + 0.25×Validation
Components:
-
Completeness (0.25): Full methodology documentation
- Target: ≥0.85 (all components present)
-
Effectiveness (0.25): Measurable improvement
- Target: ≥0.80 (80% of potential realized)
-
Reusability (0.25): Transfer to other projects
- Target: ≥0.85 (85% generalizable)
-
Validation (0.25): Empirical evidence
- Target: ≥0.80 (strong metrics and data)
Overall Target: V_meta ≥ 0.80
Convergence Criteria
Primary Convergence:
- V_instance ≥ 0.80 AND V_meta ≥ 0.80
Secondary Convergence (Stability):
- System stable: ΔV < 0.02 for 2 iterations
- Objectives complete: All methodology components implemented
Expected Timeline:
- Best case: 3 iterations (baseline + 2 improvements)
- Typical case: 4 iterations
- Worst case: 5+ iterations
Examples
See examples/ directory for real examples from gemini-live-scribe project:
examples/gemini-live-scribe-dashboard.md - Complete dashboard (650 lines)examples/gemini-live-scribe-traceability.md - Complete traceability matrix (950 lines)examples/completion-report-with-state-impact.md - EXECUTION phase exampleexamples/state-doc-with-evolution-history.md - State doc example
Key Results (gemini-live-scribe)
Baseline (Iteration 0):
- V_instance = 0.25 (weak alignment, poor traceability, slow discovery, no visibility)
- V_meta = 0.00 (no methodology)
Iteration 1: Core Methodology (8 hours)
- Created 6 lifecycle phase templates (~13,500 lines)
- Created refactoring dashboard (650 lines)
- Created traceability matrix (950 lines)
- Results: V_instance = 0.50 (+0.25, +100%), V_meta = 0.35
Iteration 2: Quality Gates (10 hours)
- Defined all 6 quality gates (500 lines)
- Created RLM methodology guide (500+ lines)
- Results: V_instance = 0.48 (conservative), V_meta = 0.60 (+0.25)
Iteration 3: Validation (8 hours) ✅ CONVERGED
- Validated discovery queries (10.9x faster: 180s → 16.5s)
- Documented plan deviations (alignment +0.20)
- Results: V_instance = 0.82 (+0.34), V_meta = 0.85 (+0.25) ✅
Total Duration: 36 hours (3 iterations)
Convergence: Best case (3 iterations)
Validation
Quality Checklist
Use this checklist to validate RLM adoption:
Phase Templates:
Dashboard:
Traceability Matrix:
Quality Gates:
Bi-Directional Traceability:
Skill Integration:
Metrics:
Success Criteria
Minimum Viable Adoption (V_instance ≥ 0.60):
- Dashboard created and populated
- Traceability matrix created (≥60% coverage)
- 3-5 completion reports with state impact sections
- 2-3 state docs with evolution history
Full Adoption (V_instance ≥ 0.80, V_meta ≥ 0.80):
- All 6 templates in use
- Dashboard and matrix comprehensive
- Quality gates defined and enforced
- Bi-directional traceability ≥85%
- Discovery efficiency ≤30 seconds per query
- Skill integration established
Reference Materials
See reference/ directory for detailed documentation:
reference/RLM_METHODOLOGY.md - Complete methodology guide (1000+ lines)reference/QUALITY_GATES.md - Quality gate definitions (500 lines)reference/ITERATION_3_CONVERGENCE.md - Convergence validation report
Related Skills
-
code-refactoring: Technical methods for code refactoring (TDD, patterns, metrics)
- Integration: Used in EXECUTION, VALIDATION, INTEGRATION, MONITORING phases
- Location: code-refactoring SKILL.md
- Quick Start: See "Quick Start with RLM" section in code-refactoring skill
-
methodology-bootstrapping: Parent framework for BAIME experiments
-
documentation-management: Complementary documentation quality methodology
-
documentation-organization: Complementary documentation organization methodology
Skill Status: ✅ Enhanced with Skill Integration
Version: 1.1 (Integration Updates)
V_instance: 0.82 (103% of 0.80 target)
V_meta: 0.85 (106% of 0.80 target)
Integration: Bidirectional references to code-refactoring, doc-mgmt, doc-org
Validation: 3 iterations of empirical evidence + skill integration testing
Transferability: 90% generalizable (10% project-specific examples)
Last Updated: 2026-01-22 (Iteration 1: RLM Skill Integration Updates)
