Two-Axis Diff Review: Standards vs Spec

Where this fits

You've just finished a feature branch and want a second pair of eyes before opening a PR. Or you're mid-sprint and need a sanity check on WIP changes. The x-review skill steps in when you need a structured diff review that separates two questions: Does this code follow our repo standards? and Does it match the intended spec? Instead of a generic "look at this diff" prompt, x-review forces a fixed comparison base, pulls the right spec sources, and produces a report that keeps the axes separate—so you can act on each independently.

Why agents benefit

• Enforces a verified base: The skill asks for and validates git rev-parse and a non-empty diff, so the agent never reviews an ambiguous range.
• Resolves spec sources deterministically: It checks commit references, user-supplied paths, then known brief locations—no guessing about what the intended behavior is.
• Filters standards to what matters: It skips linter/formatter-enforced rules and focuses on judgment-call smells that appear in the actual diff, reducing noise.
• Produces a structured, two-axis report: The output format separates Standards and Spec findings with a summary of worst issues, making it easy to prioritize fixes.
• Works in a single session: No parallel sub-agents or orchestration overhead—just one focused pass, which keeps context tight and costs predictable.

Practical scenarios

Pre-PR review on a feature branch

You're about to open a PR against main. The agent runs x-review with base main, picks up the PRD from docs/specs/, and returns a list of standards violations (e.g., a magic number that should be a constant) plus spec deviations (e.g., missing error handling for an edge case the spec calls out). You fix both before anyone else looks.

WIP check after a long refactor

You've been refactoring for two days and want to know if you've drifted from the original API contract. Point the skill at HEAD~10 as the base, and it scans for spec mismatches in changed function signatures and return types, while also flagging duplicated logic introduced during the move.

Onboarding to a new codebase

You're new to a repo and need to contribute quickly. The skill reads CODING_STANDARDS.md and AGENTS.md, applies those rules to your first diff, and tells you exactly where your code style deviates—before a human reviewer has to point it out.

Add it to your agent workflow

Install via npx:

npx skills add Fromlan/X-agent --skill x-review

Then use it in a conversation like:

Review the diff from main to HEAD using x-review. Base is main.

The agent will confirm the base, locate a spec if available, run the review, and output the standard two-axis markdown report.

Compare before adopting

Before making x-review a regular part of your loop, compare it against alternatives. Check whether the skill's output quality matches your expectations—run it on a known diff and see if the findings are specific and actionable. Look at the repository's maintenance freshness (last commit, open issues, response to feedback). Consider other diff-review skills that might use parallel agents or different output formats. Finally, assess workflow fit: does the two-axis separation align with how your team reviews, or would a merged list be more practical? The skill is young (25 stars), so verify it works for your repo's conventions.

Why it is worth tracking

x-review is a focused, opinionated take on diff review that avoids the common pitfall of mixing style nits with functional gaps. Its single-agent design keeps costs low and output predictable, and its explicit spec-source resolution is a thoughtful touch. While it's early, the approach is sound and worth evaluating as your agent tooling matures. Keep an eye on its GitHub activity and community feedback—if it gains traction, it could become a staple for structured code review. For a broader view of agent skills in this space, see OpenAgentSkill for more context and related options.