autoresearch-hooks

Files (11)

• SKILL.md
• README.md · examples/
• auto-tag-winners.sh · examples/after/
• learnings-journal.sh · examples/after/
• macos-notify.sh · examples/after/
• anti-thrash.sh · examples/before/
• context-rotation.sh · examples/before/
• external-search.sh · examples/before/
• hypothesis-reflection.sh · examples/before/
• idea-rotator.sh · examples/before/
• qmd-search.sh · examples/before/

SKILL.md (first lines)

# autoresearch-hooks

Optional scripts that run at iteration boundaries in an autoresearch session. Two hooks, both transparent to the loop-running agent — their effect is a file on disk or a steer message.

```
.auto/hooks/
  before.sh    # fires before each iteration (prospective)
  after.sh     # fires after each log_experiment (retrospective)
```

Both files are optional. Files without the executable bit are silently ignored.

---

## Contract

### Stdin — `before.sh`

One JSON line. Parse with `jq`. Realistic example:

```json
{
  "event": "before",
  "cwd": "/path/to/workdir",
  "next_run": 6,
  "last_run": {
    "run": 5,
    "status": "discard",
    "metric": 42.1,
    "description": "Simplified to sorted(arr) — copy cost dominates",
    "asi": {
      "hypothesis": "Built-in sort avoids Python overhead",
      "next_focus": "list copy avoidance"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 5,
    "goal": "optimize sort speed"
  }
}
```

| Field                     | Notes                                                               |
| ------------------------- | ------------------------------------------------------------------- |
| `last_run`                | The most recent run entry. `null` on a fresh session.               |
| `session.direction`       | `"lower"` or `"higher"` — which end of the scale wins.              |
| `session.baseline_metric` | First run of the current segment. `null` until one run exists.      |
| `session.best_metric`     | Optimal metric across **kept** runs only. `null` until one is kept. |
| `session.goal`            | The session name set by `init_experiment`.                          |
| `session.run_count`       | Total runs logged so far (any status).                              |

### Stdin — `after.sh`

```json
{
  "event": "after",
  "cwd": "/path/to/workdir",
  "run_entry": {
    "run": 6,
    "status": "discard",
    "metric": 38.9,
    "description": "Timsort hybrid slower on random",
    "asi": {
      "hypothesis": "Partial-sort heuristic on input distribution",
      "learned": "Overhead dominates on random arrays"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 6,
    "goal": "optimize sort speed"
  }
}
```

| Field       | Notes                                                         |
| ----------- | ------------------------------------------------------------- |
| `run_entry` | The run just logged. Always present.                          |
| `session`   | Same shape as in `before.sh`, reflecting state after the run. |

### Output

- **Stdout** (up to 8 KB) — delivered to the agent as a steer message on the next turn. Empty = silent.
- **Stderr + non-zero exit** — surfaced as an error steer.
- **Timeout** — 30 s hard kill; flagged in the observability entry.

### Preservation

`.auto/**` survives the auto-revert — the entire `.auto/` folder is preserved. (Legacy `autoresearch.*` paths are still preserved too, for in-flight sessions.)

---

## Examples

Runnable reference scripts live in this skill's `examples/` directory — one file per pattern. Paths are resolved against the skill directory (parent of SKILL.md). Browse them for inspiration; they're not policy.

- `examples/before/` — external search, qmd document search, anti-thrash, idea rotator, hypothesis reflection, context rotation
- `examples/after/` — learnings journal, macOS notification on new best, auto-tag winning commits

Each example is a complete, self-contained script with named constants, short helper functions, guard clauses, and intention-revealing names. Read the header comment for its purpose, copy to `.auto/hooks/<stage>.sh`, adapt.

---

## Steps to add a hook

1. **Understand the session.** Read `.auto/prompt.md` for the objective and metric; glance at `.auto/measure.sh` for the workload. Your hook should complement the loop, not duplicate it.

2. **Clarify the user's intent.** What should happen, at which boundary? Research before / log after / notify on wins / intervene on thrash / etc.

3. **Start from an example in `examples/`** that's closest to the intent (resolve against the skill directory). If nothing fits, write from scratch following the same style (named constants, short functions, guard clauses, JSON stdin parsed with `jq`). If the request combines retrospective + prospective concerns, use both `before.sh` and `after.sh` — don't overload one.

From lseman/logician, MIT.

More from lseman/logician