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

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 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. 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:

// 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:

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:

await refine.run(rollbackId="refine_20240512_1234")

Invoke the low‑level API directly for custom orchestration:

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 — 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 — Public exports and entry points consumed by the daemon and skill wrappers.

• 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 — 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}