alignment-review_skill

Overview

This skill reviews code changes for bugs and for alignment with OpenEnv design principles and RFCs. It runs automated hooks, inspects relevant docs and RFCs, and produces a two-tier report that separates immediate fixes from alignment discussion items. The output is a concise, actionable Alignment Review Report suitable for PRs or pre-commit checks.

How this skill works

The skill runs the lint and debug-check hooks, scans PRINCIPLES.md and INVARIANTS.md, and enumerates RFC files under rfcs/ noting their status. It analyzes a git diff (or provided diff) to surface mechanical problems (Tier 1) and to flag potential principle or RFC conflicts (Tier 2). Tier 2 flags include a suggested reviewer based on document authorship and git blame heuristics.

When to use it

• When reviewing a pull request touching the interface library or environments
• Before committing non-trivial changes that affect design or API
• When an RFC is in Draft or In Review and code changes may overlap
• As part of CI to block regressions that violate principles or invariants
• When asked to produce a clear alignment report for team discussion

Best practices

• Run automated hooks first and resolve all Tier 1 items before discussion
• Always reference the specific principle or RFC in Tier 2 flags
• Include contextual git blame or author suggestions for each alignment flag
• Keep Tier 1 fixes minimal and deterministic (lint, debug, syntax, security)
• Treat RFC conflicts as discussion starters, not final judgments

Example use cases

• A PR adds new environment reward helpers—detects possible violation of “rewards belong in environment” principle
• A refactor changes client/server boundaries—flags client importing server code
• A change touches an area covered by a Draft RFC—lists that RFC and asks for discussion
• Pre-commit hook runs and reports lint and debug statement failures to be fixed before merge
• CI job generates the Alignment Review Report to attach to a PR