Skip to content
Skills Library
Programming · Review & audit

compare-to-codebase

/compare-to-codebase

Use when reviewing an RFC that proposes code changes. Reads the RFC, then reads the actual repository at the PR head ref, and flags every factual claim the proposal makes about the codebase that the code contradicts or omits. Output stays in chat – the user types any feedback into GitHub themselves.

Repository
rfc123 ↗
Licence
MIT
Last repository change
29.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when reviewing an RFC that proposes code changes. Reads the RFC, then reads the actual repository at the PR head ref, and flags every factual claim the proposal makes about the codebase that the code contradicts or omits. Output stays in chat – the user types any feedback into GitHub themselves.

Original author description

Use when reviewing an RFC that proposes code changes. Reads the RFC, then reads the actual repository at the PR head ref, and flags every factual claim the proposal makes about the codebase that the code contradicts or omits. Output stays in chat – the user types any feedback into GitHub themselves.

How it works

  1. When to use
  2. Process
  3. What not to do
Original SKILL.md headings · 91 lines, 602 words
SKILL.md preview
---
name: compare-to-codebase
description: Use when reviewing an RFC that proposes code changes. Reads the RFC, then reads the actual repository at the PR head ref, and flags every factual claim the proposal makes about the codebase that the code contradicts or omits. Output stays in chat – the user types any feedback into GitHub themselves.
allowed-tools:
  - mcp__rfc123__rfc123_get_rfc
  - mcp__rfc123__rfc123_get_rfc_comments
  - mcp__rfc123__rfc123_list_review_threads
---

# compare-to-codebase

The most common reviewer failure mode is taking an RFC's claims about the
current codebase at face value. This skill grounds the review in the actual
code. **Output stays in chat.** Any feedback the user wants to leave on the
RFC, they type into GitHub themselves – in their own voice.

## When to use

The user is reviewing an RFC that proposes code changes and says "check this
against the code", "is this accurate?", "what does the code actually do?",
or simply "review this RFC." Skip for non-code RFCs (process, org, policy).

## Process

1. **Read the RFC.** Call `rfc123_get_rfc`. Note the `headRef` field – that's
   the PR's head branch, the canonical version of the code the proposal
   refers to. Also note the `path` of each entry in `files` (a PR can carry
   several markdown documents) and which repo this RFC lives in.

2. **Read the existing discussion.** Call `rfc123_get_rfc_comments` and
   `rfc123_list_review_threads`. Don't re-raise points already on the table.

3. **Inventory the codebase claims.** Walk the RFC body and pull out every
   factual claim about the *current* state of the code:
   - "File X does Y today"
   - "We currently use library Z"
   - "Function `foo()` returns A"
   - "There is no existing support for B"
   - "The schema for table T has columns C, D, E"
   - Dependency / version claims
   - Behavior under specific edge cases

   Skip claims about the *future* state – those are proposals, not facts.

4. **Verify each claim against the actual code.** Use the host agent's
   repo-reading tools (e.g. Read, Grep, Glob in Claude Code) to look at the
   repo at `headRef`. For each claim, mark one of:
   - **Confirmed** – the code matches.
   - **Contradicted** – the code says otherwise; cite file:line.
   - **Omits** – the proposal misses a file/module/API that would have to
     change for the proposal to work; cite file:line.
   - **Stale** – the code has moved since the RFC was written; cite the
     newer state.
   - **Unverifiable** – can't be answered from the code alone (e.g. a claim
     about prod behavior, performance, or team capacity).

5. **Cross-check against existing reviewer threads.** If a thread already
   flags one of your "contradicted" or "omits" findings, downgrade your note
   to "@alice already raised this in thread X" – the goal is to add signal,
   not duplicate it.

6. **Format the report in chat.** Group by severity:

   ```markdown
   ## RFC vs. codebase

   ### Contradicted by the code
   - <RFC claim> – actually <what the code does>. (`path/to/file.ts:42`)

   ### Omitted from the proposal
   - The RFC doesn't mention <file/module>, but it would have to change
     because <reason>. (`path/to/file.ts:N`)

   ### Stale
   - <RFC claim> – the code has changed since the RFC was written.
     (`path/to/file.ts:N`)

   ### Unverifiable from the code
   - <RFC claim> – needs a human to confirm.

   ### Confirmed (sanity-check pass)
   - <claim> ✓
   ```

7. **Stop there.** Tell the user: "If you want to raise any of these on
   the RFC, write the comment yourself on GitHub – in your own voice.
   What's above is to inform your review, not to be copied verbatim."

## What not to do

- Don't second-guess design decisions – that's `pressure-test-rfc`. This
  skill is strictly about whether the *factual* claims hold.
- Don't propose code edits, even small ones. The deliverable is a checklist
  for the human reviewer, not a patch.
- Don't fabricate file paths. If you can't find what the RFC references,
  mark it "Unverifiable" rather than guessing.
- Don't post anything to GitHub. The findings are a thinking aid for the
  user's review – they write any feedback themselves, in their own voice.

Versions

The database has no other skills named compare-to-codebase.

Database snapshot: 13.11.2026 · package version 2236741b6315 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90discuss-rfc
    Use when the user wants to talk through a specific RFC in depth – understanding the proposal, pressure-testing it, comparing it against the actual codebase, and surfacing gaps the author missed. Pulls the RFC + threads via the MCP server, grounds the discussion in the current…
  • 100review-rfc
    Review an engineering RFC before it is shared or accepted. Checks its claims against code and documentation, its scope against the originating request, repository rules, internal consistency and template structure, then reports author decisions, fixes and side-channel questions.…
  • 100compare-alternatives
    Use when an RFC discusses multiple options but hasn't laid them out side-by-side. Reads the body, extracts the alternatives, proposes comparison axes, and builds a markdown table in chat. The user edits it into the RFC themselves – in their own voice – if they want it there.
  • 90create-rfc
    Create OpenShell RFC proposals in rfc/ from a design request. Use when the user asks to write, draft, start, create, or update an RFC, Request for Comments, architecture proposal, API proposal, process proposal, or cross-cutting design proposal that should follow the OpenShell…
  • 100rfc
    Manage architecture RFCs: create, review, list, update, and transition status. Use when user mentions "RFC", "technical proposal", "architecture proposal", or wants to draft, review, list, update, or change status of RFCs.
  • 100rfc
    Use when drafting, reviewing, or editing an RFC / design proposal / technical spec for a software project — starting a new numbered RFC, checking one is precise enough for independent implementations, or following its review lifecycle. Works in any repo; detects and mirrors that…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.