Known Agent Issues Need A Register, Not A Vague Optimization Note
Production Agents can have known issues. The dangerous part is writing "needs optimization" and letting everyone work around the issue from memory. One field sometimes needs manual correction. One source causes artifact drift. One downstream user cannot use the new format. Without a register, the same issue returns through repetitive investigation, slow communication, and time-consuming rework. An Agent known issue register turns "everyone knows" into a record the team can review, repair, and stop when needed.
The NIST AI Risk Management Framework emphasizes identifying, measuring, and managing risk. Anthropic's building effective agents also points to clear workflows and boundaries as a foundation for reliability. Axon's operating view is that a known issue does not always block Agent use, but it must name scope, workaround, and stop condition.
This article connects to Agent output drift review, Agent manual rework threshold, Agent rollback decision rule, and Agent user feedback loop. The register does not dramatize problems. It keeps them from spreading invisibly.
Not A Generic Bug List
An Agent known issue register should describe operating impact, not only a technical symptom.
| Field | What to write |
|---|---|
| issue scope | Which source, field, user, or Schedule is affected |
| affected artifact | Which part of the artifact may be unreliable |
| workaround | What the owner or reviewer does now |
| owner | Who repairs or reviews it |
| next review | When the issue is judged again |
| stop condition | What triggers pause, rollback, or narrower scope |
Without a stop condition, a known issue can become a permanent background risk.
A Clear Issue Record
Agent: weekly renewal summary
known_issue: renewal status may be stale when CRM export is delayed
scope: Monday run only, renewal status field
affected_artifact: risk reason and next action
workaround: owner checks export timestamp before accepting artifact
next_review: after 3 Monday runs
stop_condition: any rejected external-use artifact
This record tells the team where the issue lives and how the Agent can still be used. It is more useful than "source sometimes wrong."
Use Severity Instead Of All-Or-Nothing
Not every known issue should pause an Agent. Separate issues into three lanes:
- Watch: affects format or preference, not facts.
- Repair: affects a local field and needs owner review or workaround.
- Stop: affects facts, external use, downstream decision, or Trust Mode boundary.
The register is useful because it distinguishes controlled issues from issues that require stopping the workflow.
Watch issues can wait for the next maintenance window. Repair issues should enter a change request. Stop issues should trigger pause, rollback, or narrowed scope.
Make Issues Closeable
Many registers fail because issues never close. Each issue should name:
Step 1: what evidence proves the issue is gone.
Step 2: who reviews that evidence.
Step 3: whether scope narrows if repair misses the date.
Step 4: whether the runbook or release note must be updated.
This prevents the register from becoming a permanent footnote.
A useful register also separates temporary workaround from accepted operation. If the owner checks a source timestamp for three runs while a connector problem is being repaired, that is a workaround. It should have a review date and a stop condition. If the team decides the Agent will permanently exclude a source, the runbook and release note should change so users do not treat the exclusion as an unresolved issue. This distinction keeps the register honest.
When the register is reviewed, avoid debating every possible future failure. Look at evidence: repeated rework, rejected artifacts, missed Schedules, user feedback, and Trust Mode stops. A known issue stays open when evidence shows the risk is still active. It closes when the accepted artifact, source boundary, and user behavior prove that the problem no longer affects production use.
FAQ
Q1: Will an Agent known issue register make users less confident?
No, if scope and workaround are clear. Vague issues damage trust more than visible controlled ones.
Q2: Which issues must be registered?
Repeated issues, acceptance issues, downstream issues, source reliability issues, and Trust Mode issues should be registered.
Q3: Who records the issue?
Anyone can record it. The Agent owner confirms scope, owner, next review, and stop condition.
Q4: How is this different from feedback?
Feedback is an input signal. A known issue is a confirmed operating record with scope and control.
Q5: Should closed issues be kept?
Yes, especially when the issue affected external use, downstream work, or high-attention delivery.
Next Step
Start using Axon for production Agent issue management by writing one Agent known issue register entry for each repeated issue: scope, affected artifact, workaround, owner, next review, and stop condition. Learn more by replacing "needs optimization" with how the issue is controlled today.