autocorrect

Files (5)

• LIMITATIONS.md
• SKILL.md
• autocorrect-prompts.md · references/
• corrections-log-format.md · references/
• wiring-existing-verifiers.md · references/

SKILL.md (first lines)

# Autocorrect

The meta-improvement layer: passive capture, fresh-API review, human triage in 20 minutes per month.

**Harness boundary:** the capture wiring is Claude-specific. The git post-commit hook, verifier wrapper paths, and watermarks live under `~/.claude/`, and the cron registers launchd jobs on this machine. On another harness only the manual `/autocorrect review` command runs. The passive writers are absent, and the skill says so rather than pretending the loop is armed.

## Three writers, one log, one consumer

Capture surfaces (write to `~/.fno/logs/corrections.log`, never invoked by the agent):

1. **git post-commit hook on `~/.claude/`** records every edit to rule/skill/CLAUDE.md files. Severity S1 by default; S0 if the commit subject starts with `urgent:` or `revert:`.
2. **pre-commit verifier wrapper** (`scripts/corrections-verifier-log.sh`) any verifier in any repo calls when it blocks a commit. Verifier decides the severity (S0 for secret-scanner, S1 for style/lint, S2 for drift).
3. **`/fno:intel` correction ingester** (`scripts/corrections-insights-tag.sh`) ports `#agent-correction`-tagged `/fno:intel` report lines as S2 events.

Consumer surface (this skill):

- **Weekly review** (Mondays, 09:00 local) sends the last 30 days of S1+S2 events plus the current full text of every implicated rule file to a fresh Claude API call. Output is a numbered patch list.
- **S0 watcher** (every 15 minutes) catches any unprocessed S0 events and fires an immediate review.
- **Triage** walks the patch list interactively with accept/reject/defer/skip/quit per item. An accepted diff to a shipped skill (`skills/<name>/SKILL.md` in this repo) is never applied locally. Triage files a backlog node, and a worker ships it through the normal PR path. The shipping commit carries the trailer `Autocorrect-Ref: <review_id>#<N>`, so the post-commit hook's row links back to the proposal.

## Commands

| Command | What it does |
|---|---|
| `/autocorrect review [--severity S0\|S1\|S2]` | Build a packet and call the reviewer now. Severity filter optional. |
| `/autocorrect triage [--review-id <id>]` | Walk the latest (or specified) patch list interactively. |
| `/autocorrect status` | Show scheduled jobs, latest review, pending patches, watermark state. |
| `/autocorrect install` | Register the weekly cron and the S0 watcher (idempotent). |
| `/autocorrect ingest-insights` | Manually run the `/fno:intel` report ingestion path (`--insights-file <intel report>`). |

All commands are thin wrappers over scripts in this plugin's `scripts/` directory.

## Invariants (read before extending)

1. **The agent is never the capture surface.** All three writers are passive (git hooks, verifier wrappers, scheduled ingester). If you find yourself proposing an agent-direct write, you're holding the wrong end of the loop.
2. **Single artifact.** Everything funnels through `~/.fno/logs/corrections.log`. Three writers, one consumer. Resist the urge to add ad-hoc per-source logs.
3. **Severity tiers, not frequency thresholds.** S0 fires immediately on a single event. S1 and S2 both roll up in the weekly review. The registered cron passes `--severity S1,S2` on Mondays, and that scheduler is the one cadence owner. The writer decides severity.
4. **Reviewer sees current full rule text, not just diffs.** Decisions are made against the rule as it stands today, not its history.
5. **L1 -> L2 migration discipline.** Rules are a holding pen; verifiers are the destination. CONVERT-TO-VERIFIER patches MUST delete the rule text in the same commit they add the verifier. `autocorrect-triage.sh` surfaces this invariant.
6. **The loop's success metric is patch volume decreasing.** Patch volume dropping is the goal, not a failure signal. The loop retires successfully when verifiers absorb every recurring correction class.

## File map

| File | Purpose |
|---|---|
| `~/.fno/logs/corrections.log` | The canonical capture artifact. Mode 0600. |
| `~/.claude/.corrections-watermark` | Last weekly review window end. |
| `~/.claude/.s0-watcher-watermark` | Last S0 watcher tick. |
| `~/.claude/.s0-processed.log` | Per-event hashes of S0 events already dispatched. |
| `~/.fno/logs/corrections.log.wm` | Per-event hashes ingested from the intel report. |
| `~/.fno/corrections-rejected.log` | Items the user rejected during triage. |
| `~/.claude/corrections-malformed.log` | Items where the patch did not apply cleanly. |
| `~/.claude/proposed-patches/{review_id}.md` | The reviewer's patch list per review. |

## Setup

```bash
# Upgrading from before ab-f063 Wave 2? corrections.log moved from ~/.claude/
# to ~/.fno/ (placement rule). Run this once first - it appends any existing
# ~/.claude/corrections.log content to the new location and tombstones the
# old file. No-op if there's nothing to migrate.
bash $CLAUDE_PLUGIN_ROOT/scripts/corrections-migrate-to-fno.sh

# One-time bootstrap (creates corrections.log, installs git post-commit hook,
# registers the launchd jobs)
bash $CLAUDE_PLUGIN_ROOT/scripts/corrections-log-init.sh
bash $CLAUDE_PLUGIN_ROOT/scripts/install-corrections-git-hook.sh
bash $CLAUDE_PLUGIN_ROOT/scripts/install-autocorrect-cron.sh

# Verify
bash $CLAUDE_PLUGIN_ROOT/scripts/install-autocorrect-cron.sh --status

# Tail the log
tail -f ~/.fno/logs/corrections.log
```

After setup, the loop runs unattended. The user only interacts during triage (~20 min/month) or to acknowledge an S0 review.

## References

- `references/corrections-log-format.md` - canonical format for the log
- `references/wiring-existing-verifiers.md` - how to add a new verifier writer
- `references/autocorrect-prompts.md` - canonical reviewer prompt template

## Retirement

The loop self-retires when, for two consecutive years, no S0 event has been caught only by this loop (i.e., every S0 was also caught by a deterministic verifier). At that point the verifier layer has fully absorbed the work and the meta-loop is no longer load-bearing. Delete the schedule, leave the capture infrastructure running as a paper trail, and move on.

## Known Limitations and Deferred Work

- Human triage is required before autocorrect changes guidance. See [LIMITATIONS.md](LIMITATIONS.md).

From bllshttng/fno, Apache-2.0.

More from bllshttng/fno