# How the `/refine` Command Enhances Harness State with Evidence‑Backed Updates

> Learn how the /refine command enhances Harness state with evidence-backed updates by transforming session observations into versioned edits of prompt notes, memories, and skills.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: deep-dive
- Published: 2026-08-12

---

**The `/refine` command transforms session observations into versioned, evidence‑driven edits of the continual harness—the persistent store of prompt notes, memories, skills, and sub‑agent specifications—by prompting an LLM with hard evidence from the conversation trajectory, current harness overview, and refinement history.**

The `/refine` command sits at the core of how Prime Agent learns from experience. Unlike generic state updates, this mechanism ensures every modification to the harness is grounded in concrete observations from the current or past sessions. This article breaks down the three‑stage pipeline that makes evidence‑backed refinement possible in the PrimeIntellect‑ai/prime‑agent repository.

## Stages of the `/refine` Pipeline

The refinement engine operates in three tightly‑coupled stages. Each stage is implemented in [`packages/coding-agent/src/core/refinement/refinement.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/refinement/refinement.ts) and contributes to the guarantee that no edit enters the harness without supporting evidence.

### Stage 1: Gathering Context and Building the Prompt

The `planRefinement` function constructs the evidence package that the LLM will use to propose edits.

- **Current harness overview**: Retrieved via `overviewForPrompt` to show the existing state of prompts, memories, and skills.
- **Full refinement history**: Loaded through `historyForPrompt` to expose what has already been learned and when.
- **Recent conversation slice**: A truncated window of `AgentMessage[]` providing the raw observations that justify new refinements.
- **Optional user instruction**: Allows operators to steer the refinement with explicit guidance.

These four sources are concatenated into a compact prompt at lines 8644–8650 of [`refinement.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/refinement.ts). The prompt contains **hard evidence**—not summaries, but actual message content and state snapshots—that constrains the LLM to propose only justified changes.

### Stage 2: LLM‑Generated Proposal

With the evidence assembled, the pipeline sends the `REFINEMENT_SYSTEM_PROMPT` to the configured model. This system prompt defines:

- The refinement task objective
- Allowed edit shapes: **create**, **update**, **delete**
- Required fields: `rationale`, `expectedOutcome`, and the structured edit description

The LLM returns a JSON blob describing one or more edits. The pipeline extracts this JSON robustly:

```typescript
// From refinement.ts L8614-L8643
const raw = await model.complete(prompt, { system: REFINEMENT_SYSTEM_PROMPT });
const json = extractJsonObject(raw);      // tolerates markdown fences
const proposal = parseProposal(json);     // validates schema

```

This extraction layer ensures malformed responses do not crash the pipeline; instead, they surface as parseable errors in the `RefinementResult`.

### Stage 3: Validation, Application, and Recording

The `applyRefinementProposal` function (lines 715–784) executes the evidence‑backed edit plan:

1. **Validation**: Each edit passes through `validateEdit` to check target existence, type consistency, and scope constraints.
2. **Concurrency check**: Detects if the harness state has drifted since the proposal was generated.
3. **Mutation**: Applies valid edits to the in‑memory `HarnessState`.
4. **Persistence**: Writes a new `HarnessEntry` with proper versioning, timestamps, and scope (`global` or `local`).
5. **Event logging**: Appends a `HarnessRefinementEvent` to `state.refinements` for full auditability.

The function returns a `RefinementResult` containing:

- `appliedEdits`: The subset of proposals that succeeded
- `evidence`: References to the trajectory slice and prompts used
- `newHarnessLocation`: Path to the serialized updated state

## Scope Control: Global vs. Local Edits

The `/refine` command respects **scope boundaries** that prevent pollution of the global harness:

| Scope | Behavior | Typical Use Case |
|-------|----------|----------------|
| `local` | Edits persist only for the current session | One‑off fixes, experimental skill drafts |
| `global` | Edits become available across all future sessions | Reusable patterns, stable tool wrappers, enduring sub‑agent specifications |

Only evidence demonstrating **cross‑session value**—such as a delegation pattern appearing three times—justifies a global refinement. The `options.global` flag in the low‑level API enforces this boundary.

## Executing `/refine`: Practical Examples

Trigger refinement interactively after observing a repeated failure:

```python
await refine.run(instructions="The tool keeps failing to create a file; capture this as a reusable skill.")

```

Roll back a faulty refinement using its traceable identifier:

```python
await refine.run(rollbackId="refine_20240512_1234")

```

Invoke the low‑level API directly for custom orchestration:

```typescript
import { refineHarness } from "prime-agent/coding-agent/src/core/refinement/refinement.js";

const result = await refineHarness(
  messages,                     // AgentMessage[] slice from recent turns
  loadHarnessState(),           // current HarnessState snapshot
  getRefinementHistory(...),    // prior RefinementResult[] for context
  model,                        // Model instance (e.g., GPT‑4, Claude)
  apiKey,                       // provider API key
  { global: false }             // scope: local session only
);

console.log(result.appliedEdits.length, "edits applied");
console.log(result.refinements[0].evidence.trajectorySlice.length, "messages of evidence");

```

## Key Source Files

Understanding the implementation requires familiarity with these locations in the PrimeIntellect‑ai/prime‑agent repository:

- **[`packages/coding-agent/src/core/refinement/refinement.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/refinement/refinement.ts)** — Core pipeline: `planRefinement`, LLM call with `REFINEMENT_SYSTEM_PROMPT`, `extractJsonObject`/`parseProposal`, and `applyRefinementProposal` with validation and state mutation.

- **[`packages/coding-agent/src/core/refinement/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/refinement/index.ts)** — Public exports and entry points consumed by the daemon and skill wrappers.

- **[`packages/coding-agent/test/refinement.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/refinement.test.ts)** — Test coverage for evidence‑backed edits, rollback behavior, and scope enforcement.

- **[`packages/coding-agent/src/core/refinement/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/refinement/utils.ts)** — Helper functions `overviewForPrompt` and `historyForPrompt` that serialize harness state and refinement history for LLM consumption.

## Summary

- The `/refine` command converts raw session observations into versioned harness edits through a three‑stage pipeline.
- **Evidence is mandatory**: The LLM receives the actual trajectory, current state, and history—not summaries—ensuring every proposal is traceable to concrete observations.
- Validation and scope controls prevent uncontrolled growth of the harness; only durable patterns earn global scope.
- Full auditability is provided through `HarnessRefinementEvent` logging and `RefinementResult` return values.
- The implementation resides primarily in [`packages/coding-agent/src/core/refinement/refinement.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/refinement/refinement.ts), with clear separation between prompt construction, proposal generation, and state application.

## Frequently Asked Questions

### What happens if the LLM proposes an invalid edit?

The `validateEdit` function rejects malformed proposals before any state mutation occurs. Invalid edits are excluded from `result.appliedEdits` and logged with failure reasons. The remaining valid edits in the same proposal still apply, so partial success is supported.

### Can `/refine` undo changes made by a previous refinement?

Yes. The `rollbackId` parameter accepts a refinement identifier from a prior `RefinementResult`. The rollback mechanism consults the `refinements` list in `HarnessState` to reconstruct and invert the applied edits, restoring earlier versions of affected entries.

### How does the system prevent the harness from growing without bound?

Scope enforcement (`local` vs. `global`) and explicit human operator review for global refinements act as rate limiters. Additionally, the `historyForPrompt` mechanism includes timestamps and success metrics, allowing the LLM to propose deletions of obsolete entries when evidence shows a skill or note is no longer relevant.

### Where is the evidence for an edit stored after refinement completes?

Each `HarnessRefinementEvent` recorded in `state.refinements` contains an `evidence` field with references to the trajectory slice message IDs, the prompt used, and the raw LLM response. This enables full reconstruction of why any edit was made.