best-practices-audit

name	best-practices-audit
description	Verify semantic view compliance with established best practices including naming conventions, descriptions, metadata completeness, data quality standards, inconsistencies detection, and duplicates detection.
required_skills	["semantic-view-optimization-onboarding","semantic-view-optimization-audit/best-practices-audit/results_formatting","semantic-view-optimization-audit/best-practices-audit/inconsistencies","semantic-view-optimization-audit/best-practices-audit/duplicates","semantic-view-optimization-audit/best-practices-audit/missing_relationships","reference/semantic_view_get","reference/semantic_view_concepts"]

Best Practices Audit

When to Load

User selects "Best Practices" from AUDIT MODE menu.

⚠️ CRITICAL: Create TODOs

MANDATORY: Use system_todo_write to create TODOs for all workflow phases. All steps below are MANDATORY and cannot be skipped.

Purpose

Verify that the semantic view follows established best practices for naming, documentation, metadata completeness, and data quality. Additionally, detect structural inconsistencies and duplicate instructions to ensure model integrity and maintainability.

Workflow

Phase 1: Load Semantic View

⚠️ MANDATORY - READ FIRST: Load semantic_view_get.md

Use semantic_view_get.py to retrieve the complete semantic view:

uv run python ../../scripts/semantic_view_get.py --file semantic_model.yaml --component all

Phase 2: Execute Checks

Run all checks against the semantic view in three categories:

Phase 2a: Best Practices Checks

1. Documentation Checks

   • Verify all tables have descriptions
   • Verify all columns have descriptions
   • Check description quality clarity

2. Naming Convention Checks

   • Check for special characters
   • Verify naming consistency

3. Metadata Completeness Checks

   • Verify data types are defined
   • Synonyms are not necessary
   • Relationships should have no descriptions

4. Type Safety Checks

   • Validate dimension vs measure classification
   • Check time dimension types for date columns

Phase 2b: Inconsistencies Checks

⚠️ MANDATORY: Load inconsistencies.md for detection methodology

Phase 2c: Duplicates Checks

⚠️ MANDATORY: Load duplicates.md for detection methodology

Phase 2d: Missing Relationships Checks

⚠️ MANDATORY: Load missing_relationships.md for detection methodology

Only flag if relationship count is suspiciously low for table count.

Phase 3: Categorize Issues

Group findings by category and severity:

Best Practices:

• ERROR: Critical issues that will cause failures
• WARNING: Issues that should be addressed but won't break functionality
• INFO: Recommendations for improvement

Inconsistencies:

• CRITICAL: Will cause query failures or wrong results
• HIGH: Likely to cause confusion or unexpected behavior
• MEDIUM: May cause issues in specific scenarios
• LOW: Stylistic inconsistencies

Duplicates:

• Exact duplicates: Instruction repeats model element verbatim
• High similarity: Instruction conveys same information (>85%)
• Partial overlap: Instruction partially repeats model information

Missing Relationships:

• Only flagged when count is below threshold for table count

Phase 4: Present Results

Load results_formatting.md → Present findings to user

Phase 5: Next Steps

STOP - Prompt user:

• A: Run another audit type
• B: DEBUG MODE (query-based problem investigation)
• C: OPTIMIZATION MODE (apply fixes for identified issues)
• D: Exit

Tools

Tool 1: semantic_view_get.py

Description: Retrieves components from semantic view YAML files. Always outputs in YAML format.

⚠️ MANDATORY: Load semantic_view_get.md for complete syntax and examples.

Usage for this audit:

# Get all components
uv run python ../../scripts/semantic_view_get.py --file semantic_model.yaml --component all

# Get specific components
uv run python ../../scripts/semantic_view_get.py --file semantic_model.yaml --component tables
uv run python ../../scripts/semantic_view_get.py --file semantic_model.yaml --component dimensions
uv run python ../../scripts/semantic_view_get.py --file semantic_model.yaml --component measures

Output

• Best Practices: Categorized list of violations with severity levels
• Inconsistencies: Conflicts and logical errors with severity and impact assessment
• Duplicates: Duplicate instructions with similarity scores
• Missing Relationships: Potential relationships with confidence levels and prerequisites
• Specific locations in semantic view for all issues
• Recommendations for fixes