improve-harness

---
name: improve-harness
description: Use only when the user explicitly invokes `$improve-harness`. Test one authorized improvement to repository guidance or capabilities against an observed baseline and a fresh rerun. Do not infer permission from ordinary work or automatically reflect after tasks.
---

# Improve Harness

Improve one bounded future-agent behavior without turning every difficult task
into permanent process. Keep consumer truth with its owner and require a fresh
rerun before claiming improvement.

## Establish Authority

- Read `AGENTS.md`, `docs/WORKFLOW.md`, and applicable local instructions.
- Confirm the request authorizes changing Harness behavior. Inspection or a
  request to report friction does not authorize edits.
- Record the initial repository root, revision, branch, status, and unrelated
  changes. Preserve all existing work.
- Treat invocation as authority for this bounded experiment, not for changing
  product policy, weakening proof, adding credentials, or mutating external
  systems.

## 1. Preserve The Baseline

Use an observed task trajectory when available. Record:

- the representative job and accepted outcome;
- the concrete failure and evidence;
- human steering, relay, or recovery required;
- the worker, repository revision, relevant external state, tools, and
  authority; and
- existing proof and known limitations.

Do not diagnose a worker limitation from one run. If no observed baseline
exists, stop with an experiment proposal; do not manufacture one.

Copy `docs/templates/harness-improvement.md` to
`docs/plans/active/harness-improvement-<slug>.md`. Reuse an existing active
record for the same experiment.

## 2. Locate The Earliest Gap

Trace the failure upstream to the first owner that could have prevented or
exposed it:

- **Context:** knowledge was absent, stale, overloaded, or not retrieved.
- **Capability:** discovery, invocation, interpretation, repair, or real-system
  verification failed.
- **Domain ownership:** no canonical type, API, state machine, or source owned
  the invariant.
- **Authority:** permission, approval, audit, or recovery was unclear.
- **Proof:** checks established a proxy rather than the accepted outcome.
- **Environment:** an external prerequisite was unavailable.

Assign the correction to `repository-harness`, the consumer repository, the
external environment, or a human decision. Do not copy consumer commands or
policy into a generic upstream template.

## 3. State And Apply One Intervention

Before editing, write:

```text
If <smallest change> is added at <owner>, then a fresh agent will
<observable change> on <representative job>, because <mechanism>.
Evidence that would weaken this:
Maintenance owner and removal condition:
```

Make only the authorized intervention. Prefer an existing owner, a clearer
route, an actionable diagnostic, a runbook fact, a type or API, or
claim-matched proof over a parallel framework. Keep unknown policy unknown.
Run repository-native checks that protect the changed boundary.

## 4. Require A Fresh Rerun

Use a fresh agent session and an equivalent starting state. Hold the worker,
task class, authority, tools, and relevant external conditions materially
steady. Record separately whether the intervention was available, retrieved or
invoked, and relevant.

If a fresh rerun is not authorized or available, leave the record active with
`Decision: pending fresh rerun`. Report the exact next task; do not claim the
Harness improved.

## 5. Keep, Revise, Or Remove

Compare accepted outcome, claim-matched proof, human intervention, retries,
authority behavior, and maintenance cost.

- **Keep** when the rerun exercised the intervention and improved the bounded
  job enough to justify its cost.
- **Revise** when the owner is correct but the route or interface remains hard
  to use.
- **Remove** when it adds noise, duplicates a better owner, or does not improve
  the job.

Record the decision, evidence, owner, and removal condition. Move the record to
`docs/plans/completed/` only after native validation and the fresh-rerun
decision. Preserve a removed intervention's result in the completed record.

## Report

Return:

- representative job and baseline;
- earliest gap and owner;
- intervention and changed files;
- native validation;
- fresh-rerun status and comparison;
- `keep`, `revise`, `remove`, or `pending fresh rerun`; and
- remaining authority, risk, or follow-up.

More agent context in hoangnb24/harness-experimental

6 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• hoangnb24/repository-harness1.2k