Heal Million Dollar Skills

This skill does NOT:

• Modify production code in scaffolded projects
• Auto-merge changes to main branch
• Run without human review of proposed changes

ARCHITECTURE: SUB-AGENT ORCHESTRATION

This skill acts as an ORCHESTRATOR, not an implementer.

/heal-million-dollar-skills (Orchestrator)
    |
    |---> [Step 1] Load Aggregated Feedback
    |     - Read ~/.claude/skills-feedback/aggregate.json
    |     - Filter to relevant time window
    |
    |---> [Step 2] Pattern Analysis (Sub-Agent)
    |     - skills/heal-million-dollar-skills/agents/pattern-analyzer.md
    |     - Identify recurring errors
    |     - Detect slow phases
    |     - Find common failure modes
    |
    |---> [Step 3] Improvement Generation (Sub-Agent)
    |     - skills/heal-million-dollar-skills/agents/improvement-generator.md
    |     - Propose specific skill modifications
    |     - Generate before/after diffs
    |
    |---> [Step 4] Validation (Sub-Agent)
    |     - skills/heal-million-dollar-skills/agents/validator.md
    |     - Validate skill syntax
    |     - Check reference integrity
    |     - Assess risk level
    |
    |---> [Step 5] Git Version Control
    |     - Create branch: heal/[timestamp]-[summary]
    |     - Commit with detailed message
    |
    +---> [Step 6] Report Generation
          - Generate healing report
          - Save to perpetual folder

ORCHESTRATION WORKFLOW

[0/6] Initialize Session

Starting /heal-million-dollar-skills...
----------------------------------------------------

[0/6] Initializing session...
      --> Loading configuration
      --> Checking feedback availability

[1/6] Load Feedback from ALL Sources

CRITICAL: The healing skill must check MULTIPLE feedback sources, not just aggregate.json.

// Load config
const config = JSON.parse(read('./perpetual.config.json'));
const healConfig = JSON.parse(read('./skills/heal-million-dollar-skills/config.json'));

// ============================================
// SOURCE 1: Central Aggregation File
// ============================================
const feedbackDir = expandPath(config.paths.feedback_aggregation_dir);
const aggregate = JSON.parse(read(`${feedbackDir}/aggregate.json`));

// ============================================
// SOURCE 2: Project-Level Feedback Files
// ============================================
const projectsBaseDir = expandPath(config.paths.projects_base_dir);
const projectFeedback = [];

// Glob for all .planning/feedback.md files
const feedbackFiles = glob(`${projectsBaseDir}/**/.planning/feedback.md`);
for (const file of feedbackFiles) {
  const content = read(file);
  projectFeedback.push({
    source: 'human_review',
    file: file,
    content: content
  });
}

// Glob for all .planning/automated-feedback.json files
const automatedFiles = glob(`${projectsBaseDir}/**/.planning/automated-feedback.json`);
for (const file of automatedFiles) {
  const content = JSON.parse(read(file));
  projectFeedback.push({
    source: 'automated',
    file: file,
    content: content
  });
}

// ============================================
// SOURCE 3: Tracking File Denial Feedback
// ============================================
const tracking = JSON.parse(read(config.paths.tracking_file));
const denialFeedback = [];

for (const [slug, idea] of Object.entries(tracking.ideas)) {
  if (idea.denial_feedback && idea.denial_feedback.length > 0) {
    denialFeedback.push({
      slug: slug,
      denials: idea.denial_feedback,
      history: idea.history.filter(h => h.action === 'denied')
    });
  }
}

// ============================================
// Combine All Feedback Sources
// ============================================
const allFeedback = {
  aggregate: aggregate,
  project_feedback: projectFeedback,
  denial_feedback: denialFeedback,
  totals: {
    aggregate_executions: aggregate.totals.total_executions,
    project_feedback_files: projectFeedback.length,
    denial_entries: denialFeedback.reduce((sum, d) => sum + d.denials.length, 0)
  }
};

// Calculate total feedback items (not just aggregate executions)
const totalFeedbackItems =
  allFeedback.totals.aggregate_executions +
  allFeedback.totals.project_feedback_files +
  allFeedback.totals.denial_entries;

// Check minimum samples - NOW considers ALL sources
if (totalFeedbackItems < 1) {
  console.log(`
    INSUFFICIENT DATA
    =================
    Aggregate executions: ${allFeedback.totals.aggregate_executions}
    Project feedback files: ${allFeedback.totals.project_feedback_files}
    Denial entries: ${allFeedback.totals.denial_entries}
    Total: ${totalFeedbackItems}

    No feedback found. Run skill executions and reviews first.
  `);
  return;
}

[1/6] Loading feedback from ALL sources...
      --> Central aggregate: ~/.claude/skills-feedback/aggregate.json
      --> Project feedback: ${projectsBaseDir}/**/.planning/feedback.md
      --> Automated feedback: ${projectsBaseDir}/**/.planning/automated-feedback.json
      --> Tracking denials: ./ideas/_tracking.json

      Feedback Summary:
      +---------------------------+-------+
      | Source                    | Count |
      +---------------------------+-------+
      | Aggregate executions      | 0     |
      | Project feedback files    | 1     |
      | Denial entries            | 1     |
      +---------------------------+-------+
      | TOTAL                     | 2     |
      +---------------------------+-------+

      Ready for analysis (found feedback from project files)

[2/6] Pattern Analysis

Spawn the pattern analyzer agent:

Task({
  subagent_type: "general-purpose",
  description: "Pattern analysis agent",
  prompt: `
    Read and execute: skills/heal-million-dollar-skills/agents/pattern-analyzer.md

    Aggregate Path: ${feedbackDir}/aggregate.json
    Min Samples: ${healConfig.thresholds.min_samples_per_pattern}
    Lookback Days: ${healConfig.thresholds.lookback_days}

    Return comprehensive analysis JSON.
  `
})

[2/6] Analyzing patterns...
      --> Pattern Analyzer: Loading 150 executions
      --> Found 3 recurring error patterns
      --> Identified 2 slow phases
      --> Detected 1 quality trend

[3/6] Improvement Generation

Spawn the improvement generator agent:

Task({
  subagent_type: "general-purpose",
  description: "Improvement generation agent",
  prompt: `
    Read and execute: skills/heal-million-dollar-skills/agents/improvement-generator.md

    Analysis: ${JSON.stringify(patternAnalysis, null, 2)}
    Skills Directory: ./skills
    Max Changes: ${healConfig.thresholds.max_changes_per_run}

    Return proposed improvements with diffs.
  `
})

[3/6] Generating improvements...
      --> Improvement Generator: Prioritizing 5 issues
      --> Generating fix for OAuth timeout
      --> Generating performance optimization
      --> 3 improvements proposed

[4/6] Validation

Spawn the validator agent:

Task({
  subagent_type: "general-purpose",
  description: "Validation agent",
  prompt: `
    Read and execute: skills/heal-million-dollar-skills/agents/validator.md

    Improvements: ${JSON.stringify(proposedImprovements, null, 2)}
    Skills Directory: ./skills
    Dry Run: true

    Return validation results.
  `
})

[4/6] Validating improvements...
      --> Validator: Checking 3 proposed changes
      --> implement-million-dollar-app: APPROVED (low risk)
      --> verify-million-dollar-app: REJECTED (missing reference)
      --> theme-million-dollar-app: APPROVED (medium risk)
      --> 2/3 improvements validated

[5/6] Git Version Control

Create branch and commit approved changes:

// Generate branch name
const timestamp = new Date().toISOString().slice(0, 10);
const summary = generateBranchSummary(validatedImprovements);
const branchName = `heal/${timestamp}-${summary}`;

// Create branch
exec(`git checkout -b ${branchName}`);

// Apply each validated improvement
for (const improvement of validatedImprovements.filter(i => i.approved)) {
  // Write the modified skill file
  write(improvement.file, improvement.after);

  // Stage the change
  exec(`git add ${improvement.file}`);
}

// Commit with detailed message
const commitMessage = generateCommitMessage(validatedImprovements);
exec(`git commit -m "${commitMessage}"`);

// Return to main branch
exec(`git checkout main`);

[5/6] Creating git branch...
      --> Branch: heal/2026-01-17-retry-improvements
      --> Applying 2 approved changes
      --> Committing changes
      --> Returning to main branch

[6/6] Report Generation

Generate healing report:

const report = {
  timestamp: new Date().toISOString(),
  branch_name: branchName,
  analysis_summary: patternAnalysis.summary,
  improvements_proposed: proposedImprovements.length,
  improvements_approved: validatedImprovements.filter(i => i.approved).length,
  improvements_rejected: validatedImprovements.filter(i => !i.approved).length,
  files_modified: validatedImprovements.filter(i => i.approved).map(i => i.file),
  next_steps: [
    `Review branch: git diff main...${branchName}`,
    `Merge if approved: git merge ${branchName}`,
    `Or discard: git branch -D ${branchName}`
  ]
};

write('./healing-reports/report-${timestamp}.json', JSON.stringify(report, null, 2));

[6/6] Generating report...
      --> Report saved to healing-reports/

----------------------------------------------------

HEALING COMPLETE

Branch: heal/2026-01-17-retry-improvements

Summary:
+---------------------------+-------+
| Metric                    | Value |
+---------------------------+-------+
| Patterns analyzed         | 6     |
| Improvements proposed     | 3     |
| Improvements approved     | 2     |
| Files modified            | 2     |
+---------------------------+-------+

Modified Files:
1. skills/implement-million-dollar-app/skill.md
2. skills/theme-million-dollar-app/skill.md

Next Steps:
1. Review: git diff main...heal/2026-01-17-retry-improvements
2. Merge:  git checkout main && git merge heal/2026-01-17-retry-improvements
3. Or discard: git branch -D heal/2026-01-17-retry-improvements

GIT BRANCHING STRATEGY

All healing changes go to dedicated branches:

main
 ├── heal/2026-01-15-timeout-fixes
 ├── heal/2026-01-17-retry-improvements
 └── heal/2026-01-19-performance-optimizations

Branch Naming Convention

heal/{date}-{summary}

Examples:

• heal/2026-01-17-retry-improvements
• heal/2026-01-18-phase-timeout-fix
• heal/2026-01-19-error-handling

Commit Message Format

[heal] {summary}

Automated skill improvements based on {N} execution feedback.

Changes:
- {skill1}: {change description}
- {skill2}: {change description}

Analysis:
- Recurring errors addressed: {count}
- Slow phases optimized: {count}
- Quality improvements: {count}

Co-Authored-By: Claude Opus 4.5 <[email protected]>

CONFIGURATION

See config.json for thresholds:

{
  "thresholds": {
    "min_executions_to_heal": 10,
    "min_samples_per_pattern": 3,
    "lookback_days": 30,
    "max_changes_per_run": 5,
    "max_risk_level": "medium"
  }
}

ERROR HANDLING

Insufficient Data

INSUFFICIENT DATA
=================

Not enough execution data to identify patterns.

Current: 5 executions
Required: 10 minimum

Actions:
- Run more skill executions
- Or lower min_executions_to_heal in config.json

No Issues Found

NO ISSUES FOUND
===============

All skills are performing well!

Metrics:
- Error rate: 2% (below threshold)
- Avg duration: Within expected range
- Quality scores: Stable

No healing required at this time.

Validation Failures

If all improvements fail validation:

ALL IMPROVEMENTS REJECTED
=========================

No improvements passed validation.

Rejection reasons:
1. implement-skill: Missing file reference
2. verify-skill: Invalid syntax
3. theme-skill: High risk level

Manual review recommended.

VERIFICATION

After healing, verify:

1. Git branch created with correct name
2. Changes committed with proper message
3. Main branch unchanged
4. Healing report generated
5. No syntax errors in modified files

NEXT STEPS AFTER COMPLETION

1. Review changes: git diff main...heal/[branch-name]
2. Test affected skills: Run the modified skills manually
3. Merge if approved: git checkout main && git merge heal/[branch-name]
4. Or discard: git branch -D heal/[branch-name]