afv-library/skills/deployment-readiness-check/SKILL.md

name	description	license	compatibility	metadata	allowed-tools
deployment-readiness-check	Comprehensive pre-deployment validation checklist for Salesforce releases. Use before deploying to production to catch metadata issues, test coverage gaps, and configuration errors.	Apache-2.0	Requires Salesforce CLI, jq, bash	author version afv-library 1.0	Bash Read

When to Use This Skill

Use this skill before deploying Salesforce metadata to production (or higher environments) to:

• Validate metadata quality and completeness
• Check test coverage meets organizational standards
• Verify security settings and permissions
• Identify configuration issues before deployment
• Generate deployment documentation

Prerequisites

• Salesforce CLI installed and authenticated to target org
• jq command-line JSON processor installed
• Bash shell (Linux, macOS, or WSL on Windows)
• Source metadata in SFDX project format

Step 1: Run Metadata Validation

Execute the validation script to check for common metadata issues:

bash scripts/check_metadata.sh

The script validates:

• Metadata format - Ensures all XML is well-formed
• API versions - Checks for outdated API versions
• Deprecated features - Identifies deprecated components
• Naming conventions - Validates standard naming patterns
• File completeness - Ensures meta.xml files are present

Review the output for any warnings or errors before proceeding.

Step 2: Verify Test Coverage

Check that your Apex test coverage meets organizational standards:

# Run all tests and generate coverage report
sf apex test run --test-level RunLocalTests --result-format human --code-coverage --wait 10

# Check coverage percentage
sf apex get test --test-run-id <test-run-id> --code-coverage --result-format json | jq '.summary.testRunCoverage'

Minimum requirements:

• Overall org coverage: ≥75% (Salesforce minimum)
• Individual class coverage: ≥75% (recommended)
• No classes with 0% coverage

If coverage is below threshold:

1. Identify uncovered classes using the coverage report
2. Add test methods to increase coverage
3. Rerun tests until requirements are met

Step 3: Security and Permissions Review

Review security settings and permissions to ensure proper access controls:

1. Profile and Permission Set Review

   • Check that custom profiles/permission sets follow least-privilege principle
   • Verify admin permissions are not granted to standard users
   • Ensure sensitive objects have appropriate FLS

2. Sharing Rules and OWD

   • Review Organization-Wide Defaults are appropriate
   • Validate sharing rules grant necessary access without over-sharing
   • Check for public groups with excessive membership

3. API Access

   • Verify Connected Apps have appropriate scopes
   • Check Named Credentials use secure authentication
   • Review Remote Site Settings are necessary

Consult the security checklist reference for detailed guidance.

Step 4: Configuration Validation

Verify configuration settings are deployment-ready:

# Check for hardcoded URLs or IDs
grep -r "https://.*\.salesforce\.com" force-app/main/default/
grep -r "[a-zA-Z0-9]{15,18}" force-app/main/default/ | grep -v "meta.xml"

# Validate Custom Settings and Custom Metadata
sf project retrieve start --metadata CustomObject:*__c

Configuration checklist:

• No hardcoded production URLs in code
• No hardcoded record IDs
• Custom Settings configured correctly for target org
• Custom Metadata Types populated appropriately
• Email templates reference correct org email
• Reports and Dashboards folders have correct permissions

Step 5: Review Dependencies

Check for dependency conflicts or missing components:

# Generate dependency report
sf project deploy validate --manifest package.xml --test-level RunLocalTests --verbose

# Check for missing dependencies
grep -i "error.*component" deployment_log.txt

Common dependency issues:

• Missing Custom Fields referenced in code
• Validation Rules referencing deleted fields
• Workflows or Process Builders using deprecated actions
• Lightning Components with missing design resources

See dependency troubleshooting guide for solutions.

Step 6: Generate Deployment Checklist

Use the deployment checklist template to document your release:

cp assets/deployment_checklist.md deployment_checklist_$(date +%Y%m%d).md

Fill out the checklist with:

• Deployment date and time window
• Components being deployed (attach package.xml)
• Test execution results and coverage
• Backup verification (data and metadata)
• Rollback procedure documented
• Stakeholders notified
• Post-deployment validation steps
• Monitoring plan for 24-48 hours

Step 7: Execute Pre-Deployment Validation

Run a validation-only deployment to catch issues before actual deployment:

# Validate deployment without committing
sf project deploy validate \
  --manifest package.xml \
  --test-level RunLocalTests \
  --verbose

# Save the validation ID for quick deploy
sf project deploy start --use-most-recent-validation --async

Benefits of validation:

• Tests run in production environment
• Identifies environment-specific issues
• Generates Quick Deploy ID for faster deployment
• No changes committed until you confirm

Review validation results and address any failures before scheduling deployment.

Step 8: Prepare Rollback Plan

Document rollback procedures before deploying:

1. Backup current state

   sf project retrieve start --manifest package.xml --target-org production
   git tag pre-deployment-$(date +%Y%m%d) && git push --tags
   

2. Test rollback procedure in sandbox:

   • Deploy previous version of metadata
   • Verify functionality is restored
   • Document any data cleanup required

3. Establish rollback criteria:

   • Critical bugs found within 2 hours
   • Core functionality broken
   • Performance degradation >50%
   • Data integrity issues

See rollback procedures reference for detailed steps.

Post-Deployment Validation

After successful deployment, verify the release:

1. Smoke tests - Execute critical user workflows
2. Monitor logs - Check debug logs for errors (24-48 hours)
3. Query test data - Verify triggers and automation work correctly
4. User acceptance - Confirm with stakeholders functionality works
5. Performance check - Review governor limit usage in logs

Common Issues and Solutions

Issue: Test Coverage Drops Below 75%

Cause: New Apex classes added without sufficient tests.

Solution:

1. Run sf apex test run --code-coverage to identify gaps
2. Add test methods covering uncovered lines
3. Revalidate coverage

Issue: Validation Fails with "Component Not Found"

Cause: Missing dependency in package.xml.

Solution:

1. Review error message for missing component
2. Add component to package.xml
3. Retrieve component from source org if needed
4. Revalidate

Issue: Permission Errors After Deployment

Cause: FLS or object permissions not deployed correctly.

Solution:

1. Verify profiles/permission sets are in package.xml
2. Check that CustomObject metadata includes field permissions
3. Deploy profiles separately if needed
4. Use Permission Set Groups for complex permission hierarchies

Best Practices

1. Always validate before deploying - Never deploy directly to production without validation
2. Run full test suite - Use RunLocalTests, not NoTestRun
3. Deploy during maintenance windows - Minimize impact on users
4. Communicate with stakeholders - Notify before, during, and after deployment
5. Monitor post-deployment - Watch logs and user feedback for 24-48 hours
6. Document everything - Maintain deployment logs and decisions
7. Use version control tags - Tag releases for easy rollback

References

• Security Checklist - Detailed security review steps
• Dependency Resolution Guide - Solve dependency conflicts
• Rollback Procedures - Step-by-step rollback guide
• Deployment Checklist Template - Reusable checklist

Automation Opportunities

Consider automating this skill:

• CI/CD Integration - Run validation script in pipeline
• Scheduled Coverage Checks - Monitor test coverage daily
• Auto-generated Documentation - Create deployment notes from package.xml
• Slack/Email Notifications - Alert team of deployment status