harness-refresh

/harness refresh

Refresh a target repository's existing harness by reviewing whether its agent-facing rules, knowledge store, and drift checks are still accurate.

Harness Refresh is maintenance for the target harness. It does not refresh the local ./harness-starter-kit reference clone and does not replace /harness update.

Goal

Inspect the target repository's current harness, classify stale or conflicting artifacts, apply only safe documentation/check updates, and finish with a clear Harness Refresh Report.

Use this command when the maintainer wants to reduce old guidance, duplicate records, obsolete failure notes, stale decisions, or unused harness checks.

Procedure

1. Treat the current working directory as the target repository root.
2. Inspect target repository state before changing files:
   • git status --short --branch
   • AGENTS.md, CLAUDE.md, README files, contribution docs, and CI configs
   • .harness/source.json, if present
   • docs/decisions/, docs/failures/, docs/conventions/, and docs/domain/
   • scripts/check_*.py, scripts/check_harness.py, package scripts, test configs, lint configs, and pre-commit config
3. Build a short inventory of harness artifacts and classify each relevant item:
   • keep: still accurate and useful.
   • update: useful but stale, incomplete, or unclear.
   • merge: duplicate or overlapping guidance that should be consolidated.
   • archive/delete candidate: likely obsolete or unused, but not removed without explicit user approval.
   • manual review: needs a maintainer decision because it changes workflow, CI, dependencies, architecture rules, or historical records.
4. Check for:
   • stale docs that reference missing commands, paths, or tools
   • duplicated guidance split across AGENTS.md, README files, and docs
   • obsolete decisions or failure records contradicted by current code
   • harness checks that no normal command, CI workflow, or documentation uses
   • deterministic, local, non-network, reasonably fast checks for product behavior that agents are expected to verify repeatedly, but are not included in the documented normal completion gate and have no recorded reason for remaining focused or manual
   • rules that describe architecture constraints no check or review point can enforce
5. For large docs directories, list files first and read only records relevant to the refresh question, stale/conflict signals, or current harness rules.
6. Patch only safe, target-specific updates that preserve the repository's current architecture, tools, commands, and documentation style.
7. Prefer marking decision and failure records as superseded or obsolete over deleting them. If a replacement record is clearer, add or update the replacement and cross-reference the old record.
8. Do not delete, archive, move, or wholesale replace files unless the user explicitly approves the specific files after seeing the candidates.
9. Run relevant local checks, such as docs drift, structure drift, effectiveness plan checks, project tests, linting, type checks, or /harness doctor.