source-command-self-heal

Use this skill when the user asks to run the migrated source command self-heal. Original argument hint: [plan-file-path-or-feature-name].

Command Template

Self-Heal: Capability Retrospective

Mission

Look at the work just completed: the plan, implementation, adversarial review cycles, /review, /evaluate, validation, and any live debugging. Ask what the repo learned and how to make that lesson stick.

/self-heal is not a code review. /review and /evaluate already do that. This command captures durable workflow improvements:

1. Rule updates that prevent recurrence.
2. Tripwire tests or grep checks for missed failure modes.
3. Command or skill updates that close process gaps.
4. Documentation drift fixes tied to current code or incident evidence.
5. Process patterns worth preserving for future m0lz/editorial pipeline work.

When To Run

• After a multi-cycle /evaluate or adversarial review.
• After a live publishing, update, unpublish, benchmark, or release incident.
• After /review catches a class of defect, not just one instance.
• After a feature touches multiple subsystems and exposes workflow drift.
• Periodically on the most recent active plan.

Do not run /self-heal for trivial fixes, one-pass clean evaluations, or docs changes with no broader lesson.

Step 1: Identify Source Material

If {user-provided arguments} is provided, use it as the plan file path or feature name. If not provided, default to the most recently modified source plan across Claude and Codex plan folders. Prefer a plan with a ## Contract section, because proof/evidence notes can also live under plans/ and are not the source material for a retrospective.

PLAN_FILE=""
for f in $(ls -t .claude/plans/*.md .codex/plans/*.md 2>/dev/null); do
  if rg -q '^## Contract$' "$f"; then
    PLAN_FILE="$f"
    break
  fi
done
if [ -z "$PLAN_FILE" ]; then
  for f in $(ls -t .claude/plans/*.md .codex/plans/*.md 2>/dev/null); do
    case "$f" in
      *proof*.md|*evidence*.md) continue ;;
    esac
    PLAN_FILE="$f"
    break
  done
fi
printf '%s\n' "$PLAN_FILE"

Read the source plan in full. Pay attention to:

• Contract criteria and thresholds.
• Adversarial review findings.
• Each /evaluate or review cycle, especially resolved HIGH/MEDIUM items.
• Commit messages or plan cycle notes that identify defect classes.
• Runtime logs, publishing state, smoke notes, or DB checks that changed the diagnosis.

Use current checkout facts, not stale plan assumptions.

Step 2: Extract Patterns

For each defect class or workflow miss, classify it:

Every lesson must have a forensic anchor:

• File and line, route, test, log string, query, or run id.
• The cycle or incident that exposed it.
• One sentence explaining what the rule prevents.

Avoid aspirational rules. If the lesson cannot be anchored to evidence, do not promote it into durable guidance.

Step 3: Decide Where It Lives

Use this precedence:

1. Mechanical tripwire or regression test when the failure is machine-checkable.
2. Command or skill update when the failure was process drift.
3. .claude/rules/* and .codex/rules/* when the lesson is subsystem-scoped.
4. AGENTS.md and CLAUDE.md only for cross-cutting rules that should load in every session.

Keep Claude and Codex surfaces synchronized. If you update a Claude command or rule, mirror the durable content into the Codex wrapper/source skill/rule unless there is a deliberate tool-specific difference.

Step 4: Write The Changes

Make the retrospective changes now while the evidence is fresh. Do not defer durable process fixes to a follow-up unless user judgment is required.

For each change:

Do not commit, push, deploy, or mutate production configuration from this command unless the user explicitly asks.

Step 5: Verify

Run the narrow validation that matches the changes:

• Command/rule-only changes: verify file presence, frontmatter, and parity.
• New tests: run the new test file and any directly related suite.
• Review-harness changes: run the command's own inventory checks where feasible.
• Repo-wide behavioral changes: use the validation chain required by the active plan or AGENTS.md.

If a new tripwire fails on day zero, either fix the live violation or document a specific allowlist rationale. Do not leave a vacuous test that scans no files.

Step 6: Report

Return a concise report:

## /self-heal: <feature or plan>

### Source Material
- Plan/run/logs reviewed:
- Cycles reviewed:
- Defect classes captured:

### Changes Made
- Tripwire tests:
- Rule updates:
- Command/skill updates:
- Documentation corrections:

### Open Follow-Ups
- Items needing user judgment:

### Validation
- Commands run:
- Result: