audit-service

What this skill does

# Audit Service

Audits backend services against their Notion specifications, validates operation completeness and coding standards compliance, generates discrepancy reports, and remediates approved changes by invoking `build-service`.

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Audit backend services against their specifications to identify gaps, generate actionable discrepancy reports, sync decisions to Notion, and remediate approved changes.
**When to use**:
- Reviewing service operations for standards compliance before release
- Validating completeness after specification updates
- Conducting quality assurance on service operation documentation
- Checking operation manifest alignment with Notion specs

**Prerequisites**:
- Service must exist as `@theriety/service-{name}` or `@theriety/manifest-{name}`
- Specification must be available in DESIGN.md or Notion
- Access to Notion workspace with Services and Service Operations databases

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

### Your Role

You are a **Service Audit Director** who orchestrates like a quality assurance executive overseeing comprehensive service reviews. You never execute tasks directly, only delegate and coordinate. Your management style emphasizes:

- **Systematic Auditing**: Methodically compare implementation against specification
- **Evidence-Based Reporting**: Every finding backed by specific file/line references
- **User-Driven Remediation**: Present findings and wait for user decisions before fixing
- **Traceability**: Every change tracked from spec → finding → decision → implementation

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Service Name**: The name of the service to audit (maps to `@theriety/service-{name}`)

#### Optional Inputs

- **Operation Filter**: Specific operation name(s) for focused audit (default: all operations)
- **Area Filter**: Functional domain filter (default: all areas)
- **--auto-fix**: Automatically approve and implement all findings (default: interactive)

#### Expected Outputs

- **AUDIT.md**: Comprehensive discrepancy report with per-operation findings
- **Updated Notion Spec**: Decisions synced back to Notion (if approved)
- **Remediated Code**: Implemented fixes for approved changes (via `build-service`)
- **Compliance Status**: Pass/fail for each operation

#### Data Flow Summary

Load spec from Notion → audit each operation against spec → generate AUDIT.md → present findings to user → sync decisions to Notion → remediate approved changes → 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: validate operations in parallel batches)
   |                    +- coding:review
   |                    +- coding:lint
   |                    +- coding:find-unused
   |                    +- Operation completeness check
   v
[Step 3: Generate Report] --------- (You: compile AUDIT.md)
   |
   v
[Step 4: Decision Gate] ----------- (You: present findings, collect user decisions)
   |
   v
[Step 5: Sync to Notion] --------> (Sub-skill: specification:sync-notion)
   |
   v
[Step 6: Remediate] -------------> (Sub-skill: backend:build-service)
   |
   v
[Step 7: Final Report] ----------- (You: compile summary)
   |
   v
[END]

Legend:
═══════════════════════════════════════════════════════════════
• Steps 1,5: Notion sync via specification plugin
• Step 2: Parallel validation subagents
• Step 6: Remediation via build-service
• Steps 3,4,7: Orchestrator decisions
═══════════════════════════════════════════════════════════════
```

## 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 service specification from Notion
- **Input**: Service name
- **Output**: Complete spec with operations list, data operations, service context
- **Sub-skill**: `/Users/alvis/Repositories/.claude/plugins/specification/skills/sync-notion/SKILL.md`
- **Parallel Execution**: No

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

1. Load `/Users/alvis/Repositories/.claude/plugins/specification/skills/sync-notion/SKILL.md`
2. Execute in **pull mode** to fetch the latest spec from Notion
3. Extract: service metadata, all service operation pages, data operation dependencies
4. Continue to Step 2

---

### Step 2: Audit vs Spec

**Step Configuration**:

- **Purpose**: Validate each operation against its specification for completeness and standards compliance
- **Input**: Spec from Step 1 + local service codebase
- **Output**: Per-operation validation results
- **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 (operations validated in parallel, max 2 at a time)

#### Phase 1: Planning (You)

1. **List all operations** from the spec
2. **Apply filters** (operation filter, area filter) if specified
3. **Discover service** by searching Notion for the Services database, locating the service page, extracting operation metadata
4. **Create batches** (max 2 operations per batch)
5. **Use TodoWrite** to track

#### Phase 2: Execution (Subagents)

Spin up read-only validation subagents, up to **2** at a time. The 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.

    >>>
    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 page export or DESIGN.md section]
    **Implementation**: [absolute path(s) to operation source file(s) and related tests]
    **Output Template**: [absolute path to AUDIT.md template or finding row schema]
    **Applicable Standards**:
    - /Users/alvis/Repositories/.claude/plugins/backend/constitution/standards/data-operation.md

    **Report** (<1000 tokens):
    ```yaml
    status: success|failure|partial
    outputs:
      operation_name: '[name]'
      validation_status: 'pass|issues_found'
      issues_found: ['issue with location and fix', ...]
      recommendations: ['improvement', ...]
    issues: []
    ```
    <<<

**Issue Escalation**: When issues found, pause further validation, present detailed report with code snippets and fix suggestions, await user approval before continuing.

Also execute in parallel:
- `coding:review` — code quality review of the service package
- `coding:lint` — lint check
- `coding:find-unused` — dead code detection

#### Phase 4: Decision (You)

1. Collect all validation reports
2. Consolidate into per-operation findings
3. Categorize by functional domain
4. **PROCEED** to Step 3

---

### Step 3: Generate Discrepancy Report

**Step Configuration**:

- **Purpose**: Produce AUDIT.md with consolidated findings
- **Input**: All validation results from Step 2
- **Output**: AUDIT.md file
- **Sub-skill**: (none — orchestrator compiles)
- **Parallel Execution**: No

#### Phase 1: Planning (You)

Generate AUDIT.md with this structure:

```markdown
# Service Audit: @theriety/service-{name}
Date: [YYYY-