Agent Experience Audit

UNOFFICIAL/EXPERIMENTAL

This audit records the documentation decision for helm-expt: keep the public website and human docs readable, and put agent/operator instructions in repo Markdown.

Scope

Audited surfaces:

• README.md
• docs/README.md
• docs/user/README.md
• docs/user/verification.md
• docs/user/choosing-commands.md
• docs/user/helm-render-intents.md
• tests/npm-scripts.md
• data/README.md
• data/helm-render-intents/summary.md
• knowledge/wiki/agent-operating-guide.md
• scripts/verify-doc-map.mjs

Out of scope for this pass:

• generated catalog pages;
• generated chart pages;
• catalog data redesign;
• live proof reruns.

Findings

Keep Human Pages For Humans

The public website and docs/user pages should explain the product and the user tasks. Agent command routing belongs elsewhere because it repeats material already present in tests/npm-scripts.md and the generated data index.

Decision: keep detailed agent instructions out of website pages and do not add agent sections to the catalog. The website may include a Docs/FAQ link to docs/agent/README.md.

Agents need a deterministic start point

The repo already has the needed material, but it is spread across several places:

• docs/README.md maps manual docs;
• tests/npm-scripts.md maps npm commands;
• data/README.md maps generated evidence;
• docs/user/verification.md explains proof concepts;
• knowledge/wiki/agent-operating-guide.md gives older high-level rules.

Decision: add docs/agent/README.md as the start page and link from there to the human docs, generated data, and command lists.

Generated evidence is too large for cold starts

data/, recipes/, packages/, and site/charts/ are large. Agents that open them directly can lose the thread and overclaim from one row.

Decision: add a read-only catalog guide that tells agents which generated files to read first and which files not to edit.

Verifier choice is the main operational risk

The repo has many npm scripts. The main operational risks are running a broad gate when a narrow verifier would do, running live evidence by accident, or treating a product command as a proof command.

Decision: add task recipes, recovery rules, and a verification command map under docs/agent/.

Existing doc verifier must allow the new layer

scripts/verify-doc-map.mjs intentionally rejects unexpected Markdown locations. Adding docs/agent requires updating that allowlist and assigning each agent doc a role in docs/README.md.

Decision: update the verifier for docs/agent/*.md and document every new file in docs/README.md.

Implemented In This Pass

• Added docs/agent/README.md.
• Added docs/agent/tasks.md.
• Added docs/agent/recovery.md.
• Added docs/agent/verification.md.
• Added docs/agent/catalog.md.
• Added docs/agent/human-agent-doctrine.md.
• Added docs/agent/terms.md.
• Added this audit.
• Added an agent-experience worklog.
• Updated the Markdown verifier to allow docs/agent.
• Linked the agent docs from repo Markdown and from Docs/FAQ on the website.

Future Work

• Improve common verifier failure messages so each one prints the recovery command directly.
• Add a docs lint check for ambiguous public claims and stale command examples.
• Keep recording real agent mistakes in the worklog.
• Revisit catalog AX later as a separate project if agents still struggle after the repo Markdown layer is in place.