# pi-healing

A 4-phase **skill chain for pi** that finds bugs and heals a codebase,
with human review between every phase.

```
/heal-scan          find bugs, write findings        (read-only)
     ↓ (you review)
/heal-plan          rank bugs, propose fixes         (read-only)
     ↓ (you approve)
/heal-fix           apply fixes one bug at a time    (edits code)
     ↓
/heal-verify        full test suite + HEAL-REPORT.md (read-only)
```

## Install

Install as a pi package:

```bash
npm i -g @earendil-works/pi-coding-agent   # pi itself, if you don't have it
pi install pi-healing
```

Or straight from git:

```bash
pi install git:github.com/KcAnom/pi-healing
```

`pi-healing` uses only plain pi tools — no other packages required.

## Use

`cd` into any project and run `/heal-scan` (or say "find bugs in this project").
Each phase ends with a handoff line telling you what to run next.

## How it works

- All phases share one state file, `.heal-state.md`, at the root of the project
  being healed — the chain survives across sessions and context windows.
- Each phase validates the previous phase's status (and `chain_version`) before
  doing any work, writes the state file atomically (temp file + rename), and
  guards against concurrent sessions with a `.heal-state.lock`.
- `heal-scan` records a **baseline** (exact test/type/lint/build commands and
  their counts) and hunts with per-language patterns for silent failures plus a
  churn-guided deep read of the hottest files. Every finding must carry
  reproducible evidence — no vague smells. Works on projects with zero test
  tooling: the missing test suite becomes a finding and verification goes
  manual.
- `heal-plan` confirms each finding is real before it can be fixed (false
  positives become won't-fix, with reasons) and gives every fix a named
  **Verify** method — an existing test, a new regression test, or a manual
  command.
- Only `heal-fix` modifies code, one bug at a time: regression test first where
  the project supports it, then the fix, then that bug's Verify method. A fix
  that breaks a previously-passing test is auto-reverted. Optional per-fix git
  commits (asked once, never without a yes).
- `heal-verify` re-runs the baseline commands, diffs before vs after, and
  writes `HEAL-REPORT.md` with the proof table and a follow-up list that seeds
  the next run.

Chain version: 1

The state file format is identical to the Claude Code edition at
[elev8tion/cc-healing](https://github.com/elev8tion/cc-healing) — a run started
by one agent can be resumed by the other (the lock file prevents concurrent runs).