codebase-mentorSAFE

Find your way through unfamiliar code. Source-grounded architecture answers, change plans, and onboarding docs. Claude Code and Codex plugins, IBM Bob skills. By JEStats.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: codebase-mentor
description: Explain unfamiliar code, trace execution paths, plan changes, and check onboarding docs against current source. Use for architecture questions, finding where a change belongs, or verifying codebase claims. Works with or without ONBOARDING.md.
---

# Source-Grounded Codebase Mentor

<!-- GENERATED FILE — do not edit the protocol body by hand.
     Canonical source: core/mentor-protocol.md. Regenerate with scripts/sync-adapters.sh. -->

Activate this skill when a developer asks about code architecture, wants to know where to make a change, asks you to verify whether a statement about the codebase is true, or asks for a freshness scan of the repo's ONBOARDING.md. The skill works in Claude Code, Codex, IBM Bob, and other agents that support the open SKILL.md format.

Start in any repository, with or without an `ONBOARDING.md`. When a map exists, use it to find the relevant code, then verify its claims. Without a map, work directly from source. Live source is the truth.

**Tool mapping:** where the protocol says "read", use your file-reading tool (Read in Claude Code); where it says "search", use your code-search tool (Grep in Claude Code).

**Companions:** generate a missing ONBOARDING.md with the `onboard` skill (`/codebase-mentor:onboard` in a Claude Code plugin install). The authoring template and guide sit alongside this SKILL.md in any install: `ONBOARDING.template.md` and `AUTHORING_GUIDE.md`. Resolve these files relative to this skill's directory, not the user's repository.

---

## Accuracy Contract

**Every architecture or change-guidance claim you make must be backed by a symbol or file read in the current session.**

Do not answer from pre-training knowledge about what a codebase "typically" looks like. Do not assume a class or method exists because a similar pattern is common. Read the source first, then answer from what you found.

Answers are regenerated from current source, not from a persistent index. If a relevant source artifact cannot be located, say so explicitly — do not fill the gap with inference.

Distinguish observed behavior from proposed changes and human-provided rationale. A proposed new name is not an existing symbol. Attribute rationale supplied by a developer or document, and do not present it as a source-verified fact. Source reads establish what the checked-out code says, not what is deployed or enabled at runtime.

**Source is the truth. ONBOARDING.md is the map.**

---

## Citation Format

Use **symbol anchors with file paths**: functions, classes, methods, workflow jobs, or configuration keys. For documents and declarative projects, cite the file and relevant heading or key. Names need not be globally unique, so include enough path context to locate the evidence.

Correct citation format: "This is handled in `ResolverClass.resolveCommand()` in `path/to/ResolverClass.java`."
For a workflow: "The `deploy` job in `.github/workflows/docs.yml` publishes the site."

Do not rely on bare line numbers as durable anchors. A current file link with a line number is useful navigation when the agent supports it, but include the symbol, heading, or key as well. If a method is long, name the relevant inner call or block.

---

## Operating Modes

### Mode 1 — Mentor

**Trigger:** Developer asks an architecture question ("How does X work?", "What handles Y?", "Why does Z exist?", "Walk me through the pipeline for...").

**Your job:** Read `ONBOARDING.md` to orient yourself, locate the relevant source, read it, then answer with symbol-anchored citations.

**Steps:**

1. Locate and read `ONBOARDING.md` using the discovery rules below. Identify which section — layer map, request lifecycle, domain vocabulary, or high-signal files — is most relevant to the question. If none exists, locate entry points directly in source.

2. From the relevant ONBOARDING.md section, extract one to three symbol or file anchors that point toward the answer.

3. Open each symbol in the live source. Read the file directly, or search for the class name if the path is unknown — whichever resolves the symbol fastest. Read the body if the question requires understanding behavior, not just structure.

4. If the ONBOARDING.md pointer leads to a dead end (symbol does not exist, class has been renamed, method is gone), do not guess. Declare the pointer stale and fall back to searching the source directory for a plausible replacement (see Evidence-Missing Protocol below).

5. Compose the answer using only what you read in steps 2–4. Structure the answer as:
   - One-paragraph plain-language explanation.
   - Evidence block: one bullet per relevant source artifact, with the symbol, heading, or key and file path.
   - If ONBOARDING.md had relevant rationale, a gotcha, or a known limitation, summarize it and attribute it to the doc. Verify associated behavioral claims in source.

6. If the question requires tracing a full request path, follow the chain: read each layer in turn, do not skip ahead from ONBOARDING.md summary to a final answer.

---

### Mode 2 — Change Guide

**Trigger:** Developer describes a task ("I need to add X", "I want to change how Y works", "Where do I start to implement Z?").

**Your job:** Find the nearest existing example of the same type of change in the live source, then produce an ordered checklist of files and methods to touch.

**Steps:**

1. Read `ONBOARDING.md` — specifically the "common change recipes" section if present. Extract the recipe that most closely matches the requested change.

2. If a matching recipe exists, use its symbol anchors to locate the relevant files and classes. Open them in the live source.

3. If no matching recipe exists in ONBOARDING.md, search the source for the nearest existing example of the same pattern. For example, if the task is "add a new command", find one existing command resolver and read it to understand the pattern.

4. From the live source, identify the existing symbols and files the change touches 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.