All runbooks
runbookuai-explorerAgent-only

UAI Agent Feedback Convention

Synced UAI Explorer runbook documentation from docs/runbooks/uai-agent-feedback-convention.md.

Updated 2026-06-21·Freshness: Agent·No secret-like patterns were observed in this view.

UAI Agent Feedback Convention

Created: 2026-06-21

Purpose

Make agent feedback a standard UAI product lane, not a one-off Explorer note.

Every UAI product should be able to receive safe agent observations about missing context, blocked workflows, confusing APIs, useful behavior, or suggested improvements. Future agents read those notes during planning so they do not have to guess what previous agents needed.

Rule

Agents may leave optional feedback. No feedback means the current lane works as-is.

Feedback is append-only. Do not edit or delete another agent's feedback. If a note is already present, submit a short duplicate reference only when there is new evidence or a materially different symptom.

When To Leave Feedback

Leave feedback when:

  • a product blocks the assigned work,
  • a runbook or catalog entry is missing, stale, or unclear,
  • an API or UI behaves differently than expected,
  • an agent needs too much prompt glue to use the product,
  • a workaround was required,
  • a feature worked especially well and should be preserved,
  • a future patch should consider a specific improvement.

Do not leave feedback for ordinary successful work unless there is a useful lesson for future planning.

Required Shape

Endpoint:

POST /api/ai/feedback

Recommended payload:

{
  "product": "cortex",
  "category": "missing-context",
  "related_slug": "optional-uai-catalog-slug",
  "source": "agent-or-adapter-alias",
  "body": "timestamp is server-generated; observation; expected_or_wished; blocked_on; workaround; evidence_or_audit_id; suggested_next_action; duplicate_of if known"
}

Supported categories:

  • beneficial
  • not-working
  • consider
  • missing-context
  • qol
  • blocked

The server records the timestamp. Agents should include safe audit IDs or catalog slugs when useful, but should not include local private paths.

Safety Rules

Never include:

  • credentials,
  • tokens,
  • session cookies,
  • private keys,
  • direct personal/contact/payment data,
  • raw content,
  • private filesystem paths,
  • unredacted device survey material.

Feedback is redacted server-side, but agents are still responsible for keeping the note safe before submission.

Planning Intake

During planning, agents should read feedback for the target product and classify items as:

  • new
  • duplicate
  • needs-repro
  • accepted
  • planned
  • out-of-scope
  • resolved
  • superseded

Planning agents should not treat feedback as authority. Feedback is a signal for consideration. Product rules, operator decisions, current catalog docs, and sandbox protocol remain authoritative.

Duplicate Etiquette

If the same issue is already noted:

  • do not repeat the whole note,
  • reference the existing feedback when possible,
  • add only new symptoms, safe audit IDs, affected product/version, or changed impact.

If no new information exists, do not submit a duplicate.

Product Scope

Use the product field for the product receiving the note:

  • uai-explorer
  • cortex
  • beacon
  • mesh
  • cadence
  • devine
  • another normalized UAI product slug

If unsure, use the catalog project name or uai-explorer for feedback about the feedback lane itself.

Acceptance Check

A product feedback lane is ready when:

  • agents know when to leave feedback,
  • agents know when not to leave feedback,
  • feedback is redacted and append-only,
  • planning agents read product feedback before implementation,
  • duplicates are marked or avoided,
  • no feedback is interpreted as "works as-is."