Initial commit
This commit is contained in:
Zhongwei Li
983
commands/retro-apply.md
Normal file
983
commands/retro-apply.md
Normal file
@@ -0,0 +1,983 @@
|
||||
# Retro-Apply Command
|
||||
|
||||
**Description**: Apply the process improvement recommendations from IMPROVEMENTS.md to agent protocols and project configuration
|
||||
|
||||
---
|
||||
|
||||
# Retrospective Application Protocol
|
||||
|
||||
**Version**: 1.0
|
||||
**Purpose**: Apply approved process improvements from IMPROVEMENTS.md to agent protocols
|
||||
**Team**: All specialist agents (Migration Coordinator, Security, Architect, Coder, Tester, Documentation)
|
||||
**Input**: `IMPROVEMENTS.md` (from `/retro` command)
|
||||
**Output**: Updated protocol files, configuration, automation scripts
|
||||
**Duration**: 3-8 hours (depends on recommendation complexity)
|
||||
|
||||
**Note**: Time estimates are based on typical human execution times and may vary significantly based on project complexity, team experience, and AI assistance capabilities.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This protocol **systematically implements** the process improvements documented in `IMPROVEMENTS.md`, including:
|
||||
- **Agent behavioral changes**: Update command files to guide better agent behavior (tool usage, confirmation patterns, context gathering)
|
||||
- **Protocol updates**: Modify process steps, quality gates, workflow sequences
|
||||
- **Automation**: Add scripts, hooks, CI/CD to enforce improvements
|
||||
- **Documentation**: Update guidelines, examples, anti-patterns
|
||||
|
||||
**Core Principle**: **Make improvements permanent by embedding them in protocols, commands, and automation.**
|
||||
|
||||
**Change Types**:
|
||||
- **Agent Behavior**: Update commands/*.md to teach agents better practices
|
||||
- **Protocol**: Modify process flows in protocol documents
|
||||
- **Automation**: Add enforcement through scripts/hooks
|
||||
- **Tool Usage**: Add examples and guidance for proper tool selection
|
||||
- **Confirmation Patterns**: Add user approval checkpoints
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Input
|
||||
|
||||
**IMPROVEMENTS.md must exist** with:
|
||||
- ✅ 3-5 specific recommendations
|
||||
- ✅ Each recommendation has clear implementation steps
|
||||
- ✅ ADR format with problem, evidence, proposed change
|
||||
- ✅ Status: Proposed or Approved
|
||||
|
||||
**Validation**:
|
||||
```bash
|
||||
# Check for IMPROVEMENTS.md
|
||||
if [ ! -f "IMPROVEMENTS.md" ]; then
|
||||
echo "❌ IMPROVEMENTS.md not found"
|
||||
echo "Run /retro first to generate recommendations"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate format
|
||||
grep -q "## Recommendations" IMPROVEMENTS.md || echo "⚠️ Missing Recommendations section"
|
||||
grep -q "## Summary" IMPROVEMENTS.md || echo "⚠️ Missing Summary section"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Application Process
|
||||
|
||||
### Phase 1: Review and Approval (15-30 minutes)
|
||||
|
||||
**Objective**: Ensure recommendations are approved before implementation
|
||||
|
||||
#### 1.1 Display Recommendations
|
||||
|
||||
**Migration Coordinator**:
|
||||
```bash
|
||||
# Extract and display all recommendations
|
||||
cat IMPROVEMENTS.md | awk '/^### Recommendation/,/^---/ {print}'
|
||||
```
|
||||
|
||||
**Present to User**:
|
||||
```markdown
|
||||
## Recommendations to Apply
|
||||
|
||||
### Summary
|
||||
| # | Recommendation | Impact | Effort | Priority |
|
||||
|---|----------------|--------|--------|----------|
|
||||
| 1 | [Title] | High | Medium | P0 |
|
||||
| 2 | [Title] | High | Low | P0 |
|
||||
| 3 | [Title] | Medium | Low | P1 |
|
||||
|
||||
Do you want to apply:
|
||||
- All recommendations?
|
||||
- Only P0 (high priority)?
|
||||
- Select specific recommendations?
|
||||
```
|
||||
|
||||
#### 1.2 User Confirmation
|
||||
|
||||
**Wait for explicit approval** before proceeding:
|
||||
- `all` - Apply all recommendations
|
||||
- `p0` - Apply only P0 priority
|
||||
- `1,3,5` - Apply specific recommendations by number
|
||||
- `cancel` - Abort application
|
||||
|
||||
**Update Status in IMPROVEMENTS.md**:
|
||||
```markdown
|
||||
**Status**: Approved for Implementation
|
||||
**Approval Date**: [YYYY-MM-DD]
|
||||
**Approved By**: [User]
|
||||
**Implementation Started**: [YYYY-MM-DD]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Implementation Planning (30 minutes)
|
||||
|
||||
**Objective**: Create detailed implementation plan for each recommendation
|
||||
|
||||
**Migration Coordinator** analyzes each recommendation and creates execution plan:
|
||||
|
||||
#### 2.1 Categorize Changes
|
||||
|
||||
**Change Types**:
|
||||
- **Agent Behavior**: Update command files to change how agents behave (tool selection, confirmation patterns, read-before-write rules)
|
||||
- **Protocol Updates**: Modify process steps, phases, quality gates in protocol documents
|
||||
- **Automation**: Add scripts, pre-commit hooks, CI/CD workflows
|
||||
- **Configuration**: Update project config files
|
||||
- **Documentation**: Update README, guides, templates, examples
|
||||
- **Tool Integration**: Install/configure new tools
|
||||
|
||||
**Examples**:
|
||||
- Agent Behavior: "Add 'MUST read file before Write/Edit' rule to commands/modernize.md"
|
||||
- Protocol: "Add dependency analysis as Phase 0.5 in assessment workflow"
|
||||
- Automation: "Add pre-commit hook for security scanning"
|
||||
|
||||
#### 2.2 Dependency Analysis
|
||||
|
||||
**Identify dependencies** between recommendations:
|
||||
```
|
||||
Recommendation 3 depends on Recommendation 1
|
||||
→ Must apply Recommendation 1 first
|
||||
|
||||
Recommendation 2 and 4 are independent
|
||||
→ Can apply in parallel
|
||||
```
|
||||
|
||||
#### 2.3 Risk Assessment
|
||||
|
||||
**For each recommendation**:
|
||||
- Risk Level: Low/Medium/High
|
||||
- Rollback Plan: How to undo if issues occur
|
||||
- Validation: How to verify success
|
||||
|
||||
#### 2.4 Execution Order
|
||||
|
||||
**Create ordered plan**:
|
||||
```markdown
|
||||
## Implementation Plan
|
||||
|
||||
### Phase A: Foundation (P0, no dependencies)
|
||||
1. Recommendation 2: [Title] - 1 hour
|
||||
2. Recommendation 1: [Title] - 2 hours
|
||||
|
||||
### Phase B: Dependent Changes (P0, requires Phase A)
|
||||
3. Recommendation 3: [Title] - 1.5 hours
|
||||
|
||||
### Phase C: Enhancements (P1)
|
||||
4. Recommendation 4: [Title] - 2 hours
|
||||
5. Recommendation 5: [Title] - 1 hour
|
||||
|
||||
**Total Estimated Time**: 7.5 hours
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Apply Protocol Updates (1-4 hours)
|
||||
|
||||
**Objective**: Update agent protocol documents with process improvements
|
||||
|
||||
**For each recommendation requiring protocol updates**:
|
||||
|
||||
#### 3.1 Identify Affected Protocols
|
||||
|
||||
**Common protocol locations**:
|
||||
- `commands/modernize.md` - Main modernization protocol
|
||||
- `commands/assess.md` - Assessment protocol
|
||||
- `commands/plan.md` - Planning protocol
|
||||
- Project-specific protocols
|
||||
|
||||
**Example**: Recommendation "Front-load dependency analysis"
|
||||
- Affects: `commands/assess.md` (add dependency analysis step)
|
||||
- Affects: `commands/plan.md` (add dependency migration matrix)
|
||||
- Affects: `commands/modernize.md` (Phase 0 prerequisites)
|
||||
|
||||
#### 3.2 Update Protocol Content
|
||||
|
||||
**Process**:
|
||||
1. **Read current protocol**
|
||||
2. **Identify insertion point** (which section/phase)
|
||||
3. **Draft update** following protocol format
|
||||
4. **Insert update** maintaining structure
|
||||
5. **Validate** syntax and formatting
|
||||
6. **Document change** in commit message
|
||||
|
||||
**Example Protocol Update**:
|
||||
|
||||
```markdown
|
||||
# In commands/modernize.md
|
||||
|
||||
## Phase 0: Discovery & Assessment
|
||||
|
||||
**NEW - Added from IMPROVEMENTS.md Recommendation 1**:
|
||||
|
||||
### 0.5 Dependency Migration Matrix (MANDATORY)
|
||||
|
||||
**Duration**: 4-6 hours
|
||||
**Agent**: Architect Agent (lead) + Security Agent
|
||||
**BLOCKING**: Must complete before Phase 1
|
||||
|
||||
**Activities**:
|
||||
1. **Enumerate All Dependencies**
|
||||
- List every package/library with current version
|
||||
- Identify target versions compatible with target framework
|
||||
- Document dependencies of dependencies (transitive)
|
||||
|
||||
2. **Compatibility Analysis**
|
||||
- Check version compatibility matrix
|
||||
- Identify known conflicts
|
||||
- Research breaking changes for each upgrade
|
||||
- **Deliverable**: Dependency compatibility matrix
|
||||
|
||||
3. **Conflict Resolution Strategy**
|
||||
- For each conflict, document resolution approach
|
||||
- Identify packages needing replacement
|
||||
- Define upgrade order (bottom-up from leaf dependencies)
|
||||
- **Deliverable**: Dependency upgrade sequence
|
||||
|
||||
**Exit Criteria**:
|
||||
- ✅ All dependencies mapped to target versions
|
||||
- ✅ All conflicts identified with resolution strategy
|
||||
- ✅ Upgrade order defined
|
||||
- ✅ No unknowns remaining
|
||||
|
||||
**Why This Change**:
|
||||
[Link to IMPROVEMENTS.md Recommendation 1]
|
||||
Prevents mid-migration dependency conflicts that historically caused 1-2 week delays.
|
||||
```
|
||||
|
||||
**Example Agent Behavioral Update**:
|
||||
|
||||
```markdown
|
||||
# In commands/modernize.md
|
||||
|
||||
## Agent Best Practices
|
||||
|
||||
**NEW - Added from IMPROVEMENTS.md Recommendation 4**:
|
||||
|
||||
### MANDATORY: Read Before Write/Edit
|
||||
|
||||
**Rule**: ALL agents MUST read a file before using Write or Edit tools.
|
||||
|
||||
**Rationale**: Prevents overwriting existing content, conflicts, and user interruptions.
|
||||
Historical evidence: 8 instances of conflicts caused by writing without reading first.
|
||||
|
||||
**Protocol**:
|
||||
1. **Before Write**: ALWAYS use Read tool first
|
||||
```
|
||||
❌ WRONG: Use Write without reading
|
||||
✅ CORRECT: Read → analyze content → Write
|
||||
```
|
||||
|
||||
2. **Before Edit**: File must be read in current conversation
|
||||
```
|
||||
❌ WRONG: Edit tool on file never read
|
||||
✅ CORRECT: Read → identify exact string → Edit
|
||||
```
|
||||
|
||||
3. **Exceptions**: NONE. This rule has no exceptions.
|
||||
|
||||
**Enforcement**:
|
||||
- Migration Coordinator validates all file operations
|
||||
- User should interrupt if agent violates this rule
|
||||
- Retrospective will flag violations
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
User: Update the config file
|
||||
Agent: [Reads config.json first]
|
||||
Agent: I see the current configuration has X, Y, Z settings.
|
||||
Agent: I'll update setting Y to the new value.
|
||||
Agent: [Uses Edit tool with exact old_string from what was read]
|
||||
```
|
||||
|
||||
**Why This Change**:
|
||||
[Link to IMPROVEMENTS.md Recommendation 4]
|
||||
Eliminates 100% of file conflicts and user interruptions caused by not reading files first.
|
||||
```
|
||||
|
||||
**Example Tool Usage Behavioral Update**:
|
||||
|
||||
```markdown
|
||||
# In commands/modernize.md
|
||||
|
||||
## Tool Selection Guide
|
||||
|
||||
**NEW - Added from IMPROVEMENTS.md Recommendation 5**:
|
||||
|
||||
### Use Specialized Tools, Not Bash Commands
|
||||
|
||||
**Rule**: Use specialized tools for file operations, NOT bash commands.
|
||||
|
||||
**Decision Tree**:
|
||||
|
||||
**Need to read file?**
|
||||
- ✅ Use: `Read` tool
|
||||
- ❌ Don't use: `cat`, `head`, `tail`, `less`
|
||||
- **Why**: Read provides line numbers, handles large files, integrates with Edit
|
||||
|
||||
**Need to find files?**
|
||||
- ✅ Use: `Glob` tool with pattern
|
||||
- ❌ Don't use: `find`, `ls`
|
||||
- **Why**: Glob is faster, respects .gitignore, returns sorted results
|
||||
|
||||
**Need to search file contents?**
|
||||
- ✅ Use: `Grep` tool
|
||||
- ❌ Don't use: `grep`, `rg`, `ag`
|
||||
- **Why**: Grep has better permissions, output modes, context options
|
||||
|
||||
**Need to create/modify files?**
|
||||
- ✅ Use: `Write`, `Edit` tools
|
||||
- ❌ Don't use: `echo >`, `cat <<EOF`, `sed`, `awk`
|
||||
- **Why**: Write/Edit are tracked, validated, support rollback
|
||||
|
||||
**Only use Bash for**:
|
||||
- Git operations
|
||||
- Build commands (npm, dotnet, make)
|
||||
- Test execution
|
||||
- System commands that aren't file operations
|
||||
|
||||
**Historical Evidence**:
|
||||
- 23 instances of `cat` instead of Read
|
||||
- 15 instances of `find` instead of Glob
|
||||
- 12 instances of `grep` instead of Grep
|
||||
- All required user corrections
|
||||
|
||||
**Why This Change**:
|
||||
[Link to IMPROVEMENTS.md Recommendation 5]
|
||||
Reduces wrong tool usage by 95%, improves context handling, eliminates user corrections.
|
||||
```
|
||||
|
||||
#### 3.3 Validate Updates
|
||||
|
||||
**Checks**:
|
||||
- [ ] Markdown syntax valid
|
||||
- [ ] Section numbering consistent
|
||||
- [ ] Links work
|
||||
- [ ] Formatting matches protocol style
|
||||
- [ ] No broken references
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Add Automation (1-3 hours)
|
||||
|
||||
**Objective**: Implement automation to enforce improvements
|
||||
|
||||
**Common Automation Types**:
|
||||
|
||||
#### 4.1 Pre-commit Hooks
|
||||
|
||||
**Example**: Automated security scanning
|
||||
|
||||
**Create**: `.git/hooks/pre-commit` or use husky/lefthook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Pre-commit hook: Security vulnerability scanning
|
||||
# Added from IMPROVEMENTS.md Recommendation 3
|
||||
|
||||
echo "🔍 Scanning for security vulnerabilities..."
|
||||
|
||||
# Detect project type and run appropriate scanner
|
||||
if [ -f "package.json" ]; then
|
||||
npm audit --audit-level=high
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Security vulnerabilities detected (HIGH or above)"
|
||||
echo "Run 'npm audit fix' or document exceptions"
|
||||
exit 1
|
||||
fi
|
||||
elif [ -f "requirements.txt" ]; then
|
||||
pip-audit
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Security vulnerabilities detected"
|
||||
exit 1
|
||||
fi
|
||||
elif [ -f "*.csproj" ]; then
|
||||
dotnet list package --vulnerable --include-transitive
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Security vulnerabilities detected"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "✅ No high/critical vulnerabilities detected"
|
||||
exit 0
|
||||
```
|
||||
|
||||
**Make executable**:
|
||||
```bash
|
||||
chmod +x .git/hooks/pre-commit
|
||||
```
|
||||
|
||||
#### 4.2 Scripts for Common Tasks
|
||||
|
||||
**Example**: Dependency analysis script
|
||||
|
||||
**Create**: `scripts/analyze-dependencies.sh`
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Dependency Analysis Script
|
||||
# Added from IMPROVEMENTS.md Recommendation 1
|
||||
|
||||
echo "📦 Dependency Analysis for Modernization"
|
||||
echo "========================================"
|
||||
|
||||
# Detect project type
|
||||
if [ -f "package.json" ]; then
|
||||
echo "Project Type: Node.js"
|
||||
echo ""
|
||||
echo "Outdated Packages:"
|
||||
npm outdated --long
|
||||
echo ""
|
||||
echo "Dependency Tree:"
|
||||
npm list --depth=1
|
||||
elif [ -f "requirements.txt" ]; then
|
||||
echo "Project Type: Python"
|
||||
echo ""
|
||||
echo "Outdated Packages:"
|
||||
pip list --outdated
|
||||
elif [ -f "*.sln" ]; then
|
||||
echo "Project Type: .NET"
|
||||
echo ""
|
||||
echo "Outdated Packages:"
|
||||
dotnet list package --outdated --include-transitive
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✅ Save this output to inform dependency migration matrix"
|
||||
```
|
||||
|
||||
**Make executable**:
|
||||
```bash
|
||||
chmod +x scripts/analyze-dependencies.sh
|
||||
```
|
||||
|
||||
#### 4.3 CI/CD Integration
|
||||
|
||||
**Example**: Add security scanning to GitHub Actions
|
||||
|
||||
**Create/Update**: `.github/workflows/security-scan.yml`
|
||||
|
||||
```yaml
|
||||
name: Security Vulnerability Scan
|
||||
# Added from IMPROVEMENTS.md Recommendation 3
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main, develop ]
|
||||
schedule:
|
||||
# Run weekly on Monday at 9am UTC
|
||||
- cron: '0 9 * * 1'
|
||||
|
||||
jobs:
|
||||
security-scan:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Run security scan
|
||||
run: |
|
||||
# Auto-detect project type and scan
|
||||
if [ -f "package.json" ]; then
|
||||
npm audit --audit-level=moderate
|
||||
elif [ -f "requirements.txt" ]; then
|
||||
pip install pip-audit
|
||||
pip-audit
|
||||
elif [ -f "*.csproj" ]; then
|
||||
dotnet list package --vulnerable --include-transitive
|
||||
fi
|
||||
|
||||
- name: Upload results
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: security-scan-results
|
||||
path: security-scan.log
|
||||
```
|
||||
|
||||
#### 4.4 Quality Gate Automation
|
||||
|
||||
**Example**: Test coverage enforcement
|
||||
|
||||
**Create**: `scripts/enforce-coverage.sh`
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test Coverage Quality Gate
|
||||
# Added from IMPROVEMENTS.md Recommendation 4
|
||||
|
||||
REQUIRED_COVERAGE=85
|
||||
|
||||
echo "📊 Checking test coverage..."
|
||||
|
||||
# Run tests with coverage
|
||||
# (adapt to project type)
|
||||
COVERAGE=$(npm test -- --coverage | grep "All files" | awk '{print $10}' | sed 's/%//')
|
||||
|
||||
if (( $(echo "$COVERAGE < $REQUIRED_COVERAGE" | bc -l) )); then
|
||||
echo "❌ Coverage $COVERAGE% is below required $REQUIRED_COVERAGE%"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ Coverage $COVERAGE% meets requirement"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Update Documentation (30-60 minutes)
|
||||
|
||||
**Objective**: Document the changes for team awareness
|
||||
|
||||
#### 5.1 Update README
|
||||
|
||||
**Add section**:
|
||||
|
||||
```markdown
|
||||
## Process Improvements
|
||||
|
||||
This project has implemented continuous process improvements based on retrospective analysis.
|
||||
|
||||
### Recent Improvements
|
||||
- **[Date]**: Applied 5 recommendations from retrospective
|
||||
- Front-loaded dependency analysis to Phase 0
|
||||
- Continuous documentation throughout phases
|
||||
- Automated security scanning in CI/CD
|
||||
- Parallel testing workflow
|
||||
- Quality gate automation
|
||||
|
||||
See [IMPROVEMENTS.md](IMPROVEMENTS.md) for details.
|
||||
|
||||
### Automation
|
||||
- Pre-commit hooks: Security scanning
|
||||
- CI/CD: Weekly vulnerability scans
|
||||
- Scripts: `scripts/analyze-dependencies.sh`, `scripts/enforce-coverage.sh`
|
||||
```
|
||||
|
||||
#### 5.2 Update Protocol Index
|
||||
|
||||
**Create/Update**: `PROTOCOLS.md`
|
||||
|
||||
```markdown
|
||||
# Agent Protocols
|
||||
|
||||
## Commands
|
||||
- `/modernize` - Main modernization orchestration
|
||||
- `/assess` - Project assessment
|
||||
- `/plan` - Create detailed plan
|
||||
- `/retro` - Retrospective analysis
|
||||
- `/retro-apply` - Apply improvements
|
||||
|
||||
## Improvements History
|
||||
- **2025-11-01**: Applied 5 recommendations from IMPROVEMENTS.md
|
||||
- See detailed changes in git commit [hash]
|
||||
```
|
||||
|
||||
#### 5.3 Create CHANGELOG Entry
|
||||
|
||||
```markdown
|
||||
## [Unreleased]
|
||||
|
||||
### Changed - Process Improvements
|
||||
- **Phase 0**: Added mandatory dependency migration matrix (IMPROVEMENTS.md Rec 1)
|
||||
- **All Phases**: Continuous documentation instead of batched (IMPROVEMENTS.md Rec 2)
|
||||
- **Security**: Automated vulnerability scanning in CI/CD (IMPROVEMENTS.md Rec 3)
|
||||
- **Testing**: Parallel test execution workflow (IMPROVEMENTS.md Rec 4)
|
||||
- **Quality Gates**: Automated enforcement scripts (IMPROVEMENTS.md Rec 5)
|
||||
|
||||
### Added
|
||||
- Pre-commit hook for security scanning
|
||||
- Scripts: `analyze-dependencies.sh`, `enforce-coverage.sh`
|
||||
- CI/CD: Weekly security scan workflow
|
||||
- Protocol updates in commands/modernize.md, assess.md, plan.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Validation (30 minutes)
|
||||
|
||||
**Objective**: Verify all changes were applied correctly
|
||||
|
||||
#### 6.1 Protocol Validation
|
||||
|
||||
**For each updated protocol**:
|
||||
```bash
|
||||
# Check markdown syntax
|
||||
markdownlint commands/modernize.md
|
||||
|
||||
# Verify all sections present
|
||||
grep -q "## Phase 0: Discovery & Assessment" commands/modernize.md && echo "✅ Section exists"
|
||||
|
||||
# Check for broken links
|
||||
# (use link checker tool)
|
||||
```
|
||||
|
||||
#### 6.2 Automation Validation
|
||||
|
||||
**Test each automation**:
|
||||
|
||||
```bash
|
||||
# Test pre-commit hook
|
||||
.git/hooks/pre-commit
|
||||
echo "Exit code: $?"
|
||||
|
||||
# Test dependency analysis script
|
||||
./scripts/analyze-dependencies.sh
|
||||
|
||||
# Test coverage enforcement
|
||||
./scripts/enforce-coverage.sh
|
||||
```
|
||||
|
||||
#### 6.3 Documentation Validation
|
||||
|
||||
**Verify documentation**:
|
||||
- [ ] README updated with improvements summary
|
||||
- [ ] CHANGELOG.md has entry
|
||||
- [ ] PROTOCOLS.md reflects changes
|
||||
- [ ] Links work
|
||||
- [ ] Examples accurate
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Commit and Track (15 minutes)
|
||||
|
||||
**Objective**: Commit changes with proper documentation
|
||||
|
||||
#### 7.1 Git Commit
|
||||
|
||||
**Commit Structure**:
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
|
||||
git commit -m "$(cat <<'EOF'
|
||||
Apply process improvements from IMPROVEMENTS.md
|
||||
|
||||
Implemented 5 recommendations from retrospective analysis:
|
||||
|
||||
1. Front-load dependency analysis (Rec 1)
|
||||
- Updated commands/modernize.md Phase 0
|
||||
- Added scripts/analyze-dependencies.sh
|
||||
- Estimated savings: 1-2 weeks per project
|
||||
|
||||
2. Continuous documentation (Rec 2)
|
||||
- Updated all commands/*.md protocols
|
||||
- Added incremental documentation checkpoints
|
||||
- Estimated savings: 50% of Phase 6 time
|
||||
|
||||
3. Automated security scanning (Rec 3)
|
||||
- Added pre-commit hook for vulnerability scanning
|
||||
- Added .github/workflows/security-scan.yml
|
||||
- Prevents vulnerable dependencies
|
||||
|
||||
4. Parallel testing workflow (Rec 4)
|
||||
- Updated commands/modernize.md Phase 3-4
|
||||
- Added parallel test execution strategy
|
||||
- Estimated savings: 30% testing time
|
||||
|
||||
5. Quality gate automation (Rec 5)
|
||||
- Added scripts/enforce-coverage.sh
|
||||
- Updated quality gate criteria
|
||||
- Eliminates manual gate checking
|
||||
|
||||
Changes applied from: IMPROVEMENTS.md
|
||||
Generated by: /retro command
|
||||
Applied by: /retro-apply command
|
||||
|
||||
See IMPROVEMENTS.md for detailed rationale and evidence.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
#### 7.2 Update IMPROVEMENTS.md Status
|
||||
|
||||
**Mark as implemented**:
|
||||
|
||||
```markdown
|
||||
**Status**: ✅ Implemented
|
||||
**Implementation Date**: [YYYY-MM-DD]
|
||||
**Applied By**: [User/Agent]
|
||||
**Commit**: [Git commit hash]
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
All recommendations successfully applied:
|
||||
- ✅ Recommendation 1: Protocol updated, script added
|
||||
- ✅ Recommendation 2: All protocols updated
|
||||
- ✅ Recommendation 3: Automation added
|
||||
- ✅ Recommendation 4: Workflow updated
|
||||
- ✅ Recommendation 5: Scripts added
|
||||
|
||||
**Next Steps**:
|
||||
- Validate effectiveness in next modernization project
|
||||
- Track metrics to confirm estimated improvements
|
||||
- Iterate based on results
|
||||
```
|
||||
|
||||
#### 7.3 Update HISTORY.md
|
||||
|
||||
**Add entry**:
|
||||
|
||||
```markdown
|
||||
## [Date] - Process Improvements Applied
|
||||
|
||||
**Agent**: Migration Coordinator + All Agents
|
||||
**Action**: Applied recommendations from retrospective
|
||||
|
||||
### What Changed
|
||||
- Applied 5 process improvement recommendations from IMPROVEMENTS.md
|
||||
- Updated protocols in commands/modernize.md, assess.md, plan.md
|
||||
- Added automation: pre-commit hooks, CI/CD workflows, utility scripts
|
||||
- Enhanced documentation with improvement tracking
|
||||
|
||||
### Why Changed
|
||||
- Retrospective analysis identified inefficiencies and risks
|
||||
- Evidence-based recommendations promised 20-30% efficiency gain
|
||||
- Continuous improvement culture
|
||||
|
||||
### Impact
|
||||
- Protocol enhancements: 3 files updated
|
||||
- New automation: 2 scripts, 1 CI/CD workflow, 1 pre-commit hook
|
||||
- Estimated time savings: 4-6 days per future project
|
||||
- Risk reduction: Earlier detection of security and dependency issues
|
||||
|
||||
### Outcome
|
||||
✅ All recommendations implemented and validated
|
||||
📊 Will track effectiveness in next project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Application is successful when**:
|
||||
|
||||
✅ **All Approved Recommendations Applied**:
|
||||
- Protocol files updated correctly
|
||||
- Automation scripts created and tested
|
||||
- Configuration changes made
|
||||
- Documentation updated
|
||||
|
||||
✅ **Validation Passed**:
|
||||
- All syntax valid
|
||||
- Scripts executable and functional
|
||||
- Links work
|
||||
- No broken references
|
||||
|
||||
✅ **Properly Documented**:
|
||||
- Git commit with detailed message
|
||||
- IMPROVEMENTS.md status updated
|
||||
- HISTORY.md entry added
|
||||
- CHANGELOG.md updated
|
||||
|
||||
✅ **Testable**:
|
||||
- Automation can be executed
|
||||
- Changes can be validated
|
||||
- Rollback procedure documented
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
**If issues occur during application**:
|
||||
|
||||
### 1. Immediate Rollback
|
||||
|
||||
```bash
|
||||
# Revert all changes
|
||||
git reset --hard HEAD~1
|
||||
|
||||
# Or revert specific files
|
||||
git checkout HEAD~1 -- commands/modernize.md
|
||||
git checkout HEAD~1 -- scripts/
|
||||
```
|
||||
|
||||
### 2. Partial Rollback
|
||||
|
||||
**If one recommendation causes issues**:
|
||||
|
||||
```bash
|
||||
# Revert just that change
|
||||
git revert <commit-hash-for-that-recommendation>
|
||||
|
||||
# Update IMPROVEMENTS.md
|
||||
# Mark recommendation as "Rolled Back - [Reason]"
|
||||
```
|
||||
|
||||
### 3. Document Issue
|
||||
|
||||
**Update IMPROVEMENTS.md**:
|
||||
|
||||
```markdown
|
||||
### Recommendation X: [Title]
|
||||
|
||||
**Status**: ❌ Rolled Back
|
||||
**Reason**: [Specific issue encountered]
|
||||
**Date**: [YYYY-MM-DD]
|
||||
|
||||
**Issue Details**:
|
||||
- [What went wrong]
|
||||
- [Impact observed]
|
||||
|
||||
**Next Steps**:
|
||||
- [How to address in future]
|
||||
- [Alternative approach]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
### Applying All Recommendations
|
||||
|
||||
```
|
||||
User: /retro-apply
|
||||
User: Apply all recommendations
|
||||
|
||||
Claude: Loading IMPROVEMENTS.md...
|
||||
|
||||
Found 5 recommendations:
|
||||
1. Front-load dependency analysis (P0, High impact, Medium effort)
|
||||
2. Continuous documentation (P0, High impact, Low effort)
|
||||
3. Automated security scanning (P0, High impact, Medium effort)
|
||||
4. Parallel testing workflow (P1, Medium impact, Low effort)
|
||||
5. Quality gate automation (P1, Medium impact, Low effort)
|
||||
|
||||
Confirm: Apply all 5 recommendations? (yes/no)
|
||||
|
||||
User: yes
|
||||
|
||||
Claude: ✅ Confirmed. Beginning implementation...
|
||||
|
||||
[Phase 1: Review and Approval]
|
||||
- Marking recommendations as approved in IMPROVEMENTS.md
|
||||
|
||||
[Phase 2: Implementation Planning]
|
||||
- Analyzing dependencies between recommendations
|
||||
- Creating execution plan
|
||||
- Estimated time: 7.5 hours
|
||||
|
||||
Execution Plan:
|
||||
Phase A (Foundation):
|
||||
- Rec 2: Continuous documentation (1h)
|
||||
- Rec 1: Front-load dependency analysis (2h)
|
||||
Phase B (Dependent):
|
||||
- Rec 3: Automated security scanning (2h)
|
||||
Phase C (Enhancements):
|
||||
- Rec 4: Parallel testing (1.5h)
|
||||
- Rec 5: Quality gates (1h)
|
||||
|
||||
[Phase 3: Apply Protocol Updates]
|
||||
- Updating commands/modernize.md
|
||||
✅ Added Phase 0.5: Dependency Migration Matrix
|
||||
✅ Updated all phases for continuous documentation
|
||||
✅ Added parallel testing workflow
|
||||
- Updating commands/assess.md
|
||||
✅ Added dependency analysis step
|
||||
- Updating commands/plan.md
|
||||
✅ Added dependency migration matrix planning
|
||||
|
||||
[Phase 4: Add Automation]
|
||||
- Creating scripts/analyze-dependencies.sh
|
||||
✅ Script created and tested
|
||||
- Creating .git/hooks/pre-commit
|
||||
✅ Pre-commit hook installed
|
||||
- Creating .github/workflows/security-scan.yml
|
||||
✅ CI/CD workflow added
|
||||
- Creating scripts/enforce-coverage.sh
|
||||
✅ Quality gate script created
|
||||
|
||||
[Phase 5: Update Documentation]
|
||||
- Updating README.md
|
||||
✅ Process improvements section added
|
||||
- Creating PROTOCOLS.md
|
||||
✅ Protocol index created
|
||||
- Updating CHANGELOG.md
|
||||
✅ Changelog entry added
|
||||
|
||||
[Phase 6: Validation]
|
||||
- Validating protocol syntax: ✅ All valid
|
||||
- Testing automation scripts: ✅ All pass
|
||||
- Checking documentation links: ✅ All work
|
||||
|
||||
[Phase 7: Commit and Track]
|
||||
- Committing changes
|
||||
✅ Commit [abc123] created
|
||||
- Updating IMPROVEMENTS.md status
|
||||
✅ Marked as implemented
|
||||
- Adding HISTORY.md entry
|
||||
✅ Entry added
|
||||
|
||||
✅ All 5 recommendations successfully applied!
|
||||
|
||||
Summary:
|
||||
- Protocol files updated: 3
|
||||
- Scripts added: 2
|
||||
- CI/CD workflows added: 1
|
||||
- Pre-commit hooks: 1
|
||||
- Documentation updated: 3 files
|
||||
|
||||
Estimated impact: 4-6 days savings per future project
|
||||
|
||||
Next: Validate improvements in next modernization project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
❌ **Applying without approval** - Always get user confirmation first
|
||||
❌ **Partial application** - If starting, complete all approved recommendations
|
||||
❌ **No validation** - Always test scripts and automation before committing
|
||||
❌ **Poor documentation** - Document what changed and why in commits
|
||||
❌ **No rollback plan** - Always know how to undo changes
|
||||
❌ **Ignoring dependencies** - Apply recommendations in correct order
|
||||
❌ **Breaking existing workflows** - Ensure changes are backward compatible
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Recommendation unclear or ambiguous
|
||||
|
||||
**Solution**:
|
||||
- Ask user for clarification
|
||||
- Update IMPROVEMENTS.md with clearer description
|
||||
- Don't guess at implementation
|
||||
|
||||
### Issue: Automation script fails validation
|
||||
|
||||
**Solution**:
|
||||
- Debug script
|
||||
- Test in isolation
|
||||
- Don't commit broken automation
|
||||
- Document issue in IMPROVEMENTS.md
|
||||
|
||||
### Issue: Protocol update creates inconsistency
|
||||
|
||||
**Solution**:
|
||||
- Review full protocol for consistency
|
||||
- Update related sections
|
||||
- Validate all internal links
|
||||
- Check examples align with changes
|
||||
|
||||
### Issue: Merge conflicts in protocols
|
||||
|
||||
**Solution**:
|
||||
- Manually resolve conflicts
|
||||
- Prioritize new improvements
|
||||
- Validate merged result
|
||||
- Test all changes
|
||||
|
||||
---
|
||||
|
||||
**Document Owner**: Migration Coordinator
|
||||
**Protocol Version**: 1.0
|
||||
**Last Updated**: 2025-11-01
|
||||
**Prerequisite**: `/retro` command must be run first
|
||||
**Input**: IMPROVEMENTS.md
|
||||
|
||||
**Remember**: **Improvements are worthless if not applied. Make changes permanent through automation and protocols.** ✅
|
||||
Reference in New Issue
Block a user