/encapsulation

name: encapsulation
description: "This skill should be used when the user asks to \"audit plugin encapsulation\", \"check self-containment semantics\", \"find contributor-knowledge assumptions\", or invokes /encapsulation. Reviews LLM-facing prose in this project's plugin SKILL.md files and plugin description metadata for Plugin Encapsulation compliance: prose that assumes contributor documentation knowledge or rephrases banned references to bypass deterministic checks. Project-local contributor tooling."
allowed-tools: Read, Grep, Glob

Encapsulation Audit

The project-local instance of the **semantic-audit engine** (`references/audit-engine.md`). The shared mechanism — read-only Claude-judge review, the scope shape, severity calibration, self-application stance, and on-demand slash invocation — is defined in that engine document; read it for the parts this skill holds in common with its published siblings. Below is this instance's principle parameter and the one place its output schema extends the engine's base.

This instance audits LLM-facing prose for Plugin Encapsulation: the runtime contract surface (`SKILL.md` plus plugin description metadata) must be self-contained and intelligible without contributor documentation. Project-local — its principle is coupled to this repo's deterministic encapsulation check and contributor model, and so (unlike `white-bear` and `zero-shot`) it is not decouplable into a portable skill. Read-only: it emits structured findings and writes no fixes.

Purpose

Surface encapsulation drift that the deterministic verify check (`artifact-self-containment` BANNED patterns) cannot catch — prose that assumes contributor sidecar knowledge in plain language, or rephrases banned references to evade pattern matching. Findings are presented for review; the human author decides which to rewrite, mark as load-bearing, or dismiss.

Inputs

**Manual invocation only** (interactive `/encapsulation`):

• The caller passes target file paths or a glob; with no argument, the skill enumerates the in-scope set under the working tree HEAD.
• Files are read at their working-tree state — the post-edit, pre-commit content the contributor is about to ship.

Scope

The engine's scope shape applies, specialized to the runtime contract surface this principle governs:

**In scope** (the runtime contract surface where this principle applies):

• `*/skills/*/SKILL.md` — protocol and utility skill prose (full document; the runtime contract surface)
• `.claude-plugin/plugin.json` `description` field — plugin description metadata (discovery/routing layer)

**Out of scope**:

• Files under `docs/`, `CLAUDE.md`, `README*.md`, `*/references/*.md` — contributor documentation, where contributor-knowledge prose is appropriate by purpose.
• Files under `.claude/rules/` and `.claude/principles/` — rule prose authored for contributors.
• `.claude/skills/*/SKILL.md` — project-local contributor tooling, not part of the marketplace runtime contract surface (this skill is itself in this category).
• Files under `.insights/`, `memory/` — session and context substrates outside this skill's audit surface.

What to evaluate

**The principle.** The packaged runtime contract is `SKILL.md` plus plugin description metadata; the surface must be self-contained, with no external references (axiom identifiers, rule file paths, design-philosophy concepts, mission/vision docs) that require reading contributor documentation. The deterministic verify check covers literal pattern matches; this audit covers semantic encapsulation.

Two signal types — this instance extends the engine's single-failure-kind shape with a failure-kind dimension:

**`contributor_assumption`** — a prose passage that assumes contributor documentation knowledge to be intelligible at the runtime contract surface. The reader of the runtime contract is the LLM agent acting on the protocol, plus the user invoking the skill — neither has read `.claude/rules/`, `.claude/principles/`, or `docs/`. Test: "Does this sentence remain intelligible when read with only the SKILL.md itself and standard background knowledge?" If a sentence references a project-internal concept by name without inline definition, and the concept is not defined elsewhere in the same SKILL.md, the sentence is a finding.

**`bypass_rephrasing`** — a prose passage that conveys a banned reference's content without using its banned token. The deterministic check passes; the encapsulation invariant fails. Test: "Would the deterministic check have flagged this if the original token had remained?" If yes, it is a bypass-rephrasing finding.

For each candidate finding, prefer the rewrite that carries the meaning into the runtime surface (compile the relevant rule into `SKILL.md` Rules sections per CLAUDE.md guidance) or replaces it with a self-contained restatement. Treat ambiguous cases as `severity: low` and surface them for human triage.

Output

Emit a single JSON object as the final assistant message. This is the engine's base schema plus a failure-kind dimension (`by_signal` in the summary, `signal` on each finding):

{
  "summary": {
    "files_audited": 0,
    "findings_total": 0,
    "by_signal": {"contributor_assumption": 0, "bypass_rephrasing": 0},
    "by_severity": {"high": 0, "medium": 0, "low": 0}
  },
  "findings": [
    {
      "file": "<repo-relative path>",
      "line": 0,
      "signal": "contributor_assumption",
      "severity": "high",
      "excerpt": "<verbatim text from the file — single line or short span>",
      "rationale": "<one sentence: which contributor knowledge is assumed, or which banned reference's content is being rephrased>",
      "suggested_rewrite": "<a candidate restatement that compiles the meaning into the runtime surface or removes the assumption>"
    }
  ]
}

Severity calibration (per the engine):

| Severity | Surface | |----------|---------| | `high` | Rules sections, Phase prose, plugin description — places