Pr Standards Gate

PR Standards Gate Skill

Verify that code changes comply with documented standards before approving a pull request.

Context

You're reviewing a PR and need to ensure that the code changes follow the project's documented standards. This is the manual verification step that happens after automated checks pass.

Domain Context

The PR Gate ceremony has both automated checks (run by CI) and manual review (done by humans). This skill covers the manual review portion.

Standards can apply at different levels:

• Code-level standards (e.g., typescript.md, error-handling.md) — checked against the actual code
• Architecture standards (e.g., package boundaries) — checked at a system level
• Documentation standards (e.g., docs must be current) — checked against changed docs
• Process standards (e.g., agent context updates) — checked against CLAUDE.md/AGENTS.md

Reference: levels/L2-ceremonies/ceremonies/pr-gate.md#Manual Review Checklist

Instructions

1. Identify changed files — Get the list of files modified in the PR

   • Review the PR diff or run: git diff main...<branch> --name-only
   • Separate into categories: code files, docs, config, agent files
   • Deliverable: Categorized list of changed files

2. Map files to applicable standards — Which standards apply?

   • For each file, determine which standards document rules that apply
   • Example: src/api/server.ts → docs/standards/engineering/api-design.md and typescript.md
   • Create a file-to-standards mapping for this PR
   • Deliverable: Mapping of changed files to applicable standards

3. Read each applicable standard — Understand what the standard requires

   • For each standard from step 2, read the full document
   • Pay special attention to the Rules section
   • Note any [CUSTOMIZE] exceptions that might apply
   • Deliverable: Understanding of what each standard requires

4. Check changes against rules — Verify code follows each standard

   • For each file + standard pair, review the actual code changes
   • Check: Does the code follow all the rules in the standard?
   • If violation found, note the exact rule and the line(s) that violate it
   • Consider context: Is this an intentional exception documented in the PR?
   • Deliverable: List of violations (if any) or approval that all changes comply

5. Verify agent context updated if needed — Check that CLAUDE.md/AGENTS.md stay in sync

   • If code architecture changed, was CLAUDE.md updated?
   • If deployment/ops approach changed, was AGENTS.md updated?
   • If new standards were documented, are they wired into context files?
   • Deliverable: Confirmation that agent context is up to date

6. Report violations with specific fixes — If issues found, guide the PR author

   • For each violation, provide: Standard file + rule, What the code does, What the standard requires, Specific fix with code example
   • Use this format in your PR review comment:

     Found violation in src/api.ts:42
     Standard: docs/standards/engineering/api-design.md#Validation
     Current: function accepts data: any
     Required: All function params must have types
     Fix: Change to: function process(data: ValidRequest)
     

   • Deliverable: Clear review comments with fixes

Anti-Patterns

1. Rubber-stamping the checklist — Going through motions without real review

   • Wrong: "✓ Code follows standards" without actually reading the standards
   • Right: Read the applicable standards, review code against each rule
   • Impact: Non-compliant code gets merged
   • Guard: If you can't cite the specific rule and explain the violation, don't approve

2. Checking only the diff without reading the standard — Missing context

   • Wrong: Looking at line 42 changed without understanding what standard.md says about this code
   • Right: Read the standard first, then review code
   • Impact: You miss violations that don't show up obviously in the diff
   • Guard: Always read the complete standard section, not just the changed lines

3. Treating all violations equally — Missing severity differences

   • Wrong: Same review weight for "missing comment" vs "security vulnerability"
   • Right: Categorize: ERROR (blocks merge), WARN (should fix), INFO (nice to fix)
   • Impact: Important issues get lost among style nitpicks
   • Guard: Only block merge on ERROR violations; suggest fixes for WARN/INFO

4. Flagging violations without citing a standard — Creates disputes

   • Wrong: "This code isn't clean enough"
   • Right: "This violates docs/standards/engineering/code-quality.md#Readability rule 2"
   • Impact: PR author can't understand what rule they violated
   • Guard: Every violation must reference a specific standard file and section

Further Reading

• levels/L2-ceremonies/ceremonies/pr-gate.md — Full PR Gate ceremony
• levels/L1-context/library/ — Reference standards for common categories
• levels/L3-enforcement/agents/standards-enforcer.md — Automated enforcement equivalent