Validation Commands to Run Before Pushing Changes in AI Engineering From Scratch

Run python3 scripts/audit_lessons.py to validate lesson structure and test coverage, followed by python3 scripts/check_readme_counts.py --fix to synchronize the README lesson counts before every push.

Before committing changes to the AI Engineering From Scratch curriculum, contributors must execute specific validation commands that ensure structural integrity and documentation consistency. These pre-push checks, defined in the repository's AGENTS.md, enforce the same standards as the CI pipeline and prevent common errors like mismatched lesson counts or missing required files from reaching the main branch.

Essential Pre-Push Validation Commands

The repository requires two core validation steps that mirror the audit and readme-counts-sync CI jobs. Running these locally catches discrepancies before submission.

Run the Curriculum Audit

The scripts/audit_lessons.py script performs a comprehensive walkthrough of every lesson under the phases/ directory. It validates that each lesson contains required files, verifies front-matter consistency, and executes unit test suites to ensure code quality.

Specifically, the audit verifies:

• docs/en.md exists with valid YAML front-matter matching the implementation language
• code/main.* runs without errors and exits with status 0
• code/tests/ contains a minimum of 5 unit tests that all pass
• quiz.json and other metadata files are present and properly formatted

Execute the full curriculum audit from the repository root:

python3 scripts/audit_lessons.py

Synchronize README Lesson Counts

The scripts/check_readme_counts.py script parses the generated curriculum catalog and reconciles the lesson table in README.md. This ensures the displayed statistics accurately reflect the true state of the repository.

Check for count discrepancies:

python3 scripts/check_readme_counts.py

Automatically fix any drift detected in the README:

python3 scripts/check_readme_counts.py --fix

Complete Pre-Push Validation Workflow

For comprehensive validation before pushing changes, execute these commands in sequence:

# 1. Verify lesson structures and run all test suites

python3 scripts/audit_lessons.py

# 2. Check README synchronization (dry run)

python3 scripts/check_readme_counts.py

# 3. Auto-fix README if counts are outdated

python3 scripts/check_readme_counts.py --fix

This workflow guarantees that your changes will pass the continuous integration checks and maintain curriculum consistency across all phases.

Lesson-Level Validation for Targeted Changes

When modifying a specific lesson, run targeted validation within that lesson's directory rather than the full curriculum audit. Navigate to the lesson's code directory and verify both execution and test coverage:

# Example: Validating a specific lesson edit

cd phases/05-phase-nn/12-some-lesson/code

# Verify the implementation executes successfully

python3 main.py

# Run the lesson's unit test suite with verbose output

python3 -m unittest discover tests -v

Successful validation requires main.py to exit with status 0 and all unit tests to pass.

What the Validation Scripts Verify

Understanding the specific checks helps interpret validation failures. The scripts/audit_lessons.py script enforces structural requirements across these critical paths:

• phases/*/*/docs/en.md – Documentation files containing front-matter that must align with the lesson's programming language
• phases/*/*/code/main.* – Primary implementation files that must execute without runtime errors
• phases/*/*/code/tests/ – Directories containing unittest frameworks with comprehensive coverage
• README.md – The top-level catalog kept synchronized by check_readme_counts.py

These validations ensure that the curriculum remains structurally sound, fully tested, and accurately documented for learners.

Summary

• Run python3 scripts/audit_lessons.py before every push to validate lesson structure, required files, and test suites across all phases in the phases/ directory.
• Execute python3 scripts/check_readme_counts.py to verify README accuracy, applying the --fix flag to automatically update lesson counts when drift is detected.
• Validate individual lessons locally by running main.py and python3 -m unittest discover tests -v within the specific lesson's code/ directory when making targeted changes.
• These commands align with the CI jobs defined in AGENTS.md and prevent structural errors from breaking the main branch build.

Frequently Asked Questions

What happens if I skip the validation commands before pushing?

The CI pipeline will fail during the audit or readme-counts-sync jobs if you bypass local validation. Common failures include mismatched lesson counts in the README, missing required files like quiz.json or docs/en.md, or unit test failures in specific lessons. Running these commands locally catches issues before they trigger CI failures.

How do I fix README count discrepancies automatically?

Use the --fix flag with the README check script: python3 scripts/check_readme_counts.py --fix. This updates the lesson table in README.md to reflect the current state of the phases/ directory, eliminating manual count updates and reducing documentation errors.

Can I validate just one lesson instead of the entire curriculum?

Yes. Navigate to the specific lesson's code directory (for example, phases/03-phase-example/07-new-lesson/code) and run python3 main.py followed by python3 -m unittest discover tests -v. This targeted approach validates execution and test coverage without running the full curriculum audit, saving time during iterative development.

What files must every lesson include to pass the audit?

According to scripts/audit_lessons.py, each lesson directory must contain: docs/en.md with valid front-matter, code/main.* (the implementation file), a code/tests/ directory with at least 5 unit tests, and quiz.json. The audit validates both file existence and content integrity, ensuring consistent curriculum quality across all phases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}