maestria-co/code-quality-rules

Code Quality Rules

Overview

Specifies assessment standards, issue severity rankings, and a systematic multi-pass inspection methodology. These guidelines govern evaluation of any codebase modification.

Assessment Standards

Code Hygiene: Purge all commented-out code blocks. Strip debug print statements. Never silently swallow exceptions—handle errors explicitly at every failure point. Never commit secrets—use environment variables. Choose descriptive identifiers consistently. Replace magic numbers with named constants. Apply the Don't Repeat Yourself principle rigorously.

Security Posture: Never expose sensitive data through logging or error messages. Validate and sanitize all untrusted input at system boundaries. Prevent SQL injection through parameterized queries exclusively. Apply output encoding to block XSS attacks. Ban eval() and related dynamic execution. Verify auth/authz implementation thoroughly—confirm authorization logic executes at the service tier, never solely in presentation layers. Keep credentials out of repositories. New API endpoints and data paths must enforce access restrictions. Changes touching authentication or authorization warrant heightened scrutiny—verify modifications don't accidentally broaden permissions.

Performance Characteristics: Eliminate N+1 query antipatterns. Release resources explicitly—close database connections, file handles, network streams. Move computationally expensive operations away from hot execution paths.

Test Coverage: New features require corresponding test cases. Assertions must verify genuine behavior, not merely mock presence. Include edge cases and failure scenarios in test suites. Avoid polluting production code with test-only methods. When altering decision logic, verify presence of the standardized Coverage Evidence Block from testing-discipline. Consider this coaching guidance: flag missing evidence as developmental feedback, not automatic rejection.

Verification Evidence: Confirm build and test execution actually occurred—demand output artifacts or reproducible steps, never accept assumptions.

Maintainability Factors: Limit method length to reasonable bounds. Manage cyclomatic complexity actively. Preserve clear responsibility boundaries between components. Prevent circular dependency graphs.

Severity Classifications

Critical Priority: Security vulnerabilities, data corruption risks, runtime crashes, breaking modifications to public contracts, faulty business logic implementation.

Moderate Priority: Performance degradation, absent error handling, missing test coverage for critical paths, departure from established architectural patterns.

Minor Priority: Style inconsistencies beyond linter scope, documentation enhancement opportunities, discretionary refactoring suggestions.

Focused Review Methodology

Execute comprehensive reviews through multiple targeted inspection passes rather than attempting omniscient single-pass review. Each pass concentrates on a specific quality dimension to prevent oversight.

Pass 1: Logic & Correctness

• Does implementation fulfill stated requirements?
• Are boundary errors, null scenarios, or timing hazards present?
• Do error paths receive handling equal to success paths?
• Does execution flow align with intended semantics?

Pass 2: Security & Trust Perimeter

• Does input validation occur before consumption?
• Does authorization enforcement happen at service boundaries (not UI only)?
• Are credentials, tokens, and PII handled securely (never logged, never exposed)?
• Do newly introduced endpoints and data access channels enforce access policies?
• Are database queries parameterized? Is output properly encoded?

Pass 3: System Integration & Ripple Effects

• How do these modifications interact with surrounding code?
• Could unintended consequences affect dependent components?
• Do shared utility changes propagate correctly to consumers?
• Can database schema changes support backward compatibility?
• Can API modifications preserve existing contracts?

Pass 4: Clarity & Long-term Sustainability

• Could an unfamiliar developer comprehend this without external documentation?
• Are identifiers meaningful and consistent with project conventions?
• Is complexity warranted, or could simpler approaches achieve identical outcomes?
• Are unexplained literal values, cryptic abbreviations, or deceptive names present?

Pass 5: Substantiation & Scope Adherence

• Did the author execute build processes and provide tangible evidence?
• Do tests exist for new functionality with assertions verifying actual behavior?
• Are specification requirements comprehensively addressed?
• Does scope creep introduce changes beyond stated objectives?

Appropriate Pass Selection

Complete multi-pass inspection: New feature development, cross-module modifications, security-critical code, public interface changes.

Condensed inspection (Passes 1, 4, 5 exclusively): Isolated bug fixes, documentation updates, configuration adjustments, test augmentations.

Review output should employ the standard Findings taxonomy (Critical / Moderate / Minor), annotating which pass surfaced each finding—this contextualizes the issue category for the author.