harness-feedback

Harness Feedback Loop

When friction is discovered during harness usage — a hook that didn't fire, guidance that was contradictory, a mandate violated in practice, or tool output diverging from documentation — capture and escalate it by default. The goal is to ensure harness improvements flow upstream without requiring users to notice and report them manually.

Procedure

1. Address the immediate problem

Work around or fix the specific friction blocking your session — do not defer this step or leave it for later. Examples:

• A hook expected to run but didn't? Inspect core.hooksPath, check hook file permissions, run it manually if necessary.
• Guidance was unclear? Disambiguate it by reading related docs or asking for clarification.
• A mandate was hard to apply? Document what made it hard and propose a better framing.

2. Log it locally

Append a dated entry to docs/operational/harness-feedback.md (create it with a short header if it doesn't exist). Use this template:

## [ISO 8601 date] – [one-line summary]

**Recurrence key:** `[stable-kebab-case-slug]`

**Harness version:** [commit SHA or tag of the harness in use]

**What happened:** [The friction event and when you noticed it]

**Root cause:** [Why did this happen? What in the harness design or docs caused it?]

**Impact:** [How did it affect your session or workflow?]

**What agentharness should change:** [Concrete recommendation — a new check, clearer guidance, a new tool, a code fix, etc.]

**Corrective action taken:** [What you did to work around or fix it] Logged upstream as #[issue-number] — or "Not filed upstream (opted out via .agentharness-no-upstream-feedback)".

Optional structured fields. Add any of these when you actually have the information — none are mandatory, and a one-off entry with just the fields above is still a complete, valid entry:

**Event class:** [hook-failure | ambiguous-guidance | mandate-violation | tool-output-mismatch | other]

**Observed vs. inferred:** [Directly observed (you saw the failure happen) or Inferred (you're reasoning from symptoms without a direct repro)]

**Evidence reference:** [Link or path to the transcript, log, or command output that shows this — not the raw content, a pointer to it]

**Severity:** [blocking | degraded | cosmetic]

**Workaround:** [What let the session continue despite the friction, if anything]

**Resolution:** [Fixed upstream in #N | Still open | Won't-fix, because ...]