AX: Context Retrospectives & Usability Audits

Each time an AI agent starts a session, it navigates your workspace for the first time - making every completed task a live usability test of your Agent Experience (AX). Instead of closing the chat window right after merging a pull request or finalizing a document, we can borrow a page from UX user interviews and agile sprint retros to debrief the session while the full transcript is still in memory. Below, we break down how to use the ax-retro skill to audit back-and-forth steering friction and convert those insights into permanent upgrades across your context files (like SKILL.md), tool schemas, and future prompts.

When to use this Skill

When an agent session reaches an accepted final output - such as generating a finalized PDF report and merging a pull request - trigger ax-retro before closing the active conversation thread. Because the session begins with your mounted grounding context (like Skills and system instructions) alongside an initial user message or work ticket, every back-and-forth exchange required to hammer out the final deliverable represents interface friction. Invoking this skill right after output acceptance audits that multi-turn iteration history to pinpoint what could have gone better across your available tools, initial grounding context, and upstream message or ticket clarity.

Three Ways to Capture AX Usability Telemetry

Depending on how your runtime is deployed, you can run an AX usability audit across three environments:

The 4-Bucket Triage Filter

To prevent overfitting one-off task details into global memory, the ax-retro skill routes every friction event into one of four buckets:

• Bucket 1 - Operating Charter (AGENTS.md / system_instruction.md): Global rules and formatting invariants that apply to 100% of future sessions.
• Bucket 2 - Interface Page Copy (SKILL.md): Domain heuristics, step-by-step sequences, and reference pointers that apply only to a specific repeatable workflow.
• Bucket 3 - Integration Surfaces (Tool Availability & Responses): Missing tools, ambiguous parameter schemas, or unhelpful API error responses that forced the agent to guess or loop.
• Bucket 4 - Upstream Task Spec (The Work Ticket / Initial Prompt): Missing acceptance criteria or scope boundaries that belong strictly to the single task just completed, output as a scorecard for the human author.

The ax-retro Skill (SKILL.md)

Drop this SKILL.md file into your workspace to run UX-style contextual inquiries on your agent sessions:

---
name: ax-retro
description: Process document for how to run a post-task Agent Experience (AX) retrospective and usability audit on the given conversation transcript. Mount this skill whenever a user requests a context refinement or a context retro after you've finished a task or asks to run a retro, refine workspace context, tool availability, or audit what their initial ticket or prompt missed.
---

# Skill: Post-Task AX Retrospective (`ax-retro`)

## Role & UX Inquiry Framing
Act as a Principal UX Researcher conducting a post-task contextual inquiry on this workspace interface. Treat the completed session as a usability test where the agent runtime was the participant navigating the user's information architecture (`AGENTS.md` or system instructions), page copy (SKILLs), interactive components (mounted tools and tool responses), and task brief (the initial ticket or prompt).

## Operational Sequence
Execute this two-step sequence:

1. **Stage 1: Usability Debrief & 4-Bucket Triage**
   * Reflect on the full conversation history (or provided OTel `session.id` trace logs) to pinpoint every turn where the participant hit interface friction: human course-corrections, rejected diffs,PR review comments, missing tool affordances, or noisy tool responses.
   * Classify each friction point using the **4-Bucket Triage Filter** below.
   * Render the **AX Usability Audit** and **Upstream Ticket Scorecard**, then ask the user which workspace patches to apply.
2. **Stage 2: Interface Patching**
   * If you are able to edit the workspace context directly, apply the approved updates to available context like `AGENTS.md`, `SKILL.md`, or local tool definitions so the user can review them in version control.
   * If you cannot edit files in this environment, output clean, copy-pasteable replacement blocks.

## The 4-Bucket Triage Filter & Guardrails
* **Anti-Overfitting Rule:** Keep single-task details out of persistent workspace files. Route all one-off task requirements strictly to Bucket 4.
* **Bucket 1: Global Navigation (`AGENTS.md` / Operating Charter):** Route friction here only when a missing rule applies to every future session in the workspace.
* **Bucket 2: Page Copy & Wayfinding (`SKILL.md`):** Route friction here when a repeatable workflow lacked clear sequencing, domain rules, or reference pointers. Keep `SKILL.md` files under 500 lines.
* **Bucket 3: Interactive Affordances (Tool Availability & Responses):** Route friction here when a needed tool was missing, a parameter description was ambiguous, or a tool response returned unhelpful error text or excessive token noise.
* **Bucket 4: Task Brief (Upstream Ticket / Initial Prompt):** Route friction here when the human's initial prompt or work ticket omitted target files, edge cases, or acceptance criteria.
* **Condition-First Microcopy:** Phrase all proposed rules using positive, condition-first directives (`"When X occurs, require Y"`) rather than negative prohibitions.

## Stage 1 Output Template

### 1. AX Usability & Context Triage
| Label | Turn / Friction Event | UX Failure Mode (Root Cause) | Target Bucket & Surface | Proposed Interface Patch |
| :--- | :--- | :--- | :--- | :--- |
| **`P1`** | `[e.g., Turn 3: Guessed wrong CLI flag]` | `[Affordance Gap: Tool schema lacked enum]` | `Bucket 3: Tool Schema` | `"Add enum ['staging', 'prod'] to deploy_env parameter..."` |
| **`P2`** | `[e.g., Turn 5: PR comment flagged raw SQL]` | `[Wayfinding Gap: Missing repo ORM convention]` | `Bucket 1: AGENTS.md` | `"For all database queries, require Drizzle ORM builders..."` |
| **`P3`** | `[e.g., Turn 7: Ran db:push before generating]` | `[Sequencing Gap: Missing pre-flight step]` | `Bucket 2: db-migrate/SKILL.md` | `"Before applying schema changes, run pnpm db:generate..."` |

### 2. Tool Availability & Response Audit (Bucket 3)
* **Missing Affordances:** `[Tools or scripts the runtime needed during the task that were unavailable]`
* **Response Payload Friction:** `[Tool outputs that were too verbose, lacked actionable error recovery hints, or omitted key IDs]`

### 3. Upstream Ticket / Prompt Scorecard (Bucket 4)
* **Original Task Brief:** `[1-sentence summary of initial prompt/ticket]`
* **Missing Acceptance Criteria:** `[Specific scope or architectural decisions the human had to supply mid-flight]`
* **Upgraded First-Pass Prompt / Ticket:**
  > `[Rewrite the initial ticket or prompt so a future session completes the task with zero multi-turn steering]`

### 4. Confirmation Handshake
Ask: *"Which interface patches (by Label) should I apply to your workspace?"*

First time reading about Agent Experience (AX)? Explore the complete AX Engineering Series Hub to learn how to structure Operating Charters, SKILL.md page copy, and composable MCP servers.