audit-data

What this skill does

# Audit Data

Audits data orchestrators against their Notion specifications, validates schema completeness, operation coverage, and controller alignment, generates discrepancy reports, and remediates approved changes by invoking `build-data`.

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Audit data orchestrators against their specifications to identify schema gaps, missing operations, controller mismatches, and coding standards violations, then remediate approved changes.
**When to use**:
- Reviewing data domain completeness after spec updates
- Validating Prisma schema alignment with Notion entity definitions
- Checking operation coverage for all declared entities
- Verifying controller methods match implemented operations
- Quality assurance before release

**Prerequisites**:
- Data orchestrator must exist as `@theriety/data-{domain}`
- Specification must be available in DESIGN.md or Notion
- Access to Notion workspace with Data Controllers database

**What this skill does NOT do**:
- Build new data orchestrators from scratch (use `build-data`)
- Create service packages (use `build-service`)
- Modify Notion specifications without user approval

### Your Role

You are a **Data Audit Director** who orchestrates like a database integrity auditor. You never execute tasks directly, only delegate and coordinate. Your management style emphasizes:

- **Systematic Schema Auditing**: Compare every Prisma model against Notion entity definitions
- **Operation Coverage Analysis**: Verify every entity has appropriate CRUD operations
- **Controller Alignment**: Ensure controller methods match implemented operations 1:1
- **Evidence-Based Reporting**: Every finding backed by specific file/line/model references

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Domain Name**: The data domain to audit (maps to `@theriety/data-{domain}`)

#### Optional Inputs

- **Operation Filter**: Specific operation(s) for focused audit
- **Entity Filter**: Specific entity(ies) for focused audit
- **--auto-fix**: Automatically approve all findings

#### Expected Outputs

- **AUDIT.md**: Discrepancy report with schema/operation/controller findings
- **Updated Notion Spec**: Decisions synced back (if approved)
- **Remediated Code**: Fixes implemented via `build-data`
- **Compliance Status**: Pass/fail per entity and operation

#### Data Flow Summary

Load spec from Notion → audit schema, operations, controllers → generate AUDIT.md → collect user decisions → sync to Notion → remediate via build-data → final report.

### Visual Overview

```plaintext
  YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Load Spec] -------------> (Sub-skill: specification:sync-notion)
   |
   v
[Step 2: Audit vs Spec] ---------> (Subagents: 3 parallel streams)
   |                    +- Schema audit (Prisma vs Notion entities)
   |                    +- Operation audit (coverage + patterns)
   |                    +- Controller audit (method alignment)
   |                    +- coding:review + coding:lint + coding:find-unused
   v
[Step 3: Generate Report] --------- (You: compile AUDIT.md)
   |
   v
[Step 4: Decision Gate] ----------- (You: present findings, collect decisions)
   |
   v
[Step 5: Sync to Notion] --------> (Sub-skill: specification:sync-notion)
   |
   v
[Step 6: Remediate] -------------> (Sub-skill: backend:build-data)
   |
   v
[Step 7: Final Report] ----------- (You: compile summary)
   |
   v
[END]

Legend:
═══════════════════════════════════════════════════════════════
• Step 2: Three parallel audit streams for comprehensive coverage
• Step 6: Remediation via build-data (NOT build-service)
═══════════════════════════════════════════════════════════════
```

## 3. SKILL IMPLEMENTATION

### Skill Steps

1. Step 1: Load Spec
2. Step 2: Audit vs Spec
3. Step 3: Generate Discrepancy Report
4. Step 4: Decision Gate
5. Step 5: Sync Decisions to Notion
6. Step 6: Implement Approved Changes
7. Step 7: Final Report

---

### Step 1: Load Spec

**Step Configuration**:

- **Purpose**: Fetch data domain specification from Notion
- **Input**: Domain name
- **Output**: Entity definitions, operation specs, controller expectations
- **Sub-skill**: `/Users/alvis/Repositories/.claude/plugins/specification/skills/sync-notion/SKILL.md`
- **Parallel Execution**: No

#### Execute Sync Sub-Skill (You)

1. Load specification:sync-notion in **pull mode**
2. Search for Data Controllers database in Notion
3. Locate the controller page for the specified domain
4. Extract: entity definitions with attributes, operation specifications, relationship definitions
5. Continue to Step 2

---

### Step 2: Audit vs Spec

**Step Configuration**:

- **Purpose**: Validate schema, operations, and controllers against specification
- **Sub-skills**: `/Users/alvis/Repositories/.claude/plugins/coding/skills/review/SKILL.md`, `/Users/alvis/Repositories/.claude/plugins/coding/skills/lint/SKILL.md`, `/Users/alvis/Repositories/.claude/plugins/coding/skills/find-unused/SKILL.md`
- **Parallel Execution**: Yes (3 audit streams in parallel)

#### Phase 1: Planning (You)

1. **List all entities** from Notion spec
2. **List all operations** from Notion spec
3. **Read local codebase**: prisma schema, operations directory, controller class
4. **Create 3 audit streams**: schema, operations, controllers
5. **Apply filters** if specified

#### Phase 2: Execution (Subagents)

Spin up **3 parallel read-only audit subagents**. Each dispatch prompt MUST contain ONLY: spec path, implementation path(s), output template path, and applicable standards paths. Do not include parent narrative, intent, or expected conclusions.

**Stream 1 — Schema Audit**:

    >>>
    You are an independent auditor. Treat the implementation as unfamiliar. Compare it against the spec and the listed standards. Do not assume the implementation matches the spec.

    This is a read-only audit. Do not modify any file.

    **Spec**: [absolute path to entity spec export or DESIGN.md section]
    **Implementation**: [absolute path(s) to prisma/ schema files]
    **Output Template**: [absolute path to AUDIT.md schema-findings template]
    **Applicable Standards**:
    - /Users/alvis/Repositories/.claude/plugins/backend/constitution/standards/data-entity.md

    **Report** (<1000 tokens):
    ```yaml
    status: success|failure|partial
    outputs:
      models_checked: N
      missing_models: ['Model1', ...]
      orphaned_models: ['Model2', ...]
      field_mismatches: ['Model.field: expected X got Y', ...]
      missing_relations: ['Model1 -> Model2', ...]
    issues: []
    ```
    <<<

**Stream 2 — Operation Audit**:

    >>>
    You are an independent auditor. Treat the implementation as unfamiliar. Compare it against the spec and the listed standards. Do not assume the implementation matches the spec.

    This is a read-only audit. Do not modify any file.

    **Spec**: [absolute path to operation spec export or DESIGN.md section]
    **Implementation**: [absolute path(s) to src/operations/ and src/operations/index.ts]
    **Output Template**: [absolute path to AUDIT.md operation-findings template]
    **Applicable Standards**:
    - /Users/alvis/Repositories/.claude/plugins/backend/constitution/standards/data-operation.md

    **Report** (<1000 tokens):
    ```yaml
    status: success|failure|partial
    outputs:
      operations_checked: N
      missing_operations: ['op1', ...]
      extra_operations: ['op2', ...]
      pattern_violations: ['op3: wrong verb pattern', ...]
      missing_tests: ['op4: no int test', ...]
    issues: []
    ```
    <<<

**Stream 3 — Controller Audit**:

    >>>
    You are an independent auditor. Treat the implementation as unfamiliar. Compare it against the spec and the listed standards. Do not assume the implementation matches the spec.