Maintaining Quality Discipline in AI-Assisted Development

A Note to the Reader

This guide completes the trilogy that began with Human-AI Planning and continued with Human-AI Task Creation. Those guides covered how to plan work and create execution-ready tasks. This one covers what happens after execution: verification, quality gates, and commit discipline.

The core metaphor here comes from technical rock climbing, and it changed how I think about software quality.

The Technical Climbing Metaphor

In technical rock climbing, climbers place protection (pitons, cams, nuts) as they ascend. If they fall, they only fall to their last protection point - not to the ground.

In software development:

• Protection = Verified, tested, documented work
• Climbing = Making progress on features and fixes
• The Route = Your software's evolution over time

The Core Principle

Once protection is placed, quality can only remain stable or improve - never degrade.

This is the "quality ratchet." It only moves one direction: up.

The Four Rules of Technical Climbing

Rule 1: Document and Test Immediately

When something works → Document it NOW
When you verify a fix → Add a regression test NOW
When you learn something → Capture it NOW

Never think "I'll document this later" or "I'll add tests later." Later means lost. Later means you might fall below this point.

Rule 2: Protection Before Progress

Before starting new work:

• Review existing tests and documentation
• Understand the current protection points
• Plan to climb FROM there, not around it

Don't start new features if existing tests are failing. You're climbing from an unprotected position.

Rule 3: No Backward Movement

If something seems worse than before:

• STOP immediately
• Check the tests - what's failing?
• Find where you departed from the protected route
• Return to the last known-good state

Quality going backward is a fall. Protection points exist to catch you.

Rule 4: Every Session Climbs

Each work session must:

• Start from a verified, documented position
• Add at least one protection point (test, documentation, verification)
• Leave the codebase better than you found it

No session should end with quality lower than when it started.

Quality Gates: Your Protection Points

The Commit Gate Checklist

Before committing ANY code:

Build Verification

• Code builds cleanly
• No compilation warnings or errors
• No linter warnings

Test Verification

• All existing tests pass
• New tests added for new functionality
• No skipped or stubbed tests left behind

Documentation

• Code comments where behavior isn't obvious
• API documentation updated if applicable
• README updated if user-facing

Commit Quality

• Commit message explains WHAT and WHY
• All related files included
• No unrelated changes bundled in

The Anti-Patterns

DON'T:

• Commit with "will fix tests later"
• Leave stubbed tests in place
• Skip documentation "for now"
• Commit with "WIP" or incomplete work
• Use git add . without reviewing what you're adding

DO:

• Complete all aspects before committing
• Fix issues immediately, not later
• Review git status before every commit
• Make each commit a complete, verified unit of work

The Regression Testing Mandate

Zero Tolerance Principle

ALL test failures are blocking issues.

There is no prioritization of test failures (Critical vs High vs Medium). If a test fails, work stops until it passes. You don't climb past failing protection.

The Quality Ratchet in Practice

1. Once a test exists, it's permanent
   • Tests don't get deleted because they're inconvenient
   • Tests don't get skipped because they're slow
   • Tests don't get ignored because "we know about that issue"
2. Coverage only improves, never degrades
   • Each bug fix adds a regression test
   • Each new feature adds tests
   • The test suite grows; it never shrinks
3. Every failure creates protection
   • Find a bug? Write a test that catches it
   • That test becomes permanent protection
   • Future changes that reintroduce the bug will fail immediately

The Golden Rule

Never let a human test a system that hasn't passed automated validation.

Automated tests are the quality gate that protects human time. Only verified systems reach manual testing.

The Test-First Bug Fix Workflow

When you discover a bug, resist the urge to immediately fix it. Instead, follow this discipline:

The Three-Step Protocol

1. REPRODUCE → Write a test that confirms the bug exists
   - The test MUST FAIL (proving the bug is real)
   - This test captures the exact failure condition

2. FIX → Implement the correction
   - Make the minimal change needed
   - Don't refactor while fixing

3. VERIFY → Run the test again
   - The test MUST PASS (proving the fix works)
   - The test becomes permanent protection

Why Test First?

• The test proves the bug exists. Without a failing test, you might be fixing the wrong thing or chasing a phantom. A failing test is objective evidence.
• The test proves the fix works. When the test passes, you have proof - not hope, not assumption, but verified proof that the specific failure condition is now handled.
• The test prevents regression. That test stays in your suite forever. If anyone ever reintroduces this bug through future changes, the test catches it immediately.

Example in Practice

Human: "There's a bug - users can submit empty forms"

AI: "Let me first write a test that submits an empty form
     and expects rejection..."

[Test written - runs - FAILS as expected]

AI: "Test confirms the bug. Now implementing validation..."

[Fix implemented]

AI: "Running the test again..."

[Test PASSES]

AI: "Bug fixed and permanently protected. The test ensures
     empty form submission will always be caught."

The Climbing Connection

In the climbing metaphor, the failing test is you identifying where protection is needed. You don't climb past an unprotected section and hope for the best - you place protection first.

The test-first workflow means: protection before the fix, not after.

Commit Discipline

Surgical Commits

Critical Rules:

• NEVER: git add . or git add -A (commits everything blindly)
• ALWAYS: Specify exact file paths
• NEVER: Bundle unrelated changes
• ALWAYS: Review git status before commit

Each commit should be:

• Complete - All related changes included
• Verified - All tests pass
• Documented - Commit message explains the change
• Atomic - One logical change per commit

Good Commit Messages

Fix null pointer exception in authentication handler

The response object wasn't checked for null before accessing
the data property. Added null check and regression test.

Verified: All tests pass, including new regression test.

Bad Commit Messages

Fixed stuff
Work in progress
Updated files
Bug fix

These tell you nothing and provide no protection.

The Three Wrap Levels

Different completion points require different verification:

Daily Wrap (End of Session)

• Current work is in a stable state
• Tests pass for what's implemented
• Progress is documented
• You can resume tomorrow without confusion

Feature Wrap (Completing a Feature)

• All feature requirements implemented
• Full test coverage for the feature
• Documentation complete
• Ready for integration

Release Wrap (Shipping to Users)

• 100% of tests pass
• Full regression suite green
• All documentation current
• No known issues deferred
• Complete verification performed

Working with AI: Quality Collaboration

AI as Quality Partner

Your AI assistant should help maintain the quality ratchet:

1. During Planning
   • AI helps identify what tests will be needed
   • AI researches existing patterns to follow
   • AI asks about verification criteria
2. During Execution
   • AI writes tests alongside implementation
   • AI follows established patterns
   • AI doesn't skip steps "for speed"
3. Before Commit
   • AI runs all tests
   • AI verifies the build
   • AI helps write complete commit messages

Quality Phrases for AI Collaboration

• "Make sure all tests pass" → AI runs full test suite, reports results
• "Add a regression test for this" → AI creates a test that catches this specific issue
• "Don't skip the verification" → AI completes all quality gates before marking done
• "What protection have we added?" → AI summarizes new tests and documentation

The Philosophy in Practice

Starting a Session

1. Check current state
   • Do all tests pass?
   • Is the build clean?
   • What was the last protection point?
2. Verify you're climbing from solid ground
   • If tests are failing, fix them first
   • Don't start new work from an unstable position
3. Plan what protection you'll place
   • What tests will you add?
   • What documentation will you create?

Ending a Session

1. Place your protection
   • Run all tests
   • Commit verified work with good messages
   • Document what you learned
2. Verify you climbed higher
   • Is the codebase better than when you started?
   • Are there more tests than before?
   • Is documentation more complete?
3. Leave good anchor points
   • Clear state for next session
   • No half-done work lingering
   • No "I'll fix it tomorrow" items

Key Quotes to Remember

"The best developers aren't the ones who never introduce bugs. They're the ones who place good protection so bugs can't break the system."

"Documentation isn't overhead - it's protection. Every document you write is a piton. Every test you create is a cam. Together, they ensure you can only climb higher."

"When in doubt: Test it. Document it. Protect it."

Quick Reference

Before Any Commit

• Build passes
• All tests pass
• No skipped tests
• Documentation updated
• Commit message complete

The Quality Ratchet

• Tests only increase, never decrease
• Coverage only improves
• Documentation only grows
• Each session leaves code better

The Four Rules

1. Document and test immediately
2. Protection before progress
3. No backward movement
4. Every session climbs

Test-First Bug Fixing

1. Write test that reproduces bug (FAILS)
2. Implement the fix
3. Run test again (PASSES)
4. Commit fix AND test together

The Core Principle

Once protection is placed, quality can only remain stable or improve - never degrade.