# Jetbrains Inspection

> Use JetBrains IDE inspections through the local inspection plugin; trigger for code changes, readiness checks, PR/push validation, IDE warnings, inspection triage, worktree-safe inspection routing, or when code quality should be driven toward zero actionable IDE findings.

- Skill: `cbusillo/jetbrains-inspection` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add cbusillo/jetbrains-inspection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cbusillo/jetbrains-inspection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cbusillo (https://skillmd.com/u/cbusillo)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cbusillo/jetbrains-inspection

---


# JetBrains Inspection

Apply [task scope and authorization](../references/execution-scope.md) when
using this workflow; it defines how existing approval and task boundaries apply.

Use this skill to run and interpret JetBrains IDE inspections through the local
inspection plugin HTTP API. The script-backed helper is the primary agent
interface; prefer it over direct curl or MCP tool calls.

When IDE configuration appears in the change set, use
`../references/ide-configuration-policy.md` before deciding whether to keep,
split, revert, ignore, or remove it. Inspect tracking state, the exact diff,
ignore rules, repository policy, and history. Preserve the canonical shared form
plus only safe hunks in mixed tracked files; never use blanket commit, revert,
clean, or stash operations that can absorb machine-local or unrelated IDE state.
Do not stage untracked, non-ignored IDE configuration automatically; check
repository policy and ask when the sharing decision remains unclear.

## Before The First Inspection

If `.github/github.json` sets `qualityGate.inspection.prepare`, run that exact
repository command in the exact linked worktree through the lifecycle helper,
which performs preparation before opening it. The preferred public command for
preparing and opening that worktree is:

```bash
uv run "$HELPER" open-worktree --repo "$PWD"
```

`prepare-worktree` and `prepare` remain compatibility aliases, but they are
not the preferred public command. Do not substitute a different setup command,
even if it seems equivalent.

Preparation may create ignored local worktree state such as `.venv/` and
`.idea/` directories or files. That is allowed. What is not allowed is a
nonzero exit or any tracked-file mutation. If either happens, stop and treat
preparation as a blocker before the first inspection.

Preparation-created ignored IDE state stays untracked and is not a reason to
start versioning IDE configuration. Starting to track it is a durable repository
policy change and requires explicit user direction.

Python repositories should prefer the structured, skill-owned preparation
shape instead of embedding an absolute helper path or copying IDE files between
worktrees:

```json
{
  "qualityGate": {
    "inspection": {
      "prepare": {
        "python": {
          "version": "3.13",
          "moduleName": "example-project",
          "testRoots": ["tests"],
          "sync": true,
          "extras": ["dev"],
          "requiredGeneratedState": [".venv", ".idea"]
        }
      }
    }
  }
}
```

The helper resolves its bundled `prepare-python-project.py`, creates an ignored
worktree-local SDK/project model, and optionally runs `uv sync`. String commands
remain supported for repository-specific preparation. Structured preparation
rejects unknown fields, path traversal, extras without sync, and outer-level
`requiredGeneratedState` ambiguity.

Run preparation before the first inspection assessment, not after an
inspection has already started. Preparation is a repo-specific readiness step,
not an inspection surrogate.

Do not preflight SDK setup on every assessment. After `language_sdk_missing`,
repair the documented prerequisite and run a new assessment; do not repeat the
failed run unchanged.

## Primary Helper

Run the helper from the client repository with `uv run`, naming it through this
skill's base directory. `<skill-dir>` is the folder that holds this `SKILL.md`;
your host shows it when the skill loads.

```bash
uv run <skill-dir>/scripts/jb-inspect.py \
  agent-inspect --repo "$PWD" --scope changed_files
```

Useful commands:

```bash
HELPER=<skill-dir>/scripts/jb-inspect.py
uv run "$HELPER" agent-inspect --repo "$PWD" --scope changed_files
uv run "$HELPER" list-projects
uv run "$HELPER" resolve-route --repo "$PWD"
uv run "$HELPER" open-worktree --repo "$PWD"
uv run "$HELPER" inspect --repo "$PWD" --scope changed_files
uv run "$HELPER" inspect-closeout --repo "$PWD" --scope changed_files
uv run "$HELPER" get-status --repo "$PWD"
uv run "$HELPER" get-problems --repo "$PWD" --severity error
uv run "$HELPER" summarize-outcomes
uv run "$HELPER" summarize-outcomes --qualification-file qualification.json --sample-size 50
uv run "$HELPER" cleanup-helper-leases --no-dry-run
```

Command model:

- `agent-inspect`: primary LLM-facing command; runs the maintained inspection
  and lifecycle flow once, emits a compact JSON envelope, and exits successfully
  whenever it produced an `agent_result`. Read the verdict and retry permission
  from `agent_result`, never from the shell exit code. The additive
  `inspection_outcome` field describes the native inspection dimension, while
  `lifecycle_outcome` describes cleanup/worktree lifecycle evidence. A lifecycle
  mutation keeps the overall `agent_result.verdict` fail-closed as `UNKNOWN`;
  it does not rewrite a native GREEN/RED result. Available mutation evidence
  is bounded to paths and counts, carries `*_omitted_count` fields when
  truncated, and
  uses `attribution: "unattributed"` with `detection_phase:
  "post_run_verification"` because before/after snapshots cannot identify the
  writing process. Missing native or snapshot evidence remains `not_run` or
  `unknown`; it is never presented as clean, fresh, or unchanged.
- `list-projects`: discover plugin-visible projects only.
- `resolve-route`: probe for an already-open exact route; it does not open or
  inspect.
- `open-worktree`: preferred public command; run configured repository
  preparation, then open and claim the exact worktree; it does not inspect.
- `prepare-worktree` and `prepare`: backward-compatible aliases for
  `open-worktree`.
- `inspect`: open if needed, inspect, fetch problems, and clean up
  helper-opened projects.
- `inspect-closeout`: readiness/hand-off inspection; use before saying a change
  is ready, safe to push, safe to merge, safe to hand off, or safe to exit.
- `get-status` and `get-problems`: route-pinned diagnostics for
  already-routable projects.
- `get-problems` reads the stored inspection run; it does not start a new one.
  Repeat the original scope selectors so the plugin can prove the requested
  results belong to that run. For a `files` scope, pass at least one repeatable
  `--file` selector. Use a larger `--limit` when the compact assessment envelope
  omitted finding details:

  ```bash
  uv run "$HELPER" get-problems --json --repo "$PWD" \
    --project-key "$PROJECT_KEY" --session-id "$SESSION_ID" \
    --scope files --file src/App.kt --file src/AppTest.kt --limit 500
  ```

  A selector mismatch fails closed instead of widening retrieval.
- `summarize-outcomes`: keep the existing diagnostic verdict/bucket/retry
  summary when no qualification file is supplied. With
  `--qualification-file`, run the strict post-boundary assessment gate described
  below; strict incomplete or failed gates exit nonzero.
- `cleanup-helper-leases`: reconcile stale helper-owned leases under the
  lifecycle lock; unresolved identity or close failures return nonzero.

The helper owns route selection, trusted auto-open, lease-bound cleanup, and
bounded retries. Inspect the exact worktree; never close a preexisting or
foreign-owned project, bypass trust/preparation checks, or add an outer retry
loop. Read verdict and retry permission from `agent_result` and
`retry_policy.retry`, not the process exit code. Deferred cleanup and stale or
unproven results remain `UNKNOWN`; they are not readiness evidence.

Before diagnosing auto-open, ownership, retry, cleanup, trust, or IDE-selection
problems, read [lifecycle diagnostics](references/lifecycle-diagnostics.md).
Also read it before changing lifecycle configuration or helper behavior. Normal
inspection uses the maintained helper and its terminal result; do not reproduce
its lifecycle algorithm manually.

## When To Run

- During the edit loop after meaningful code changes.
- Before saying code is ready, safe to push, safe to merge, or safe to hand off.
- When repo instructions mention JetBrains, PyCharm, IntelliJ IDEA, WebStorm,
  IDE warnings, static analysis, or inspection quality gates.
- When normal tests pass but IDE-only analysis may catch framework/plugin issues.

For docs-only or non-code edits where no runtime behavior changed, record a
one-line not-run reason, such as `docs-only change, no code paths affected`,
when an inspection would be disproportionate.

## Scope Selection

Start narrow while iterating: changed files, touched files, or touched directory.
For final readiness, apply repository requirements and the whole-project
inspection default and exceptions in
[repo-readiness Gate Selection](../repo-readiness/SKILL.md#gate-selection).
Broaden when required coverage, changed behavior, or findings warrant it. Reuse
a current clean result covering the required scope for the same revision and
environment. Complete every required repo gate; an ordered scope preference is
not by itself a requirement to run each scope in succession.
Before defining or diagnosing lane routing, preparation configuration, receipts,
or preparation override flags, read [inspection configuration](references/inspection-config.md).

If config is absent, the helper infers from git and the current working tree. For
a one-off inspection, a missing inspection config can use the safe default
`changed_files` scope when the helper can infer the correct route. Do not
silently turn that inference into durable repo policy. If the configured IDE,
scope, project path, or worktree strategy is blank, contradictory, or feels
wrong for the active worktree, ask the user before changing policy or treating
the value as authoritative; otherwise report the mismatch as a not-clean
readiness blocker.

The helper owns preparation and receipt reuse. A preparation failure, tracked
or hidden index mutation, or missing required generated state is terminal; do
not bypass it or substitute another command.

## Worktree Safety

Inspect the worktree being edited. Do not silently inspect the main worktree
when Code is operating in a linked worktree. If routing resolves to another
worktree, treat that as a blocker unless the user explicitly approves it.

For readiness inspection, require an exact worktree route. A containing main
checkout is not enough; `inspect-closeout` may open the linked worktree in the
preferred IDE and must clean it up afterward when it owns the open.

A linked worktree isolates Git checkout state; it does not serialize processes
inside that worktree or stop IDE VFS refreshes, indexing, and project-model
updates. Before inspection, await builds, installs, generators, formatters, and
other same-worktree writers, then avoid new writes until lifecycle cleanup
finishes. The helper's readiness barrier observes IDE status only; it cannot
identify arbitrary writers or prove that ignored files are quiet.

## Result Policy

- `GREEN`: inspection worked and found no actionable findings for the selected
  scope/filter.
  `whole_project` and `directory` GREEN additionally require plugin capability
  `inspection_execution_proof_version >= 2`, which attests the exact native IDE
  inspection run with affirmative physical-file traversal and file-scoped tool
  completion; global-only activity is insufficient. A missing/older capability is
  `UNKNOWN/plugin_deployment_mismatch`; update the plugin, restart the IDE, and
  resolve the route again instead of trusting an older broad-scope GREEN.
- `RED`: inspection worked and returned actionable current findings. Fix real
  findings in touched code before calling work ready. Exact-scope responses may
  retain `execution_not_proven` in `proof_failures` when the current findings
  are decisive but clean completeness remains unproven; preserve the RED verdict
  and the proof gap together. Unexpected route, run, profile, or freshness proof
  failures still make the result `UNKNOWN`.
- `UNKNOWN`: inspection did not prove green or red. Do not summarize this as
  "no problems found"; report the verdict reason and next action, because the
  IDE, plugin, helper, route, or environment needs attention first.
  Prefer the helper's `agent_result` envelope for normal reporting. It contains
  `verdict`, `bucket`, `retry_policy`, `next_action`, and `agent_report`, plus
  bounded `proof_failures` and `inspection_proof` when a decisive RED retains a
  clean-completeness gap; do not
  inspect raw route, cleanup, wait, or capture diagnostics unless debugging the
  helper itself.
  For `stale_results` and `inspection_inputs_changed`, `unknown_diagnosis`
  separates proven snapshot invalidation from unproven source-edit or process
  attribution. Do not blame an agent or source edit without changed-file or
  process evidence.
  A bounded internal retry may extend to the stricter policy of a later UNKNOWN
  result, such as `stale_results` followed by `project_analysis_not_ready`; all
  attempts remain part of one terminal assessment and stop at the latest policy.
  Before diagnosing attribution, configuring outcome logs, or changing proof
  contracts, read [outcome qualification](references/outcome-qualification.md).
  When inspection evidence is used to qualify changes to this helper or another
  installed runtime-bound skill, compare the recorded helper/source revision
  with the intended landed revision or a fresh runtime-reconciliation receipt.
  A missing or mismatched revision makes the installed-runtime claim `UNKNOWN`;
  do not count it as current evidence. A repo-local helper may still provide
  valid branch evidence when its exact path and revision are recorded and match
  the source being evaluated.

### Qualification and Coverage

Before `summarize-outcomes --qualification-file` or diagnosis of semantic
coverage codes, read [outcome qualification](references/outcome-qualification.md).
Strict qualification requires explicit artifact-pinned input; a normal outcome
summary is not qualification evidence. Missing or truncated semantic coverage
cannot prove GREEN; preserve actionable RED findings with their proof gaps.
Use `--allow-text-only-coverage` only for an intentionally generic data/schema/text
scope, never source code or a mixed scope containing source code.

- Red-lane proof requires current actionable findings in the helper response,
  such as `total_problems > 0`; a paginated current page may have an empty
  `problems` list even when matching findings exist.
  A non-clean response with `capture_incomplete`, `non_empty_unmapped_tree`, or
  zero returned problems proves only that the plugin could not prove clean; it
  is not proof that agents can see and act on the IDE's red state.
- readiness inspections should use `agent-inspect` or `inspect-closeout`, not
  plain `get-status`.
  `open-worktree`, `prepare-worktree`, `prepare`, `agent-inspect`, `inspect`,
  and `inspect-closeout` always lifecycle-open the
  exact worktree when needed. Use `resolve-route`, `get-status`, `get-problems`,
  or `claim-worktree` for observation-only workflows that must not open an IDE;
  do not turn an assessment command into a route-only probe.
  If lifecycle cleanup is skipped or fails for a helper-opened project, the
  inspection is not clean; report both the inspection result and cleanup reason.
  Before cleanup, the helper compares bounded porcelain status snapshots and
  emits `worktree_mutation_evidence` with counts and at most 25 relative paths.
  New tracked or untracked IDE metadata is lifecycle evidence; preserve it in
  the report rather than silently treating forced worktree removal as clean.
  If cleanup is deferred because the IDE is still indexing/scanning, report the
  `UNKNOWN` verdict and rerun after indexing settles before calling the work
  inspection-clean.
- `get-status` is informational and exits zero only when the helper can retrieve
  a route-pinned status that is not stale, inconclusive, unavailable, ambiguous,
  indexing, running, timed out, or session-drifted.
- `ide_selection_required`, `ide_config_ambiguous`, or `ide_config_missing`: the
  repository has no usable IDE route, so repeating the inspection cannot succeed.
  Recommend, in the same report, that the repository record its IDE under
  `qualityGate.inspection` in `.github/github.json`, naming the IDE that fits its
  main language, and ask before writing it because it is durable repository
  policy. If the user names an IDE, rerun once with `--ide`. Do not keep
  reporting that inspection is unavailable without making that recommendation.
- `stale_results`, `capture_incomplete`, `inspection_inputs_changed`, timeout, indexing, session drift,
  ambiguous route, or unavailable IDE: not clean. Retry at most once, and only
  when `retry_policy.retry=true`; otherwise narrow scope, open the project in
  the preferred IDE, or report the blocker. Before a new helper invocation,
  await same-worktree writers and let IDE indexing/project-model updates settle.
  Do not invent retry loops.
- A freshly prepared PyCharm worktree may briefly report `language_sdk_missing`
  after the initial readiness wait if IDE auto-configuration is still registering
  the generated `.venv`. Preparation binds an existing SDK by interpreter home
  when available; it does not register an SDK or guarantee auto-configuration.
  When repository preparation
  succeeded and proved that the active lane project contains its generated
  `.venv`, the helper performs exactly one additional route-readiness wait,
  bounded by the internal retry timeout and gated by route-pinned status. A
  surfaced `language_sdk_missing` means that internal
  retry was unavailable or exhausted and remains a terminal configuration
  blocker; agents must not add another retry loop. Use the exact worktree's
  documented language/SDK setup to restore its SDK, configure the resulting SDK
  for the selected files in the current IDE project, then run one fresh
  `agent-inspect` assessment. For Python, use the repository's documented Python
  setup; do not guess a Python version. Do not commit IDE configuration. If
  preparation evidence names a configured command, use that command; otherwise
  consult the repository's setup instructions before changing the prerequisite.
  If setup is absent, ambiguous, or requires global/system changes, report that
  blocker instead.
- Stale findings are withheld by default. Use `--include-stale` or
  `--allow-stale` only for explicit diagnostics, and do not treat returned
  cached findings as current inspection results.
- Existing broad noise is not invisible. Fix straightforward findings in the
  affected area or track a cleanup item.

Do not hide findings casually. Suppressions, disabled inspections, inspection
profile changes, or baseline changes require explicit approval unless the repo
already has an established approved convention. Prefer fixing code or narrowing
the scope first.

## Reporting

Report the compact helper envelope: verdict (`GREEN`/`RED`/`UNKNOWN`), scope,
one-line finding summary with file and line when available, and next action. Do
not include raw diagnostic fields such as `capture_diagnostic` in normal
reports; use them only when explicitly debugging an extractor or capture
failure. If not run or inconclusive, state a one-line not-run or blocker reason
and the next smallest useful action.