spec-aware-pr-review

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Spec-Aware PR Review

Review a pull request against both code quality and the complete timeline of related specifications.

For eligible PRs, always submit the final review as `APPROVE`. Inline comments may identify required fixes or serious issues, but this skill must never submit `REQUEST_CHANGES`.

## Core Rule

Check PR eligibility before doing any review work. If the PR is merged or draft, ignore it: do not run `$code-review`, do not inspect specs, do not publish inline comments, do not publish a global comment, and do not submit any review state.

For eligible PRs, start with `$code-review` when available. Treat its findings as initial input only.

Do not publish comments until each finding has been validated against the related specification history. Discard findings that the spec timeline proves intentional, and add findings that arise from spec or timeline inconsistencies even when `$code-review` missed them.

## Workflow

### 1. Check PR Eligibility

Before reviewing or commenting, determine the PR state from the platform.

Skip the PR when:

- the PR is already merged
- the PR is closed as merged
- the PR is in draft state
- the platform reports `isDraft: true`
- the platform reports `merged: true` or equivalent

When skipping, return only a short local status note such as:

```text
Skipped: PR is draft, so spec-aware review comments were not posted.
```

or:

```text
Skipped: PR is already merged, so spec-aware review comments were not posted.
```

Do not post that skip note to the PR unless the user explicitly asks.

### 2. Run Base Review

Run the standard code review workflow first.

Use its results to seed the review, then continue with spec-aware validation before publishing anything.

### 3. Identify Related Specs

Find the primary specification associated with the PR.

Search:

- PR title and description
- linked issues, tickets, and project-management metadata
- branch name and commit messages
- code comments and documentation
- spec directories and feature docs
- references containing `spec`, `RFC`, `ADR`, `proposal`, `design`, `requirement`, or `acceptance criteria`

If several specs are relevant, choose one primary spec and keep the others as related context.

### 4. Build The Spec Timeline

Do not evaluate the PR using only the newest spec.

Inspect the primary spec for references to:

- earlier or superseded specs
- amended requirements
- related RFCs or ADRs
- mapped functionality
- earlier implementations of the same capability
- migration plans and rollout phases
- compatibility requirements
- deprecations
- known constraints
- decisions intentionally preserved or reversed

Follow references recursively until the relevant decision history is understood.

Create a chronological working timeline with available:

- date
- spec id or title
- status
- functionality introduced
- behavior changed
- constraints added or removed
- decisions superseded
- compatibility expectations
- migration or rollout requirements

When specs conflict, prefer the most recent explicit decision unless it says an earlier requirement remains authoritative. Do not assume a newer spec silently invalidates an older one. Treat earlier behavior as relevant when the newer spec extends it, depends on it, preserves compatibility with it, or does not explicitly replace it.

### 5. Review Against Full Context

Evaluate the PR against:

- current spec and acceptance criteria
- spec timeline and historical decisions
- existing mapped functionality
- backward-compatibility expectations
- migration and rollout constraints
- established architecture patterns
- tests and expected edge cases
- `$code-review` findings

Check especially for:

- missing requirements
- regressions against prior specs
- partial implementation of a multi-phase design
- behavior contradicting a preserved constraint
- duplicated functionality already introduced by another spec
- incompatible workflow changes
- missing migrations, feature flags, observability, or fallback behavior
- incomplete tests

From lucasbayma/skills, MIT.

More from lucasbayma/skills