grafel-aware-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# grafel-aware-review

A structural review protocol for AI agents. This skill turns grafel MCP
into a systematic second opinion on every PR — one that catches impact leakage,
broken call chains, and pattern drift that diff-only review misses.

Prerequisite: the `/using-grafel` skill. This skill assumes you already
know the 22 MCP tools and the orientation workflow.

---

## 1. Should I run grafel on this PR?

### Yes — run the structural checks when the diff touches:

| Change type | Key risk grafel catches |
|-------------|----------------------------|
| New/renamed function or method | Callers in other modules still expect the old signature |
| Deleted function or method | Orphan call-sites remain in any repo of the group |
| New HTTP endpoint | No client calls it yet (dead definition); or it clashes with an existing route |
| Changed HTTP endpoint path/method | Existing client calls become orphan callers |
| New inter-module import | Introduces an unexpected cluster coupling or a cycle |
| New message publish/subscribe | No subscriber (dead publish) or no publisher (dead subscriber) |
| Cross-repo call site added | Target entity may not exist in the other repo's graph |
| Pattern implementation (new handler, new serializer, etc.) | Does not follow the established structural pattern |

### No — skip grafel when the diff is limited to:

- Whitespace, formatting, or lint fixes.
- Comment or docstring edits.
- Test fixture data files (JSON, YAML, CSV).
- Changes that are entirely within a single private function with no exported signature.
- Config-only changes (`*.env`, `*.yaml`, `*.toml`) with no code entry points.
- Pure CSS/markup with no JS/TS wiring changes.

**Quick self-check:** if the change cannot be reached from any entity in the
grafel graph (no exported name, no route, no published event), skip the
structural pass and review the diff purely on its own terms.

---

## 2. Quick win — one call for 80 % of insights

When time is short, a single call surfaces most structural risk:

```
grafel_impact_radius(
  target="<the changed entity>",
  scope="entity"
)
```

This call returns:
- The blast radius of the change — directly and transitively affected entities.
- Whether any affected entities live in a different repo (cross-repo risk).
- The PageRank weight of the changed entity (high = high blast radius).

If the entity is not found, it is either brand-new (check for
orphan callers of the new name) or the repo has not been re-indexed since the
PR was opened.

**Estimated cost:** ~100–300 tokens. Run this first. If the result is clean
and the entity has low PageRank, you may not need the full per-change-type
sequence below.

---

## 3. Per-change-type MCP tool sequence

### 3.1 Function / method signature change

**Risk:** callers in other modules or repos still call the old signature,
or assume a return type that no longer exists.

```
# Step 1: Find the entity and all depth-2 callers
grafel_related(entity="<FunctionName>", direction="callers")

# Step 2: Inspect for PageRank (blast-radius indicator)
grafel_inspect(entity="<FunctionName>")

# Step 3: For each top caller — does its call site match the new signature?
grafel_get_source(entity="<CallerEntityId>", context_lines=20)

# Step 4: Check cross-repo callers
grafel_related(entity="<FunctionName>", direction="callers")
# Look for entries where entity_id prefix differs from current repo slug
```

**Review comment trigger:** any caller found at depth 1 or 2 that is in a
different file or repo — confirm the call site is updated or explicitly listed
as a follow-up ticket.

---

### 3.2 Deleted function or method

**Risk:** call-sites anywhere in the group still reference the deleted name,
creating dead code (orphan callers).

```
# Step 1: Find all callers before deletion is confirmed as safe
grafel_related(entity="<DeletedFunctionName>", direction="callers")
# If callers is empty: the entity was already absent from the index — safe.
# If callers exist: call-sites remain.

# Step 2: Expand to enumerate every direct caller
grafel_related(entity="<DeletedFunctionName>", direction="callers")

# Step 3: Source-read each caller to verify it is also removed in this PR
grafel_get_source(entity="<CallerId>", context_lines=15)
```

**Review comment trigger:** any caller not removed in the same PR. Block
if caller is in a different repo (cross-repo breakage).

---

### 3.3 New HTTP endpoint

From cajasmota/grafel, MIT.

More from cajasmota/grafel