How the Five Axes of Code Review Function in the code-review-and-quality Skill

The code-review-and-quality skill evaluates every change across five distinct axes—Correctness, Readability & Simplicity, Architecture, Security, and Performance—providing concrete questions and severity classifications to ensure comprehensive code quality.

The addyosmani/agent-skills repository contains a structured code-review-and-quality skill that transforms subjective code review into an objective, repeatable process. By examining changes through the five axes of code review, reviewers can systematically assess functional behavior, maintainability, system design, security posture, and runtime efficiency. This methodology is defined in skills/code-review-and-quality/SKILL.md and provides specific line ranges for each axis’s evaluation criteria.

The Five Axes Defined

The framework organizes review criteria into five independent dimensions. According to the source code in skills/code-review-and-quality/SKILL.md, each axis occupies a specific section with targeted review questions:

Correctness: Verifying Behavioral Accuracy

The Correctness axis ensures code behaves exactly as intended according to specifications. Defined in lines 26‑35, this axis asks whether the implementation meets the spec, handles edge cases like null values and boundary conditions, covers error paths, and verifies that tests actually validate the right behavior. Reviewers specifically check for off-by-one errors, race conditions, and state management issues that could cause subtle failures.

Readability & Simplicity: Ensuring Maintainability

The Readability & Simplicity axis validates whether another engineer can understand the code without the author’s explanation. As documented in lines 36‑48, this dimension examines whether variable names are descriptive and consistent, control flow is straightforward, and the code is logically organized. Reviewers verify that "clever" tricks are avoided, abstractions justify their complexity, comments only explain non-obvious intent, and dead code is removed.

Architecture: Validating System Design

The Architecture axis determines whether changes fit the system’s long-term design and structure. Located in lines 49‑58, this axis checks if the change follows existing patterns or introduces justified new ones, preserves module boundaries, consolidates duplicated code, avoids circular dependencies, and maintains appropriate abstraction levels without over-engineering or excessive coupling.

Security: Identifying Vulnerabilities

The Security axis screens for potential security flaws and attack vectors. Defined in lines 59‑70, this axis requires validation that user input is sanitized, secrets remain outside code and logs, authentication and authorization checks are present where required, SQL queries use parameterization, and outputs are encoded to prevent XSS. Reviewers also verify that third-party dependencies are trusted and updated, and that external data is treated as untrusted at system boundaries.

Performance: Detecting Runtime Inefficiencies

The Performance axis identifies degradations in runtime efficiency or resource usage. As specified in lines 72‑82, this axis checks for N+1 query patterns, unbounded loops, unconstrained data fetches, unnecessary synchronous operations that could be async, and UI components with excessive re-renders. Reviewers confirm that list endpoints implement pagination and that large objects are avoided in hot execution paths.

Applying the Five Axes in Practice

During a review, the reviewer walks through modified files with these five axes in mind, marking observations with severity levels. The skill defines Critical issues as blockers requiring immediate resolution, Nit items as minor suggestions, and Optional feedback as nice-to-have improvements.

Review Checklist Template

Below is a practical markdown checklist that maps directly to the five axes defined in skills/code-review-and-quality/SKILL.md:

## Review: Add user‑profile endpoint

### Correctness

- [ ] Matches spec: returns user data for valid IDs
- [ ] Handles null/empty ID
- [ ] Returns error for non‑existent user
- [ ] Tests verify correct behavior and edge cases

### Readability

- [ ] Variable names are clear (`userId`, `profileData`)
- [ ] No nested ternaries or deep callbacks
- [ ] Comments only for non‑obvious intent

### Architecture

- [ ] Uses existing `services/user` module
- [ ] No new circular imports introduced
- [ ] Duplicated logic consolidated

### Security

- [ ] Input `userId` is validated as UUID
- [ ] No secrets logged
- [ ] SQL query is parameterized

### Performance

- [ ] No N+1 queries when fetching related data
- [ ] Pagination added for list endpoints

Annotating Findings with Severity

When commenting on specific lines, reviewers use severity labels to indicate priority:

**Critical:** The SQL query concatenates `userId` directly – opens to injection.
**Nit:** Variable `tmp` could be renamed to `profileData` for clarity.
**Optional:** Consider extracting the validation logic into `utils/validation.ts`.

Summary

• The five axes of code review provide a multi-dimensional framework for evaluating code changes beyond superficial syntax checks.
• Each axis targets a specific quality attribute—Correctness (lines 26‑35), Readability & Simplicity (lines 36‑48), Architecture (lines 49‑58), Security (lines 59‑70), and Performance (lines 72‑82)—with concrete review questions.
• Reviewers apply these axes systematically to every modified file, classifying findings using Critical, Nit, and Optional severity levels.
• The methodology is implemented in skills/code-review-and-quality/SKILL.md within the addyosmani/agent-skills repository.

Frequently Asked Questions

What are the five axes of code review in the code-review-and-quality skill?

The five axes are Correctness, Readability & Simplicity, Architecture, Security, and Performance. Each axis evaluates a distinct quality dimension with specific review questions, such as checking for edge cases under Correctness or scanning for SQL injection vulnerabilities under Security.

How does the Security axis prevent vulnerabilities?

The Security axis defined in lines 59‑70 of skills/code-review-and-quality/SKILL.md requires reviewers to verify that user input is validated and sanitized, secrets are excluded from code and logs, SQL queries use parameterization, outputs are encoded to prevent XSS, and third-party dependencies are trusted and current.

Where are the five axes defined in the addyosmani/agent-skills repository?

The five axes are defined in skills/code-review-and-quality/SKILL.md in the addyosmani/agent-skills repository. Each axis occupies a specific line range: Correctness (26‑35), Readability & Simplicity (36‑48), Architecture (49‑58), Security (59‑70), and Performance (72‑82).

What severity labels should reviewers use when applying the five axes?

According to the skill documentation, reviewers should classify observations as Critical (blocking issues), Nit (minor style or preference suggestions), or Optional (nice-to-have improvements). This labeling system ensures feedback is actionable and prioritized appropriately.

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