OpenParable
Skip to content
← Back to skills

Knowledge Graph

Development
knowledge-graph

Knowledge Graph is an Agent Skill for development published in the wp-media/wp-rocket repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Read and refresh wp-rocket's pre-built dependency graph at .claude/graph/dependency-graph.json. Use to locate a class file, trace dependencies, find the ServiceProvider that wires a service, or enumerate Subscribers in a module — without re-scanning the codebase from scratch. This skill is primarily a reader: the graph is built (and incrementally refreshed) by `node bin/build-knowledge-graph.js`. Invoke this skill at session start (to refresh if stale) and before grep/glob searches for class relationships.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/wp-media/wp-rocket/blob/HEAD/.claude/skills/knowledge-graph/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/knowledge-graph, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Knowledge Graph

A pre-built dependency graph lives at .claude/graph/dependency-graph.json. The builder is node bin/build-knowledge-graph.js (incremental by default, --full to force rebuild).

This skill has two responsibilities:

  1. Refresh the graph at session start if it is stale (base_commit ≠ git rev-parse HEAD).
  2. Read the graph to answer dependency, namespace, and structure questions instantly.

Read it before running grep/glob searches for class relationships, namespace exploration, or dependency tracing. It eliminates redundant file scans and speeds up the first useful response in any session.


Graph shape

{
  "generated_at": "<ISO timestamp>",
  "base_commit":  "<git SHA>",
  "node_count":   913,
  "nodes": {
    "inc/Engine/Cache/Subscriber.php": {
      "language":  "php",
      "namespace": "WP_Rocket\\Engine\\Cache",
      "symbols": [
        { "kind": "class", "name": "Subscriber", "extends": [], "implements": ["Subscriber_Interface"] }
      ],
      "imports": [
        "WP_Rocket\\Event_Management\\Subscriber_Interface",
        "WP_Rocket\\Engine\\Cache\\Purge"
      ]
    }
  },
  "symbol_index": {
    "WP_Rocket\\Engine\\Cache\\Subscriber": "inc/Engine/Cache/Subscriber.php"
  }
}
  • nodes — keyed by relative file path. Each node has the language (php or js), declared symbols (PHP only), and all import/use statements.
  • symbol_index — maps every fully-qualified PHP class / interface / trait / enum to its file path. Use this for instant "where is this class?" lookups.

WP Rocket specific query patterns

Find a class file (zero grep)

symbol_index["WP_Rocket\\Engine\\Cache\\Purge"]
→ "inc/Engine/Cache/Purge.php"

Find the ServiceProvider that wires a class

The ServiceProvider that registers a class imports it. Search for files whose imports contain the target FQN:

filter nodes where "WP_Rocket\\Engine\\Cache\\Purge" ∈ node.imports
→ "inc/Engine/Cache/ServiceProvider.php"

Then read that ServiceProvider to see how the class is registered in register().

Find all Subscribers in a module

Filter nodes where:

  • namespace starts with the module prefix (e.g. WP_Rocket\Engine\Cache)
  • symbols[*].implements contains Subscriber_Interface

Find all ServiceProviders in the codebase

Filter nodes where symbols[*].extends contains AbstractServiceProvider.

Trace a class's full dependency chain

  1. Start at symbol_index["WP_Rocket\\...\\ClassName"] → get file path
  2. Read nodes[file].imports → these are its direct dependencies
  3. For each dependency, repeat → you get the full constructor injection tree without reading any PHP

Verify no unexpected cross-module dependencies

Check nodes[file].imports for any FQN that shouldn't be there. For example, a Frontend Subscriber importing an Admin class is a red flag.

Find classes that use apply_filters directly (not wpm_apply_filters_typed)

This requires reading the actual files, but the graph narrows the field: only check PHP nodes in inc/Engine/ and inc/Addon/ (the paths covered by PHPStan).


Keeping the graph fresh

The graph records the git commit it was built from (base_commit). If that SHA differs from HEAD, run:

node bin/build-knowledge-graph.js

The script is incremental — it only re-parses files changed since base_commit. Use --full to force a complete rebuild.

When to refresh:

  • At the start of every issue workflow session (step 9 checks this automatically).
  • After merging a branch with structural changes (new classes, namespace moves).
  • Before an architecture review session.

Supported languages

LanguageWhat is extracted
PHPnamespace, class/interface/trait/enum declarations (with extends/implements), use imports (including grouped \{A, B} forms)
TypeScript / JavaScriptimport (static + dynamic) and require() sources

Practical workflow (issue implementation)

Before writing a single line of code for an issue:

  1. Check base_commit vs HEAD — refresh if stale.
  2. Use symbol_index to locate all classes involved in the fix.
  3. For each class, read nodes[file].imports — know the dependency chain before touching the constructor.
  4. Find the ServiceProvider via the import search above — know where to add/modify the binding.
  5. List all Subscribers in the module — know which ones may need new hook entries.
  6. Only then open the actual PHP files (now you know exactly which ones to read).