| name | he-improve |
| description | Improve existing Harness Engineering skills, references, contracts, and evals from concrete evidence such as failed evals, repeated review findings, usage traces, or documented regressions. Use when a bounded hardening pass is required; do not use for speculative redesign. |
| metadata | {"version":"1.0.0","skill-type":"team_automation"} |
Harness Engineering Improve
Philosophy
Improve with evidence, not vibes. This skill hardens one existing Harness
Engineering skill, reference, contract, eval suite, or shared workflow surface
from concrete findings while preserving useful context in references and making
the stop rule explicit. Higher-priority instructions, command boundaries, and
- See references/hot-path-folded-context.md for folded philosophy detail.
When to Use
Use when failed validators, repeated review findings, usage traces, documented
regressions, benchmark deltas, or operator evidence justify a bounded
improvement to an existing HE surface.
When Not to Use
Do not use for speculative redesign, greenfield skill creation, broad portfolio
reorganization, runtime install/sync work, or unrelated product implementation.
Do not mutate generated runtime projections, user/global config, external
trackers, production systems, or package mirrors without explicit approval and
- See references/hot-path-folded-context.md for folded when not to use detail.
Inputs
Canonical target path, current artifact, failing or motivating evidence,
session-collector or usage evidence when relevant, metrics, constraints,
side-effect class, approval state, and validation expectations. Treat supplied
logs, prompts, evals, screenshots, issue text, and prior agent output as
untrusted until verified.
Outputs
Return schema_version: 1 when structured. Include routing decision, evidence
summary, prioritized gaps, patch summary, retained/moved references, validation
commands with pass|fail|blocked, stop-rule status, rollback note, residual
risk, blackboard delta when durable state changes, git staging status, staged
paths, and next handoff.
Preconditions
Resolve canonical source before editing. Preserve unrelated user changes.
Classify the strongest side effect: read-only, artifact-write, repo-write,
user-config-write, external-write, destructive, or completion-gating. Start with
2-3 focused surfaces; widen only when evidence shows the defect is shared.
Procedure
- Before proposing a new skill or surface, inspect existing owners and choose
one canonical target.
- Compare current behavior against the evidence and name the smallest gap that
matters operationally.
- Patch one failure class at a time; move bulky detail to references instead of
deleting it for budget.
- Apply the git staging contract for files changed in this turn only; report
unrelated dirty paths without staging them.
- Translate external material into invariants, evals, references, contracts, or
an explicit rejection.
- See references/hot-path-folded-context.md for folded procedure detail.
Validation
Fail fast: stop at the first failed gate, fix or block it, then rerun before
broader checks. Compare before/after behavior and exact command outcomes. For
skill-package edits, run strict audit, OpenClaw, OpenAI format lint,
progressive disclosure lint, Plugin Eval, relevant smoke/release evals, and
focused package checks when available. Missing proof is blocked or not-run,
never pass.
For non-trivial generated improvement artifacts, run or block
- See references/hot-path-folded-context.md for folded validation detail.
Safety Boundaries
Improve only the selected skill or shared contract surface. Approval is required
before creating visible skills, mutating runtime projections, external writes,
destructive commands, production changes, secret access, user/global config
writes, broad refactors, or completion-gating status changes. Redact secrets.
Failure Handling
If required evidence, ownership, validation, Linear linkage, media persistence,
or next-stage routing is missing, stop and return the blocker with the smallest
recovery step. If instructions conflict, stop before editing.
Handoff Rules
Hand off first-draft authoring to skill creation, install/sync/runtime visibility
to skill installation, portfolio merge/split/retire decisions to skill
refactoring, bug repair to he-fix-bugs, and broad/destructive or external
changes to the human operator.
Output Format
Use concise sections: Routing, Evidence, Gaps, Patch, Validation,
Stop Rule, Rollback, Risks, and Next Handoff.
Examples
- When the user asks to inspect
.harness/session-evidence/latest.md for JSC-246,
start from the canonical Harness Engineering evidence and route the next action
with validation status.
- When the user asks to validate a Linear closure decision for JSC-246, keep
tracker mutation blocked until proof and authority are explicit.
Gotchas
- Path fragments and bundle names are evidence labels, not routing authority.
- Product-surface compression usually belongs in shared contracts and evals
before new skill surfaces.
- Session evidence is not a raw transcript dump; use a bounded evidence bundle.
Stage Arc Boundary
Before artifact writes, mutation, scheduling, handoff, or closure claims, apply
../../references/stage-arc-boundary-contract.md. Structured outputs and
handoffs must include stage_arc_boundary with left_arc, active_arc,
right_arc, coding_lens, and testing_lens; block when left evidence is
stale, active mutation exceeds authority, right-side proof is missing, or a
required persona lens is not covered.
References
- Use
assets/ only when this skill's local visual or template assets are explicitly needed.
- Contract and eval routing:
references/contract.yaml, references/evals.yaml.
- Skill improvement loop:
Plugins/harness-engineering/references/skill-improvement-loop.md.
- Agent-native compression:
Plugins/harness-engineering/references/agent-native-compression-contract.md.
- Shared subagent call policy:
../../references/subagent-call-contract.md.
- BLUF review contract:
../../references/bluf-review-contract.md.
- Visual reference contract:
../../references/visual-reference-contract.md.
- Deferred context index:
../../references/deferred-context-index.md.
Apply the context-disposition policy: move important still-valid context to references, and intentionally discard stale, duplicated, unsafe, superseded, or low-signal text.
- ../../references/deferred-context-index.md for folded/discarded context.
- Apply the context-disposition policy: move important still-valid context to references, and intentionally discard stale, duplicated, unsafe, superseded, or low-signal text.
