Skip to content

HK-hub/AgentSkills / ax-audit

ax-audit

Verified

Audits agentic applications for architecture and trust: tool parity, tool granularity, context injection, completion signals, approval gates, confidence cues, escape hatches, intent handshakes, memory visibility, and adaptive canvases. Produces a ship-readiness verdict plus an AX Relationship Summary. Use when reviewing agentic feature PRs or asking "is this agent-native", "AX review", "critique this AI feature", "does this earn user trust", or "audit this for AX". For traditional frontend UX use ui-audit.

FileKindSize
SKILL.mdskill md8.7 KB
references/agent-native-principles.mdmarkdown3.6 KB
references/ax-evolution-curve.mdmarkdown3.0 KB
references/feature-playbooks.mdmarkdown6.7 KB
references/output-format.mdmarkdown4.8 KB
references/ship-readiness.mdmarkdown5.5 KB
rules-arch/_sections.mdmarkdown1.8 KB
rules-arch/_template.mdmarkdown2.2 KB
rules-arch/comm-no-approval-gate.mdmarkdown3.2 KB
rules-arch/comm-no-completion-signal.mdmarkdown2.9 KB
rules-arch/comm-no-progress-visibility.mdmarkdown2.7 KB
rules-arch/context-no-checkpoint-resume.mdmarkdown2.8 KB
rules-arch/context-no-injection.mdmarkdown2.6 KB
rules-arch/context-starvation.mdmarkdown2.6 KB
rules-arch/granularity-static-api-mapping.mdmarkdown2.9 KB
rules-arch/granularity-workflow-shaped-tool.mdmarkdown2.8 KB
rules-arch/parity-crud-incomplete.mdmarkdown2.5 KB
rules-arch/parity-no-tool-parity.mdmarkdown2.3 KB
rules-arch/parity-orphan-ui-action.mdmarkdown2.4 KB
rules-ax/_sections.mdmarkdown2.9 KB
rules-ax/_template.mdmarkdown2.5 KB
rules-ax/comm-no-generative-momentum.mdmarkdown2.6 KB
rules-ax/comm-no-intent-handshake.mdmarkdown3.1 KB
rules-ax/comm-no-progress-signal.mdmarkdown2.8 KB
rules-ax/context-memory-not-visible.mdmarkdown3.0 KB
rules-ax/context-no-adaptive-canvas.mdmarkdown2.9 KB
rules-ax/context-under-contextual.mdmarkdown2.9 KB
rules-ax/control-no-approval-gate.mdmarkdown2.8 KB
rules-ax/control-no-escape-hatch.mdmarkdown2.7 KB
rules-ax/control-over-conversational.mdmarkdown2.3 KB
rules-ax/trust-no-confidence-cues.mdmarkdown2.5 KB
rules-ax/trust-no-escalation-path.mdmarkdown2.6 KB
rules-ax/trust-no-uncertainty-markers.mdmarkdown2.5 KB

references/output-format.md

View on GitHub
# Output Format

Output structure for ax-audit results: a findings table, then the AX relationship summary.

## Table of contents

- [Findings table](#findings-table)
- [Field reference](#field-reference)
- [AX relationship summary](#ax-relationship-summary)
- [AX relationship summary, field descriptions](#ax-relationship-summary-field-descriptions)
- [Terminal rendering](#terminal-rendering)

## Findings table

Each finding is a JSON object (schema is compatible with ui-audit findings, so the two reports merge):

```json
{
  "rule": "trust-no-confidence-cues",
  "layer": "ax",
  "category": "trust",
  "feature": "agent-chat",
  "surface": "ChatPanel",
  "file": "src/chat/ChatPanel.tsx",
  "line": 42,
  "result": "fail",
  "defaultTier": "fix-this-sprint",
  "assignedTier": "fix-this-sprint",
  "tierReason": "Default tier; agent chat surface.",
  "observed": "Agent output rendered in <AssistantMessage> with no citation, source, or reasoning child components.",
  "evidence": ["src/chat/ChatPanel.tsx:42, <AssistantMessage content={message.content} /> with no children"],
  "fix": "Add a <Sources> or <Reasoning> component inside agent message rendering.",
  "suppressed": false
}
```

## Field reference

| Field | Values / notes |
|---|---|
| `rule` | Rule slug, matches the rule filename without `.md` |
| `layer` | `arch` (Layer 1) or `ax` (Layer 2) |
| `category` | arch: `parity \| granularity \| context \| comm`. ax: `trust \| control \| context \| comm` |
| `feature` | One of 4 playbooks: `agent-chat`, `agent-tool-execution`, `agent-config`, `agent-dashboard` |
| `surface` | Component or page name the finding sits on (groups the report) |
| `file`, `line` | Evidence location; required on every `fail`/`warn` |
| `result` | `pass \| warn \| fail \| unknown`: `unknown` requires a reason in `observed` |
| `defaultTier`, `assignedTier`, `tierReason` | Tier from the rule file, tier after surface override, and one-sentence justification. Tier is the only ship-impact signal; no separate severity field |
| `observed` | What the code actually does, in one sentence |
| `evidence` | Array of `file:line: excerpt` strings backing the finding |
| `fix` | Concrete change; a snippet or one-sentence instruction |
| `suppressed` | `true` when an `ax-audit-ignore:<slug>` comment covers the match, report suppressed counts, never silently drop |

## AX relationship summary

Produced after findings, only when agentic features are detected. Four fields naming the user-agent relationship in behavioral terms:

```json
{
  "axSummary": {
    "evolutionStage": {
      "stage": 2,
      "label": "Task-Aware",
      "behavior": "Agent tracks current task state and adjusts in the moment, but starts fresh each session with no memory of user preferences or history."
    },
    "trustSignal": {
      "level": "moderate",
      "reasoning": "Escape hatches present for all agent actions. Confidence cues missing: agent output has no rationale or source attribution."
    },
    "keyGap": "Agent accumulates no session context; every interaction starts cold. Users re-explain preferences and constraints each time.",
    "trustQuestion": "Will users accept inline rationale (sources, reasoning steps) on every agent response, or will it feel like noise?"
  }
}
```

## AX relationship summary: field descriptions

| Field | Description |
|---|---|
| `evolutionStage` | Which of the 4 stages (see `ax-evolution-curve.md`). Describe the behavior, not the label (label for JSON, behavior for the reader). |
| `trustSignal` | `high \| moderate \| low` with one-sentence reasoning, based on how many trust-critical rules passed vs failed (escalation, escape hatch, confidence cues, approval gates). |
| `keyGap` | Single most important architectural or trust gap. One sentence, specific enough to act on. |
| `trustQuestion` | One question for the designer/developer to answer before the next round; only prototyping or research can resolve it. |

## Terminal rendering

Terminal (not JSON) format:

```
═══════════════════════════════════════════════════════════
AX VERDICT: ⚠️ READY WITH FOLLOW-UP (0 blockers, 4 fix-this-sprint)

Surfaces:            2 (ChatPanel, ToolExecutionPanel)
Findings:            6
  Release blockers:  0
  Fix this sprint:   4   ⚠️
  Backlog:           2   📋

AX Relationship:
  Stage:       Task-Aware (2 of 4)
  Trust:       Moderate: escape hatches present, confidence cues missing
  Key gap:     No session context; every interaction starts cold
  Question:    Will users accept inline rationale on every response?

Cross-reference:     Run ui-audit for traditional UX findings
═══════════════════════════════════════════════════════════
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall