CI Code Reviewer

CI Code Reviewer

Automated code review for CI pipelines. Designed to run inside GitHub Actions via openai/​codex-action, producing a single structured PR comment.

This skill extends .skills/​code-reviewer/​SKILL.md with CI-specific adaptations: no interactive prompts, PR description validation, manifest pre-checks, and concise output formatting for automated comments.

At activation, announce the skill name and scope in one line. Example: [ci-code-reviewer] reviewing PR #97.

See .skills/​review-anti-patterns.md for the shared rule set.

---

When to Use

Use this skill when:

• Running automated code review in GitHub Actions (Codex CI pipeline)
• Reviewing PRs that transition from draft to ready-for-review
• Performing non-interactive, autonomous code review

Do NOT use for:

• Interactive human-guided code review (use code-reviewer skill instead)
• Reviewing plans/​specs (use plan-reviewer skill)
• Implementation tasks

---

Required Context

Before starting the review, read:

1. AGENTS.md -- architecture boundaries and coding conventions
2. .skills/​code-reviewer/​SKILL.md -- severity model and review baseline

If any file is missing, note it in the output and continue with available context.

---

Severity Model (Use in PR Comments)

Classify findings using these levels, and include the level in each finding:

• Blocker: Merge must not proceed
• Must fix: Should be fixed before merge unless explicitly accepted as debt
• Should fix: Important, but can be deferred with clear rationale
• Nit: Ignore by default; mention only if specifically requested

Rule: avoid comment-only style polish and trivial corrections. Prefer high signal.

---

Review Process

Step 0: PR Description Validation (Mandatory)

This step is mandatory and must appear first in the output.

Check the PR description for:

1. Good explanation: WHAT changed and WHY it is needed.
2. OR link/​path to plan file: for example .quest/​*/​phase_01_plan/​plan.md or docs/​implementation/​....

If neither condition is met:

• Must fix: "PR description is missing. Add what/​why context or link to a readable implementation plan."

If description exists but is very thin (fewer than ~20 words, little context):

• Should fix: "PR description is sparse. Add more context about purpose and approach."

Step 0.1: Manifest Validation (Mandatory)

Run bash scripts/​quest_validate-manifest.sh.

• If it fails, flag Must fix with the failing file/​path details.
• If PR adds or renames files under Quest-managed paths, verify .quest-manifest is updated in the diff.

Step 0.5: Implementation Alignment

Verify that what the PR implements matches what it claims to do. Use the best available source of intent, in priority order:

1. Plan file referenced in PR description (preferred)
2. Acceptance criteria listed in PR description
3. PR description intent (what + why) if no explicit AC

Missing plan file is not a reason to skip alignment. Fall back to description.

Compare expectations vs diff:

• Expected deliverable missing from diff -> Must fix
• Out-of-scope file changes not justified by tests/​docs/​config support -> Should fix
• Missing explicit acceptance criteria in PR description -> Should fix

For each acceptance criterion:

• Automated criterion missing code/​test evidence -> Must fix
• Manual-only criterion -> mark manual - not verified
• Unclear from diff -> mark unclear - needs human review

If all criteria align, stay silent on this section.

Step 0.6: Existing Comment Fetch Budget

When fetching existing PR review comments before posting the CI review, use a bounded budget:

• interval_seconds = 20
• max_retries = 20
• Hard cap: 400 seconds (400-second cap, 20 seconds x 20 retries).

Stop when the fetch succeeds, a confirmed permission/​API failure occurs, or the budget is exhausted.

Step 1: Identify Changed Files and Scope

1. Run git diff --name-only <base>...<head>.
2. Run git diff --stat <base>...<head>.
3. Categorize changed files into:
   • Skills (.skills/, including .skills/​quest/)
   • AI roles/​config (.ai/)
   • Scripts (scripts/)
   • Workflows (.github/​workflows/)
   • Documentation (docs/, AGENTS.md, quest markdown artifacts)

Use these categories to decide which boundary checks and quality checks apply.

Step 2: Architecture Boundaries

Apply Quest boundaries from AGENTS.md:

• .skills/: skill definitions, review protocols, delegation docs
• .ai/: agent roles, templates, schemas, allowlist/​context config
• scripts/: validation and utility shell scripts
• .github/: CI and repository automation config (especially workflow orchestration)
• docs/: documentation and guidance, no executable logic

For each changed file, verify:

• Changes stay within directory responsibility
• No cross-layer leakage (for example: embedding workflow logic into docs)
• Dependencies and references are appropriate to the layer

Boundary violations are Must fix or Blocker depending on severity.

Step 3: Correctness and Contracts

Review for:

• Correct trigger/​behavior semantics
• Config contract compatibility
• Data/​config invariants
• Edge cases and failure semantics

Focus on behavior correctness, not style preferences.

Step 4: Security Hygiene

PR-focused checks:

• No secrets in code, logs, or responses
• No sensitive data in errors
• Input/​path validation at trust boundaries
• No hardcoded API keys or long-lived tokens

Secret leakage is always Blocker.

Step 5: Test Coverage (Map to Acceptance Criteria)

If acceptance criteria are available from Step 0.5:

1. Map each automated criterion to tests or validation evidence.
2. If missing, flag as Must fix.

For workflow/​config/​skill-only changes, acceptable evidence can include:

• bash scripts/​quest_validate-manifest.sh
• ./​scripts/​quest_validate-quest-config.sh
• Manual GitHub runtime verification steps when CI event behavior is required

If no criteria are available:

• Check that meaningful logic/​config changes include corresponding validation updates or explicit rationale. Missing validation -> Should fix.

Step 6: Code Quality and Maintainability

Review for clarity, maintainability, and consistency with existing patterns.

Markdown and YAML:

• Valid, consistent structure and headings
• Stable key names/​ordering when convention exists
• No ambiguous indentation or malformed frontmatter

Shell scripts:

• Safe quoting and robust conditionals
• Avoid unsafe globbing and unbounded command behavior
• Portability and clear error handling

JSON/​schema/​config integrity:

• Schema references and paths are valid
• Config keys are spelled correctly and supported
• New files are registered where required (.quest-manifest, skill index)

Apply minimal diff principle: smallest correct change, no speculative refactors.

---

Output Format

Keep output concise. Omit sections with no findings.

**PR Description:** PASS | FAIL - one-line explanation

**Summary:** 1-3 bullets. Recommendation: APPROVE / REQUEST CHANGES

**Findings** (only sections with issues):

**Blocker**
[N] Blocker - path:line - description and suggested fix

**Must fix**
[N] Must fix - path:line - description and suggested fix

**Should fix**
[N] Should fix - path:line - description and suggested fix

**Plan alignment** (only if gaps/​scope creep found): list issues
**Test gaps** (only if gaps found): list missing coverage
**Architecture** (only if violations found): list violations

Finding numbers are review-local indices. Use [N] format, increment in current-review order, and keep the number with the finding if it is converted to canonical JSON as review_local_index.

Line number guidance:

• Include path:line when the line comes from the diff.
• Otherwise use path alone.
• Do not guess line numbers.

Brevity rules:

• Clean review output should be short (PR description line + summary + APPROVE).
• Do not pad with empty PASS sections.
• Keep total output under 30 lines when possible.

Signature

Append this block at the end of every PR review comment:

<pre>
     ▐▛███▜▌
    ▝▜█████▛▘
      ▘▘ ▝▝
<agent name and model> in Collaboration with <github username>
</​pre>

Replace agent name/​model and github username with the actual values.

---

Principles

1. Correctness over style
2. Boundaries are enforced
3. Tests map to acceptance criteria
4. Security hygiene is non-negotiable
5. Minimal diff and high signal feedback
6. Autonomous operation (no interactive prompts)
7. Explicit severity on every finding