| name | agent-feedback |
| description | Use when an agent hits friction, confusion, a bug, or a fleet-policy misalignment they cannot resolve from existing docs. Appends a structured entry to AGENT_FEEDBACK.md (per repo) for owner triage and conversion into fleet directives. Outbound-to-fleet channel; counterpart to agent-inbox (inbound handoffs) and fleet-enforce (compliance directives). Replaces the ad-hoc 'agent complains verbally' channel with a durable, auditable surface. |
Agent Feedback
The recognised channel for agents to surface friction, confusion,
bugs, misalignments, and proposals back to fleet policy without
stalling, bypassing guardrails, or going silent.
Authority: judgment://agent-synthesis (the
framework-refresh-lightweight-ceremony Decision);
file://spec-bundle/templates/workpads/AGENT_FEEDBACK.template.md.
When to use
Invoke when ANY of:
- The framework slowed you down disproportionately to safety value
(friction).
- Docs / skills / workflows / hooks pointed in contradictory
directions (confusion).
- A hook / lint / audit script gave a wrong answer (bug).
- A fleet rule conflicts with another fleet rule, OR a child-repo
doc contradicts the canonical at the source policy repo's
agents/ directory (misalignment).
- You have a concrete idea worth considering for fleet rule change
(proposal).
Do NOT use for:
- Bug reports against product code (file in the product repo's
issue tracker).
- Disagreements about owner-set decisions (raise directly with
owner; the owner's authority is not subject to agent feedback).
- Routine completion reports (those belong in SPEC §17 Completion
Reports).
Procedure
- Locate
AGENT_FEEDBACK.md at repo root. If absent, create it
from file://spec-bundle/templates/workpads/AGENT_FEEDBACK.template.md.
- Append a new entry at the top of the
## Entries section using
the template's ## YYYY-MM-DD HH:MM heading format.
- Fill every required section: Context, What happened, What I
expected, Why this matters. Suggested fix is optional.
- Status defaults to
surfaced (initial).
- Stage and commit the entry. Commit message:
docs(feedback): <agent-id> reports <type>: <one-line summary>.
Do not block your current session waiting for triage. File the
feedback, work around the friction if possible, and continue. If
the friction is a hard blocker, also set the relevant SPEC or
TASK.md status to blocked with a file:// reference to the
feedback entry.
Triage (fleet-side)
The agent attached to your-policy-repo is responsible for
periodic triage:
- Scan all 9 fleet locations'
AGENT_FEEDBACK.md for entries with
status surfaced.
- For each entry, classify and act:
- misalignment → issue a fleet directive via
file://spec-bundle/skills/fleet-enforce/SKILL.md.
- bug → file a fast-path SPEC or full task SPEC depending
on scope.
- friction → batch with similar entries; owner-decided
whether to amend procedure.
- proposal → forward to owner; if owner approves, becomes a
Decision or Contract SPEC.
- confusion → fix the upstream doc directly via fast-path or
fleet-enforce directive.
- Update each entry's Status section in place with a status-line
citing the your-policy-repo commit that resolves it.
Hard rules
- Agents MUST NOT delete or edit prior
AGENT_FEEDBACK.md
entries. Updates append below the original entry.
- Owner alone closes entries as
won't-fix.
- Feedback citing facts (lint output, hook behaviour, file
contents) MUST use the citation grammar from
file://spec-bundle/schema/SPEC.schema.md §2.
- Agents MUST NOT include secrets, credentials, or third-party
private content in feedback entries.
- Agents MUST NOT use this channel to bypass owner authority on
approved/decomposed/closed status transitions.
