What is transaction-audit?

The Transaction Audit skill acts as an automated project manager for API documentation and transaction tracking. It synchronizes with Swagger/OpenAPI specifications to maintain a source of truth, monitors the documentation status of various endpoints, and orchestrates complex analysis workflows by delegating tasks to specialized worker agents. It is designed to ensure consistency between live API structures and local documentation files.

When should I use transaction-audit?

transaction-audit is useful in the following scenarios: • API Documentation Management: Automatically sync local tracking files with live Swagger JSON to identify new, removed, or updated transaction endpoints. • Workflow Orchestration: Manage the lifecycle of API analysis by tracking statuses from 'not-analyzed' to 'verified' and delegating specific tasks to the /analyze-transaction worker skill. • Path Alignment & Migration: Detect misalignments between API endpoint structures and local file paths, providing automated suggestions for migrating legacy files to standardized directories. • Dependency Mapping: Prioritize documentation tasks by identifying Tier 1 entry points (like authentication) that must be analyzed before dependent Tier 2-4 transactions.

transaction-audit – AI Agent Skills

name	transaction-audit
description	Orchestrate V2 transaction documentation by tracking all endpoints and delegating analysis to /analyze-transaction

This skill is the **project manager** for V2 transaction documentation. It tracks all transaction endpoints from the Atlas API swagger and coordinates analysis work.

Source of Truth: https://atlas-api-preprod-507341199760.us-central1.run.app/swagger.json

Worker Skill: Use /analyze-transaction to process individual transactions.

Tracking File: .claude/skills/transaction-audit/v2-transaction-tracker.json

## When Invoked

Sync with Swagger (if requested or stale)
- Fetch latest swagger.json from Atlas API
- Compare endpoints to tracker
- Add any new endpoints, flag any removed ones
Display Status Dashboard
- Show summary: X analyzed, Y not-analyzed, Z verified
- List transactions by system (global, instance, course, project)
- Highlight path misalignments between swagger and existing files
Identify Work Needed
- List transactions with not-analyzed status
- List transactions with path misalignments (legacy files in wrong location)
- Prioritize based on dependencies (e.g., access-token-mint before enrollments)
Prompt for Action
- Offer to run /analyze-transaction for specific transactions
- Offer to migrate legacy files to correct paths
- Offer to mark transactions as verified after testing

Commands

Command	Description
`/transaction-audit`	Show dashboard and status
`/transaction-audit sync`	Sync tracker with swagger.json
`/transaction-audit status`	Show summary counts only
`/transaction-audit next`	Suggest next transaction to analyze
`/transaction-audit analyze <id>`	Run /analyze-transaction for specific tx

## Transaction Statuses

Status	Meaning
`not-analyzed`	Known from swagger, no YAML/TS files created yet
`analyzed`	YAML + TS files created via /analyze-transaction
`verified`	Tested against live API, confirmed working

Status Transitions

not-analyzed → analyzed → verified
     ↑              ↓
     └──────────────┘ (if API changes)

## Tracker File Structure

{
  "version": "1.0.0",
  "lastUpdated": "YYYY-MM-DD",
  "swaggerSource": "https://atlas-api-preprod-507341199760.us-central1.run.app/swagger.json",
  "totalTransactions": 17,
  "summary": {
    "analyzed": N,
    "not-analyzed": N,
    "verified": N
  },
  "transactions": [
    {
      "id": "system.role.action",
      "endpoint": "/v2/tx/...",
      "method": "POST",
      "system": "global|instance|course|project",
      "role": "general|owner|teacher|student|manager|contributor",
      "description": "...",
      "status": "not-analyzed|analyzed|verified",
      "lastAnalyzed": "YYYY-MM-DD" | null,
      "files": {
        "yaml": "path/to/file.yaml" | null,
        "ts": "path/to/file.ts" | null,
        "mdx": "path/to/file.mdx" | null
      },
      "legacyFiles": {  // Only if path mismatch exists
        "yaml": "old/path.yaml",
        "note": "Migration needed"
      },
      "notes": "..."
    }
  ]
}

## Path Alignment Rules

File paths MUST match the API endpoint structure:

API Endpoint	YAML Path	TS Path
`/v2/tx/{system}/{role}/{action}`	`{system}/{role}/{action}.yaml`	`{system}/{role}/{action}.ts`

Examples:

/v2/tx/global/general/access-token/mint → global/general/access-token/mint.yaml
/v2/tx/course/student/assignment/commit → course/student/assignment/commit.yaml
/v2/tx/project/contributor/task/commit → project/contributor/task/commit.yaml

Base Paths:

YAML: public/yaml/transactions/v2/
TS: packages/andamio-transactions/src/definitions/v2/
MDX: content/docs/protocol/v2/transactions/

## Transaction Dependencies

Some transactions must be analyzed in order:

Tier 1: Entry Points (no dependencies)

global.general.access-token.mint - Required for all other transactions

Tier 2: Instance Creation (requires access token)

instance.owner.course.create
instance.owner.project.create

Tier 3: Management (requires instance)

Course: course.owner.teachers.manage, course.teacher.modules.manage
Project: project.owner.managers.manage, project.owner.contributor-blacklist.manage, project.manager.tasks.manage

Tier 4: Participation (requires course/project)

Course: course.student.enroll, course.student.assignment.action, course.teacher.assignments.assess, course.student.credential.claim
Project: project.contributor.enroll, project.contributor.task.commit, project.contributor.task.action, project.manager.tasks.assess, project.contributor.credential.claim

## Dashboard Output Format

═══════════════════════════════════════════════════════════════
                 V2 TRANSACTION AUDIT DASHBOARD
═══════════════════════════════════════════════════════════════

Last Updated: YYYY-MM-DD
Swagger Source: https://atlas-api-preprod-507341199760.us-central1.run.app/swagger.json

SUMMARY
───────────────────────────────────────────────────────────────
Total: 17 | Analyzed: 1 | Not Analyzed: 16 | Verified: 0

BY SYSTEM
───────────────────────────────────────────────────────────────
Global (1):     ████████████████████ 100% [1/1]
Instance (2):   ░░░░░░░░░░░░░░░░░░░░   0% [0/2]
Course (6):     ░░░░░░░░░░░░░░░░░░░░   0% [0/6]
Project (8):    ░░░░░░░░░░░░░░░░░░░░   0% [0/8]

TRANSACTIONS
───────────────────────────────────────────────────────────────
[✓] global.general.access-token.mint
[ ] instance.owner.course.create          ⚠️ Legacy path mismatch
[ ] instance.owner.project.create
[ ] course.owner.teachers.manage          ⚠️ Legacy path mismatch
...

NEXT RECOMMENDED
───────────────────────────────────────────────────────────────
→ instance.owner.course.create (Tier 2, has legacy file to migrate)

To analyze: /analyze-transaction <paste decoded CBOR>
═══════════════════════════════════════════════════════════════

## Important Notes

Swagger is the source of truth - The tracker should always reflect what's in swagger.json
Path alignment is mandatory - All new files must match API URL structure
Legacy files need migration - Some old files exist at wrong paths; migrate them when analyzing
Update tracker after analysis - When /analyze-transaction completes, update the tracker
Verify after testing - Only mark as "verified" after testing against live API

Related Skills

/analyze-transaction - Worker skill that processes individual transaction CBORs
/glossary-game - Terminology validation (different domain)

transaction-audit

When & Why to Use This Skill

Use Cases