# hacker

Adopt this skill: https://proskills.md/skills/other/erergb-hacker

Page: https://proskills.md/skills/other/erergb-hacker
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8108
upstream: https://github.com/erergb/hacker/blob/HEAD/SKILL.md

````text
---
name: hacker
description: >
  Define a problem. Aggregate all best practices. Hack it.
  Problem-driven optimization engine for LLM prompts and agent configurations.
  Runs candidates against a test corpus, scores outputs, diagnoses failures,
  explores external evidence, and applies targeted single-variable mutations.
  In Cursor, pair with the ralph-loop skill (/ralph-loop) so each chat turn runs
  exactly one Hacker cycle until completion_promise or max_iterations.
license: MIT
metadata:
  author: ERerGB
  version: "0.2.2"
  tags: problem-driven, best-practices, evidence-driven, optimization, agent-evolution, ralph-loop
---

# Hacker

Define a problem. Aggregate all best practices. Hack it.

You have a prompt that mostly works. Some cases fail. You don't know which
change will fix them without breaking the ones that already pass. So you
guess, test one case, ship, and hope.

Hacker eliminates the guessing. You define the problem as a test corpus
with golden labels. The engine scores every case, diagnoses the single
worst failure, searches the world for evidence-backed solutions, applies
one precise change, re-runs the full corpus, and accepts only if nothing
regressed. One cycle, one variable, full accountability.

```
  [Define]                    [Aggregate]              [Hack]
      ↓                            ↓                      ↓
 Corpus + Labels ──▶ Score ──▶ Diagnose ──▶ Explore ──▶ Mutate ──▶ Re-run
                                                                      ↓
                                                              accept / rollback
```

## Sustaining many cycles (Cursor + Ralph Loop)

Hacker defines **one** cycle (steps 1–10). It does **not** re-invoke itself.

To **keep going** turn after turn until a stop rule fires, use Cursor’s **`ralph-loop`** skill (**`/ralph-loop`**) as the outer driver:

1. Run **`/ralph-loop`** (or attach the **Ralph Loop** skill) and set `max_iterations` + optional `completion_promise` in `.cursor/ralph/scratchpad.md`.
2. Put your **Hacker task** in the scratchpad **body** (corpus path, candidate path, scoring command). Instruct the agent: **each iteration = exactly one Hacker cycle** (one diagnosis, one mutation, full re-run, log) — see **Cursor — Ralph Loop** below for a paste-ready template.
3. On every follow-up, Ralph replays the same prompt; the agent reads the scratchpad, runs the next cycle, appends **Cycle Log**, bumps `iteration` in YAML.

If you skip Ralph Loop, you must **manually** send the same “run one Hacker cycle” instruction each time.

---

## Invariants

Violation of any invariant invalidates the cycle.

- **INVARIANT**: each test case runs in an isolated worker context.
- **INVARIANT**: controller never generates model outputs; it only scores.
- **INVARIANT**: workers must not see golden labels, other test cases, or prior context.
- **INVARIANT**: one mutation per cycle.
- **INVARIANT**: accept/rollback decisions require full-corpus re-run.

---

## The Cycle

Each iteration follows this exact sequence.

### 1. Run

Dispatch each corpus entry to an isolated worker.

**Candidate format**: The candidate under optimization is a
[subagent-harness](https://github.com/ERerGB/subagent-harness) `.agent.md` file.
This gives the cycle a structured representation to read, mutate, and write back.

The Run phase is a three-step pipeline:

```
.agent.md → parse → validate → compose → dispatch N workers
```

1. **Parse** — `parseRichAgentMarkdown(path, content)` → `RichAgentDocument`
2. **Validate** — `validateRichAgent(doc, options?)` → confirm schema integrity (optional `extensionValidator` in `options` for `.agent.ext.yaml` fields; see `subagent-harness` `ValidateOptions`)
3. **Compose** — `composeSubagent(doc, target, profile?)` → runtime-ready artifact (`target`: `cursor` | `codex` | `claude-code` | `production`)
4. **Dispatch** — send the composed artifact to N isolated workers (one per test case)

Worker dispatch shape:

```markdown
You are a worker evaluator. Do not score and do not explain.

## Prompt Under Test
{composed_candidate}

## Input
{single_test_case_input}

## Output Schema
{worker_output_schema}

Return ONLY schema-compliant output.
If prompt indicates no action, return:
{"decision":"no_output","outputs":[]}
```

The `composed_candidate` is the output of `composeSubagent()`, not the raw
`.agent.md` source. Workers receive the runtime-native format for their platform.

### 2. Verify

Before scoring, confirm isolation:

- [ ] each case ran in a fresh worker
- [ ] workers did not receive golden labels
- [ ] workers did not receive other test cases
- [ ] controller only scored worker outputs (no inline generation)

If any item is unchecked: cycle is invalid, re-run.

### 3. Score

Compare worker outputs against golden labels.

- Produce per-case scores across configured dimensions.
- Record both aggregate (mean, median) and tail (min, failure rate).
- Hard-check failures (format, safety) are separate from soft scores.

Scoring dimensions, weights, and thresholds are **project-level configuration**.
See [Configuration](#configuration) for how to define them.

### 4. Diagnose

Identify the single primary failure mode for this cycle.

- Focus on the worst-scoring case.
- Produce a testable hypothesis: "if [change], then [case N] should improve because [reason]."
- Do not attempt to fix multiple failure modes in one cycle.

### 5. Explore

Search for external evidence that can inform the mutation.

Explore is not optional decoration — it is the upstream supply system for Mutate.
Without evidence, mutations degrade to guesswork.

Sources (configured per project):
- Web search (papers, docs, community discussions)
- Skill hubs and public prompt repositories
- Local memory (past cycle logs, prior art)

Each retrieved item must be structured as an **Evidence Card**:

```
artifact        — the skill/prompt/pattern snippet or pointer
source_ref      — URL or internal reference (traceable)
hypothesis      — which failure mode it addresses
risk            — what side effects it might introduce
confidence      — estimated relevance (0-1)
```

### 6. Select

Filter evidence before it enters Mutate. Three gates:

- **Relevance**: directly addresses the diagnosed failure mode.
- **Executability**: can be expressed as a single mutation.
- **Verifiability**: effect is observable in the current corpus.

Reject evidence that fails any gate. Record rejections with reasons.

### 7. Mutate

Apply exactly one change to produce the next candidate.

The mutation operates on the structured `RichAgentDocument` via `patchAgent()`:

```
patchAgent(doc, { path, value }) → mutatedDoc (immutable)
```

Supported patch paths:
- `body` — the prompt text (most common mutation target)
- `model.temperature`, `model.name` — model configuration
- `extensions.*` — consumer-defined metadata (e.g. evolution state)

After patching:
1. **Validate** — `validateRichAgent(mutatedDoc, options?)` to confirm the mutation didn't break schema
2. **Serialize** — `serializeAgent(mutatedDoc)` to write back the updated `.agent.md`
3. **Record** — what changed, why, which evidence supported it

Constraints:
- The mutation must link to at least one Evidence Card (when Explore is enabled).
- Do not bundle unrelated improvements.
- One `patchAgent()` call per cycle.

### 8. Re-run

Re-dispatch the full corpus against the mutated candidate.

Same pipeline as Step 1:

```
mutated .agent.md → parse → validate → compose → dispatch N workers
```

Same isolation rules apply. The re-run uses the serialized output from Step 7,
not an in-memory representation — ensuring the written `.agent.md` is the
source of truth for scoring.

### 9. Decide

Compare re-run results against the previous baseline.

Acceptance criteria are **project-level configuration**. Common patterns:
- Overall score improves.
- No single case regresses beyond a configured tolerance.
- All hard-check constraints still pass.

If accepted: new candidate becomes base
````

## File: README.md
upstream: https://github.com/erergb/hacker/blob/HEAD/README.md

````text
# Hacker

> **Define a problem. Aggregate all best practices. Hack it.**

Drop this skill into Cursor. Your agent diagnoses prompt failures, searches the world for fixes, and applies them one at a time — with full regression protection. No guesswork.

---

A developer spends two hours tuning a support-ticket classifier prompt. It works on three test cases. They deploy. A customer sends an all-caps complaint — the prompt classifies "URGENT BUG FIX" as positive feedback. They add a rule: *"ignore all-caps text."* Next morning, normal acronyms (API, HTTP, SQL) are being ignored too. Three old cases silently regressed. They didn't know, because they only re-tested the new case.

This is what prompt engineering looks like without a regression gate. Every fix is a blind bet. You can't prove version B is better than version A — you can only hope nothing broke.

### What changes

The developer writes 8 test cases with expected outputs — including the all-caps edge case — and tells the agent:

> *"Run hacker against my classifier using corpus.md"*

They walk away. When they come back, the scratchpad reads:

```
Cycle 3  ACCEPT  avg 6.2 → 7.1
  diagnosis: T4 false positive — all-caps acronyms treated as noise
  explored:  arxiv.org/abs/2301.xxxxx — case-folding preserves acronyms
  mutation:  replaced "ignore caps" with Unicode category filter
  regressed: none

Cycle 5  ACCEPT  avg 7.1 → 7.8
  diagnosis: T2 missed implicit complaint ("this is ridiculous")
  explored:  lobehub.com/skill/sentiment-boundary — negative-example pattern
  mutation:  added implicit-negative examples from public skill
  regressed: none

Cycle 8  ACCEPT  avg 7.8 → 8.0
  diagnosis: no case below 6.0 — entering pruning
  mutation:  deleted rule with no measurable effect across 3 epochs
  result:    prompt 18% shorter, same scores
```

They didn't write a single new rule. The agent diagnosed each failure, searched for evidence-backed solutions — a paper, a public skill, a community pattern — and applied them one cut at a time. Every change has a source URL, a hypothesis, and a before/after score.

This README was itself written using Hacker's methodology — 7 cycles of scoring against [NDD](https://github.com/nicobailey/narrative-driven-development) narrative dimensions, with evidence-sourced mutations and accept/rollback gates. The [evolution log](.cursor/hacker-narrative-evolution.md) is in this repo.

Built for the [Magpie](https://github.com/nicobailey/magpie) agent pipeline, where it evolves sub-agent prompts in production.

```
  [Define]                    [Aggregate]              [Hack]
      ↓                            ↓                      ↓
 Corpus + Labels ──▶ Score ──▶ Diagnose ──▶ Explore ──▶ Mutate ──▶ Re-run
                                                                      ↓
                                                              accept / rollback
```

---

## Try It

```bash
# Drop the skill into your project
cp -r hacker/ .cursor/skills/hacker/

# Or clone globally
git clone https://github.com/ERerGB/hacker.git ~/.cursor/skills/hacker
```

Then tell your agent:

> *"Run hacker against my support_bot.md using corpus.md"*

It enters an optimization loop — diagnose, explore, mutate, verify — and logs every decision to a scratchpad you can audit after.

**Continuous runs**: Hacker does not bundle a loop driver. Pair it with your environment's re-invocation mechanism (e.g. Cursor Ralph Loop on `.cursor/ralph/scratchpad.md`, Claude Code's loop, or a shell wrapper) so each automated turn executes **one** full Hacker cycle. See [SKILL.md — Integration with Iterative Loop Runners](SKILL.md#integration-with-iterative-loop-runners).

---

## The Cycle (10 Steps)

| Step | Phase | What happens |
|------|-------|-------------|
| 1 | **Run** | Dispatch corpus to isolated workers |
| 2 | **Verify** | Confirm worker isolation |
| 3 | **Score** | Compare outputs to golden labels |
| 4 | **Diagnose** | Identify the single worst failure mode |
| 5 | **Explore** | Search external evidence (web, skill hubs, memory) |
| 6 | **Select** | Filter evidence by relevance, executability, verifiability |
| 7 | **Mutate** | Apply one evidence-backed change |
| 8 | **Re-run** | Full corpus re-dispatch |
| 9 | **Decide** | Accept if improved, rollback if regressed |
| 10 | **Log** | Record hypothesis, evidence, result, lesson |

See [SKILL.md](SKILL.md) for the full executable protocol.

---

## Configuration — Not Policy

Hacker's core is an abstract optimization loop. Concrete policies — scoring dimensions, stage gates, mutation operators, thresholds — are **project-level configuration**, not baked into the skill.

You configure:
- **Evaluation**: dimensions, weights, hard checks
- **Explore**: search providers, budget, evidence schema
- **Mutation**: available operators, evidence linking requirements
- **Acceptance**: gate thresholds, regression tolerance
- **Stages**: optional phased curriculum (e.g., recall → precision → quality → pruning)

See [references/config-schema.ts](references/config-schema.ts) for the TypeScript interface. It re-exports types and APIs from [`subagent-harness`](https://www.npmjs.com/package/subagent-harness) (`^0.4.0`) so prompts stay aligned with the published package.

```bash
cd hacker && pnpm install   # or npm install
pnpm run typecheck
```

Default profiles are provided as **examples**:
- [references/stages.md](references/stages.md) — a 5-stage curriculum
- [references/mutations.md](references/mutations.md) — a 9-operator mutation menu

### Composable sub-skills (for non-`.agent.md` candidates)

If your candidate is a SKILL.md section, a config file, or anything scored by a script (not subagent-harness workers), use the extracted references directly:

- [references/hacker-core.md](references/hacker-core.md) — 5-step cycle contract (no subagent-harness dependency)
- [references/hacker-loop.md](references/hacker-loop.md) — Claude Code Agent template, Cursor Ralph, CI drivers

---

## Inspired By

| Source | What we adapted |
|--------|-----------------|
| [Promptbreeder](https://arxiv.org/abs/2309.16797) (DeepMind) | Evolutionary prompt mutation via LLM |
| [EvoSkill](https://arxiv.org/abs/2603.02766) | Failure-driven skill discovery, Pareto selection |
| [Opus Self-Evolving Agent](https://dev.to/stefan_nitu/32-more-generations-my-self-evolving-ai-agent-learned-to-delete-its-own-code-18bp) | Reflexion, pruning as evolution |
| [Genetic Prompt Programming](https://github.com/stack-research/genetic-prompt-programming) | Enumerated mutation operators |

*The difference: those are research frameworks. This is a skill file you drop into your project and start using in 5 minutes.*

---

## What's Next

Hacker is actively evolving (using its own methodology, naturally):

- **Structured candidates** — `.agent.md` format via [subagent-harness](https://github.com/ERerGB/subagent-harness) for parse → mutate → serialize round-trips
- **Evidence sourcing** — SkillRank integration to search skill hubs during the Explore phase
- **Pareto frontier** — maintain multiple non-dominated prompt versions instead of a single best

**Try it on your own prompt and [share your scratchpad log](https://github.com/ERerGB/hacker/issues).** The best way to understand Hacker is to watch it think — and the best way to improve it is more real-world evolution logs.

## License

MIT
````
