​

Verification Standards for Release Notes

​

Core Verification Principles

1. Verify existence first — Search codebase to confirm feature exists before documenting
2. Never assume — Always verify before writing
3. Never hallucinate — If you can’t verify it, don’t document it
4. Be specific — Use exact UI labels, button text, and navigation paths
5. Stay current — Database configurations can change; always verify current values

​

Pre-Documentation Checklist

​

1. Feature Existence Verification

​

Search Commands

# Search for UI components
grep -r "featureName" resources/client/

# Search for backend logic
grep -r "featureName" app/

# Search for routes
grep -r "featureName" routes/

​

What to Verify

• UI components implementing the feature exist
• Backend controllers/services powering it exist
• Database tables/columns for data storage exist
• Routes exposing the feature exist

​

If Not Found

• No UI components implementing it
• No backend controllers handling it
• No database tables storing it
• No routes exposing it

​

2. UI Navigation & Labels Verification

​

Key Files to Check

# Navigation & Menus
common/resources/client/ui/navigation/navbar/navbar-auth-menu.tsx
common/resources/client/auth/auth-routes.tsx

# Account Settings
common/resources/client/auth/ui/account-settings/account-settings-sidenav.tsx

# Billing
common/resources/client/billing/billing-page/

​

Verified UI Elements Reference

• Sidenav says “Delete account” but panel title is “Danger zone”
• Sidenav says “Password” but panel title is “Update password”

​

3. Database Verification Commands

​

Contact & Company

# Contact email
php artisan tinker --execute="echo settings('mail.contact_page_address');"

​

Subscription Plans

# Products (plans)
php artisan tinker --execute="echo json_encode(\DB::table('products')->select('id', 'name', 'free')->get()->toArray(), JSON_PRETTY_PRINT);"

# Prices (billing intervals)
php artisan tinker --execute="echo json_encode(\DB::table('prices')->select('id', 'product_id', 'amount', 'currency', 'interval', 'interval_count')->get()->toArray(), JSON_PRETTY_PRINT);"

​

Profile Menu Items

# Get auth dropdown menu items
php artisan tinker --execute="$menus = json_decode(\DB::table('settings')->where('name', 'menus')->first()->value, true); foreach($menus as $menu) { if (in_array('auth-dropdown', $menu['positions'] ?? [])) { foreach($menu['items'] as $item) { echo $item['label'] . ' → ' . $item['action'] . PHP_EOL; } } }"

​

Writing Standards

​

Language & Tone

• Non-technical — Write for users, not developers
• Clear — Use simple, direct language
• Actionable — Guide users step-by-step
• Accurate — Every claim must be verifiable

​

Avoiding Technical Jargon

​

UI References

​

Navigation Format

Click your **profile avatar** in the top navigation bar, then select **Billing** from the menu.

Go to Settings → Subscription

​

Common Mistakes to Avoid

​

❌ Don’t Do This

0. Document features that don’t exist
   • Wrong: Creating docs for “demo downloads”, “watermarked previews”
   • Fix: Search codebase FIRST
1. Trust backend config without verifying frontend
   • Wrong: “Legendary achievements don’t exist” (config says rarity 5)
   • Fix: Check frontend code for actual display mapping
2. Assume navigation paths
   • Wrong: “Go to Settings → Subscription”
   • Fix: Verify actual menu structure
3. Invent menu item names
   • Wrong: “Select Settings from the menu”
   • Fix: Check database for actual labels
4. Use generic section names
   • Wrong: “the Localization section”
   • Fix: Use exact labels: “Location and language”
5. Confuse sidenav with panel titles
   • Wrong: “the Delete Account section”
   • Fix: Panel is “Danger zone”
6. Use inconsistent capitalization
   • Wrong: “This Device”, “Log Out Other Devices”
   • Fix: “This device”, “Logout other sessions”
7. Document features without verification
   • Wrong: “Select monthly or yearly billing”
   • Fix: Query database to confirm intervals
8. Use generic button names
   • Wrong: “Click the Cancel button”
   • Fix: “Click Cancel plan”
9. Use technical terminology
   • Wrong: “You need the music.create permission”
   • Fix: “You need the ability to upload tracks”

​

Release Note Specific Requirements

​

What to Verify for Release Notes

1. Feature actually shipped
   • Check deployment status
   • Verify in production environment
   • Confirm no feature flags blocking it
2. User-facing changes only
   • Internal refactoring = no release note
   • Database schema changes = no release note (unless affects users)
   • Backend optimization = no release note (unless improves UX)
3. Accurate impact description
   • Don’t claim “all users” if it’s producer-only
   • Don’t claim “major improvement” for minor bug fix
   • Use severity levels appropriately
4. Correct navigation for new features
   • Actually navigate to the feature in UI
   • Document the exact path found
   • Verify buttons/controls exist

​

Post-Release Verification

1. Verify links work — Click all internal links
2. Check rendering — Preview in Mintlify
3. Confirm placement — File in correct folder
4. Validate indices — Month/year indexes updated

​

Verification Checklist Template

​

Feature Existence

• Searched codebase for feature
• Found UI components
• Found backend logic
• Confirmed routes exist
• Feature is actually deployed

​

Navigation Accuracy

• Checked actual menu structure
• Used exact UI labels
• Verified button text
• Tested navigation path

​

Content Quality

• No internal jargon
• No technical terminology users don’t see
• All UI references use exact labels
• Bold formatting for buttons/menus
• Numbers/metrics verified

​

Database Verification (if applicable)

• Queried products/plans for billing mentions
• Queried settings for configuration claims
• Verified pricing is current
• Checked for trials (none exist)

​

Mintlify Formatting

• Frontmatter valid YAML
• Tags from taxonomy only
• Components from approved list
• All icon names verified against Font Awesome 6 (not Lucide — see Section below)
• No emoji used
• Internal doc links use root-relative paths (/help/...)
• App page links use full URLs (https://open.beatpass.ca/...)
• All Card href targets verified (.mdx file exists + listed in docs.json)

​

Icon Verification (Font Awesome 6)

​

Before Using Any Icon

1. Verify the icon name exists at fontawesome.com/icons
2. Check it’s not a Lucide name (common mistake — see table below)
3. Check it’s not a deprecated FA4/FA5 alias

​

Common Invalid Icons That Cause Silent Failures

​

Batch Verification Command

# Extract all unique icon names from MDX files and docs.json
grep -roh 'icon="[^"]*"' --include="*.mdx" --include="*.json" | sort -u

# Then verify each name at fontawesome.com/icons

​

Link Verification

​

Internal Doc Links

1. Verify the corresponding .mdx file exists on disk
2. Verify the page is listed in docs.json navigation
3. If the file was renamed or moved, search for and update ALL references

​

App Page Links

Never use bare paths like /login or /pricing — Mintlify will try to resolve these as doc pages and they will 404.

​

Card href Verification

• If internal doc path → .mdx file exists
• If internal doc path → page is in docs.json nav
• If app page → uses https://open.beatpass.ca/...
• If external → URL is valid and accessible

​

WCAG AA Color Verification

• Primary: #187AB4 (4.63:1 ✅)
• Light: #5BC0F0 (9.94:1 ✅)
• Dark: #1F8AC8 (5.36:1 ✅)

​

Mintlify CLI Known Issues

​

Quick Verification Commands

# Search for a feature in UI
grep -r "featureName" resources/client/ --include="*.tsx"

# Search for backend controller
grep -r "featureName" app/Http/Controllers/ --include="*.php"

# Check database for settings
php artisan tinker --execute="echo settings('setting.key');"

# List menu items
php artisan tinker --execute="$menus = json_decode(\DB::table('settings')->where('name', 'menus')->first()->value, true); foreach($menus as $menu) { if (in_array('auth-dropdown', $menu['positions'] ?? [])) { foreach($menu['items'] as $item) { echo $item['label'] . PHP_EOL; } } }"

# Check plans
php artisan tinker --execute="echo json_encode(\DB::table('products')->get(['name', 'free'])->toArray());"

​

AI Agent Verification Protocol

1. State what was verified — List the files/commands checked
2. Note assumptions — Clearly mark anything not verified
3. Use verified data only — No placeholder text for unverified elements
4. Flag for review — Mark sections needing human verification
5. Check snippets — Use existing /snippets/ imports for repeated content (fees, warnings, support sections) instead of writing inline

​

Example Verification Statement

VERIFIED:
- Feature exists in: resources/client/web-player/backstage/new-feature.tsx
- Backend controller: app/Http/Controllers/NewFeatureController.php
- Database table: new_features (columns: id, user_id, setting)
- Menu item: "New Feature" in auth-dropdown (verified via DB query)

ASSUMED (needs verification):
- Exact button text in modal (could not locate component)
- Performance improvement percentage (from PR description, not benchmarked)