| name | connector-audit |
| description | Deep reliability audit for OpenMetadata connectors — runs 7 investigation prompts (metadata, errors, auth, lineage, scale, synthesis, implementation) against connector standards |
OpenMetadata Connector Reliability Audit
When to Activate
When a user asks to audit a connector, run a reliability audit, or investigate connector quality in depth.
STEP 1 — DO THIS FIRST, BEFORE ANYTHING ELSE
When this skill is invoked, your VERY FIRST action — before responding to the user, before summarizing anything, before checking any state — is:
- List all files in
.claude/audit-results/ (if the directory exists)
- List
.claude/connector-audit.json (if it exists)
- Present the file list to the user and ask: "These files exist from a previous audit. Which should I keep and which should I delete?"
- Wait for the user's answer. Do NOT proceed until they respond.
If no files exist, skip to Step 2.
NEVER summarize existing results, say "the audit is complete", or suggest the user doesn't need to run anything. The user invoked the skill — execute it.
Arguments
- Connector name (e.g.,
mysql, snowflake, tableau): Full 7-prompt audit
--prompt N (e.g., --prompt 3): Run a single prompt (1-7) — useful for re-running after fixes--prompts N,M (e.g., --prompts 1,4): Run specific prompts only--from N (e.g., --from 6): Run prompts N through 7 — useful for continuing after P1-P5--setup-only: Run setup only (writes connector-audit.json)--dry-run: When used with P7, produce a detailed implementation plan (before/after diffs, tests, risk flags) without actually writing code — for review before execution
Relationship to connector-review
| connector-audit | connector-review |
|---|
| Purpose | Deep reliability investigation | Breadth check for PRs |
| Depth | 7 focused prompts, hours of analysis | 5 parallel agents, minutes |
| Output | .claude/audit-results/ (7 reports) | PR comment or local report |
| When | Before major work on a connector | During PR review |
| Scope | Full connector + base classes + shared code | Changed files only |
Workflow Overview
Setup → P1-P5 (investigation, parallelizable) → P6 (synthesis) → P7 (implementation)
Phase 1: Setup
After the stale results check (Step 1 above), run the setup prompt to establish connector context. This writes .claude/connector-audit.json which all subsequent prompts read.
Phase 2: Static Pre-Check
Run the static analyzer from the connector-review skill to get a mechanical baseline:
python skills/connector-review/scripts/analyze_connector.py {service_type} {name} --json
Save the output — prompts reference it to avoid duplicating mechanical checks.
Phase 3: Investigation (P1-P5)
These 5 prompts are independent and can run in any order. For efficiency, dispatch them in parallel:
- Pair A: P1 (Metadata & Ingestion) + P2 (Error Handling)
- Pair B: P3 (Connection & Auth) + P4 (Lineage)
- Solo: P5 (Scale & Performance)
Each prompt:
- Reads
.claude/connector-audit.json for context
- Loads connector standards via
/connector-standards
- Investigates its focus area in depth
- Presents a summary for user review
- Saves its report under
.claude/audit-results/ using the fixed filename for that prompt described in the Output Structure section (for example, 01-metadata-ingestion.md for P1) after user approval
User review gate: Each prompt presents findings and asks for confirmation before saving. This catches errors early instead of propagating them to P6.
Phase 4: Synthesis (P6)
Reads all 5 reports from .claude/audit-results/, cross-validates findings, clusters root causes, checks git history, and produces a prioritized implementation plan with PR scoping.
Phase 5: Implementation (P7)
Reads the P6 plan and implements the fixes — writes code, runs tests, creates commits. With --dry-run, produces a detailed plan (before/after diffs, test code, risk flags) without writing code.
Prompt Files
Each prompt is a self-contained investigation guide in prompts/:
| # | File | Focus | Standards |
|---|
| 0 | 00-setup.md | Set target connector, write context file | — |
| 1 | 01-metadata-ingestion.md | Metadata coverage by tier, ingestion completeness | Tiers 1-3, Standard 1 |
| 2 | 02-error-handling.md | Error handling, fault tolerance, observability | Standards 4, 5, 7 |
| 3 | 03-connection-auth.md | Auth methods, test connection, SSL/TLS | Standard 3 |
| 4 | 04-lineage.md | SQL dialect, FQN resolution, column lineage | Standard 2 |
| 5 | 05-scale-performance.md | Memory patterns, pagination, generators, lookups | Standard 6 |
| 6 | 06-refactor-plan.md | Cross-validate, cluster root causes, PR scoping | All standards |
| 7 | 07-implementation.md | Implement fixes (or --dry-run for plan only) | All standards |
How to Run
Full Audit
/connector-audit mysql
- Stale results check: List existing files in
.claude/audit-results/, ask user what to keep/delete, wait for answer
- Setup: Ask user for connector name (if not provided), find source directory, write
.claude/connector-audit.json
- Static pre-check: Run
analyze_connector.py for mechanical baseline
- P1-P5: For each prompt:
a. Read the prompt file from
prompts/0N-*.md
b. Follow its instructions — read the actual connector source code, analyze it against the standards, produce findings with file:line references
c. Present a summary to the user for review
d. Save the report to .claude/audit-results/ after user approval
- P6: Read all reports from
.claude/audit-results/, synthesize, present implementation plan, save after approval
- P7: Read P6 plan, implement fixes (or
--dry-run for plan only), save after approval
Each prompt is a detailed investigation guide — it tells you exactly which files to read, what to look for, how to rate findings, and what format to present them in. You must actually read the connector's source code and do the analysis, not summarize previous results.
Single Prompt
/connector-audit mysql --prompt 3
Verify .claude/connector-audit.json exists, then read the prompt file and execute only that investigation.
Parallel Dispatch
When running the full audit, dispatch P1-P5 using Agent subagents for parallelism:
- Each agent gets: the prompt content, connector-audit.json values, and the static analyzer output
- Each agent saves its report independently
- P6 runs only after all 5 reports exist
Important: Each agent must present its summary and get user approval before saving. When running in parallel pairs, present both summaries together.
Standards Reference
All prompts reference connector standards loaded via /connector-standards. The standards live at:
skills/connector-review/standards/ — shared standards (main.md, patterns.md, etc.)skills/connector-review/standards/source_types/ — per-service-type standards
The static analyzer at skills/connector-review/scripts/analyze_connector.py provides mechanical checks that complement the deeper investigation in each prompt.
Output Structure
.claude/
├── connector-audit.json # Connector context (written by Setup)
└── audit-results/
├── 01-metadata-ingestion.md # P1 report
├── 02-error-handling.md # P2 report
├── 03-connection-auth.md # P3 report
├── 04-lineage.md # P4 report
├── 05-scale-performance.md # P5 report
├── 06-refactor-plan.md # P6 consolidated plan
└── 07-implementation.md # P7 implementation report (or 07-dry-run-implementation.md with --dry-run)
Report Template
Each prompt report follows the template in templates/audit-report.md. Key sections:
- Header with connector name, prompt number, standards assessed, and rating
- Findings with file:line references and severity
- Rating calibration evidence
- Present & Validate summary for user review
