Self Healing Ci

Self-Healing CI

CI-only variant of `self-healing`. Runs the diagnose → patch → verify → file loop headlessly against pull-request and scheduled workflow events.

Install

gh skill install pskoett/pskoett-skills self-healing-ci

Fallback using the Agent Skills CLI:

npx skills add pskoett/pskoett-skills/skills/self-healing-ci

Purpose

Run self-healing in CI without interactive chat loops:

• Inspect failed PR checks (test/build/lint/scan/deploy) and parse logs for root cause
• Propose a minimal verified patch as a PR comment or follow-up commit
• Commit a HEAL- entry to .learnings/HEALS.md with verification proof (or pending-verify if the workflow can't re-run the check)
• Search prior HEAL entries by Pattern-Key before filing new ones — deduplicate recurrences
• Append a Handoff block at Recurrence-Count >= 3 for promotion via self-improvement-ci

Use `self-healing` for interactive/local sessions.

Context Limitation (Important)

CI agents do not have peak task context from the original implementation session. The agent is reading CI logs and code, not riding peak context after a focused implementation. Implications:

• Favor conservative diagnoses — when uncertain, file pending-verify and surface to the PR author
• Require mandatory verify before claiming verified — re-run the failing check in the same workflow run
• Never modify project code without an explicit verify pass; propose changes as PR comments unless the workflow is configured for auto-commit
• Route uncertain or high-impact recommendations to interactive review

Prerequisites

1. GitHub Actions enabled for the repository 2. GitHub CLI authenticated in the workflow (gh auth status) 3. gh-aw installed for authoring/validation:

gh extension install github/gh-aw

4. .learnings/HEALS.md committed to the repo (or created on first run; see references/workflow-example.md for the bootstrap pattern)

CI Contract

The CI skill must:

1. Read CI logs, PR diff, and existing .learnings/HEALS.md — nothing else from the PR author's machine 2. Avoid direct code modifications by default — propose via PR comment or label-gated commit 3. Re-run the failing check after applying the proposed patch (when feasible) — verified requires this; pending-verify is honest if it cannot 4. Emit a machine-readable YAML output (see Output Schema) 5. Commit the verified HEAL- entry only on a successful re-run — abandoned heals are still filed, but in a separate commit clearly labeled

Output Schema

self_healing_ci:
  source:
    pr_number: 123
    commit_sha: "abc123def"
    failed_check: "test (node 20)"
    workflow_run_id: 4567891234
  heal:
    heal_id: "HEAL-20260524-001"
    status: "verified"            # verified | pending-verify | abandoned
    trigger: "tool-failure"       # free-form
    active_context: "ci"          # optional
    area: "tests"                 # free-form
    pattern_key: "env.lockfile_mismatch"
    diagnosis: "Project uses pnpm; CI workflow ran `npm ci`."
    fix:
      summary: "Switch the CI install step from `npm ci` to `pnpm install --frozen-lockfile`."
      diff_path: ".learnings/heals/HEAL-20260524-001/patch.diff"   # only if files generated
    verification:
      command: "pnpm install --frozen-lockfile"
      exit_code: 0
      output_excerpt: "Lockfile is up to date, resolution step is skipped"
    recurrence_count: 1
    promotion_ready: false        # true at recurrence_count >= 3
  summary:
    heals_filed: 1
    verified: 1
    pending_verify: 0
    abandoned: 0
    promotion_candidates: 0

Verify-Before-Persist in CI

In CI the verify step is operationalized as re-running the failed check inside the same workflow run after applying the proposed patch:

If the re-run isn't feasible (the check requires secrets only available in production workflows; the failure is transient; the patch needs human review before commit), the HEAL ships as pending-verify with explicit notes on what would prove it.

Never fake `verified`. Faking is the exact failure mode this skill exists to prevent — and in CI, the consequences propagate further than in interactive sessions because future PRs may apply the unverified "fix" automatically.

Recurrence and Promotion Rules

• Search .learnings/HEALS.md by Pattern-Key before filing new heals
• On match: increment Recurrence-Count, update Last-Seen, append the new occurrence to See Also
• Promotion threshold (same as interactive):
• Recurrence-Count >= 3
• Seen across at least 2 distinct PRs/tasks
• The fix is generalizable (not project-specific)
• On promotion: append a Handoff block to the existing HEAL with a Promotion Target (CLAUDE.md / AGENTS.md / .github/copilot-instructions.md / new-skill) and a one-line Distilled Rule
• self-improvement-ci consumes the Handoff blocks and proposes the promotion as a PR

Suggested Workflow Triggers

Authoring patterns and example .github/workflows/*.lock.yml files live in `references/workflow-example.md`. Keep example workflows out of .github/workflows until you've explicitly decided to enable CI automation.

Anti-Patterns in CI

The interactive skill's anti-patterns all apply. CI-specific ones to watch:

1. Auto-commit unverified fixes. A patch that hasn't passed the re-run check should never land on the branch automatically. Propose via PR comment instead. 2. Re-trigger loops. If the heal triggers its own workflow, gate with if: github.actor != 'github-actions[bot]' to prevent infinite loops. 3. Silent retry of flaky tests. A flaky test is not a heal candidate unless the patch actually addresses the non-determinism. Re-running the same flaky test until green is hiding, not healing. 4. Cross-PR `Pattern-Key` collisions. If two PRs hit the same Pattern-Key with different root causes, the keys are too coarse — refine them rather than letting them merge. 5. Heals on infra you don't own. Don't patch a third-party action's source from inside CI — propose a version pin or a configuration change instead.

Cross-references

• `self-healing` — the interactive skill this mirrors; same file format, same verify discipline
• `self-improvement-ci` — receives heal Handoff blocks; proposes promotion to memory files
• `simplify-and-harden-ci` — quality pass after heals stabilize the PR
• `verify-gate` — the interactive verify gate; self-healing-ci's verify is the CI workflow re-run
• `references/workflow-example.md` — gh-aw workflow templates and authoring notes

Self-Healing CI — gh-aw Workflow Examples

Templates for authoring self-healing-ci workflows with gh-aw. Keep these as `.example` files outside `.github/workflows/` until you've decided to enable CI automation in your repo.

Workflow 1: React to failed PR checks (recommended starting point)

# .github/workflows/self-healing-ci.lock.yml.example
# Reacts to any failed workflow_run on a pull request.

on:
  workflow_run:
    workflows: ["CI"]   # the workflow whose failures you want healed
    types: [completed]

permissions:
  contents: read
  pull-requests: write
  actions: read

jobs:
  heal:
    if: ${{ github.event.workflow_run.conclusion == 'failure' && github.event.workflow_run.event == 'pull_request' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_sha }}

      - name: Run self-healing-ci
        uses: githubnext/gh-aw@v0   # or pinned version
        with:
          skill: self-healing-ci
          context: |
            pr_number: ${{ github.event.workflow_run.pull_requests[0].number }}
            failed_workflow_run_id: ${{ github.event.workflow_run.id }}
            failed_check_name: ${{ github.event.workflow_run.name }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Comment heal on PR
        if: success()
        uses: actions/github-script@v7
        with:
          script: |
            // Read the YAML output produced by the skill, format as a PR comment.
            const fs = require('fs');
            const heal = fs.readFileSync('.gh-aw/output/heal.yml', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🩹 Self-Healing Proposal\n\n\`\`\`yaml\n${heal}\n\`\`\`\n\nReview the patch; if verified, merge or apply.`
            });

Anti-loop guard: the if: clause filters to PR-triggered runs only; the implicit github.actor filter prevents re-triggering when the heal itself opens a PR.

Workflow 2: Apply verified heals as follow-up commits

For higher-trust setups where verified heals can land directly. Gate by label so humans opt in.

# .github/workflows/self-healing-apply.lock.yml.example
# Applies verified heals to the PR branch when labeled `auto-heal`.

on:
  workflow_run:
    workflows: ["self-healing-ci"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  apply:
    if: |
      github.event.workflow_run.conclusion == 'success' &&
      contains(github.event.workflow_run.pull_requests[0].labels.*.name, 'auto-heal')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}
          token: ${{ secrets.HEAL_PUSH_TOKEN }}

      - name: Apply patch from heal artifact
        run: |
          # Download the heal artifact (patch.diff) from the upstream workflow.
          gh run download ${{ github.event.workflow_run.id }} --name heal-artifacts -D /tmp/heal
          test -f /tmp/heal/patch.diff || { echo "no patch.diff, nothing to apply"; exit 0; }
          git apply /tmp/heal/patch.diff

      - name: Verify after apply
        run: |
          # Re-run the originally failing check. Bail if it doesn't pass.
          ./.github/scripts/run-failed-check.sh "${{ github.event.workflow_run.name }}"

      - name: Commit heal
        run: |
          git config user.name "self-healing-ci"
          git config user.email "self-healing-ci@users.noreply.github.com"
          git add .learnings/HEALS.md .learnings/heals/ 2>/dev/null || true
          git diff --cached --quiet || git commit -m "heal: apply HEAL from self-healing-ci"
          git push

Important: the Verify after apply step is the load-bearing wall. If the re-run check fails, the workflow exits non-zero and the heal does NOT land. This preserves the verify discipline in CI.

Workflow 3: Scheduled recurrence sweep

Surfaces patterns that the per-PR runs missed.

# .github/workflows/self-healing-sweep.lock.yml.example
on:
  schedule:
    - cron: '0 8 * * 1'  # Mondays at 08:00 UTC
  workflow_dispatch: {}

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  sweep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Aggregate heals + look for promotion candidates
        uses: githubnext/gh-aw@v0
        with:
          skill: self-healing-ci
          mode: sweep   # custom mode the skill can interpret to scan only
          context: |
            window_days: 30
            min_recurrence: 3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Open promotion issue if candidates exist
        if: ${{ steps.sweep.outputs.promotion_candidates > 0 }}
        # ... open an issue listing the candidates for self-improvement-ci to act on

Patch file conventions

When the heal generates a patch (rare — most are config swaps, not code changes), save it as a unified diff at .learnings/heals/<HEAL-ID>/patch.diff. The applier workflow (#2 above) runs git apply against it. Keep patches minimal:

• One logical fix per patch
• No unrelated reformatting
• Touch only the file(s) named in Related Files
• Reversible (the heal author should be able to revert by running the apply in reverse)

Permissions checklist

Avoid granting contents: write on the per-PR heal workflow. Keep apply separate, label-gated, and behind a higher-trust token.

Anti-loop checklist

The heal workflow must not retrigger itself or the workflow it's healing.

1. if: github.actor != 'github-actions[bot]' on every job 2. Skip when the PR branch is self-healing/... (heal-authored) 3. Limit to 3 heal attempts per PR (track via PR comments or a state file) 4. Bail if the same Pattern-Key has been tried on this PR twice in a row without success — that's a flap, not a heal

See also

• Parent skill: `self-healing-ci` — the canonical CI contract and output schema
• Interactive skill: `self-healing` — same loop, same discipline, different runtime
• gh-aw docs — the GitHub Agentic Workflows extension