Inspect

Change-Set Inspection

/cpm:inspect answers one question: what did this work actually do, and where does it sit?

Not "is this code any good" — that is /cpm:audit, and it is a different question over a different scope. Not "does this plan hold up" — that is /cpm:review, and it runs before execution rather than after. This skill takes a change set and produces the account a colleague would want if they had to understand the work without opening the repository.

Where this sits

/cpm:review and /cpm:inspect are close enough in name to be confused permanently, so each one's description leads with its subject rather than its verb.

The line against /cpm:audit is the one worth holding. Findings about code quality are audit's output, and a change-set analysis that drifts into them stops answering its own question. If the work under inspection has quality problems worth raising, name them in a sentence and point at /cpm:audit — do not turn the page into a review.

The target repository does not need to be a CPM project. Everything below degrades to whatever the repository actually has, and says which channel it fell back to.

Input

Parse $ARGUMENTS as a selector: a commit, tag, branch, range, --since <ref>, --working-tree, or a phrase like "3 days ago".

If it is absent, work out a sensible baseline — the last release tag, the last merge to the default branch — and state which you chose and why before going further.

Always include uncommitted working-tree changes, and always report them separately from committed ones. Whether work has landed is a fact about the change set, not a footnote.

Resolving it

Selector resolution is deterministic and fiddly enough to be worth a library rather than a judgement — fork points in particular have a right answer that is easy to get plausibly wrong. Source it and call it:

source cpm/hooks/lib/changeset.sh
source cpm/hooks/lib/changeset-resolve.sh
changeset_resolve_git <repo> <selector>...

It emits COMMIT<TAB><sha> and FILE<TAB><path> records, handles --since <ref>, <A>..<B>, a branch name (measured from its actual fork point) and --working-tree, and errors with the selector echoed back rather than returning an empty change set. Report that message as-is and stop; do not widen the selector to find something to talk about.

For anything the library does not cover — a date phrase, a tag, a derived baseline — resolve it with git directly and say what you resolved it to.

Process

State tracking: Create the progress file once the selector has resolved, and update it as each section is settled. See State Management below.

Stale-Progress Check (Startup)

Follow the shared Stale-Progress Check procedure (from the CPM Shared Skill Conventions loaded at session start).

Retro Check (Startup)

Follow the shared Retro Awareness procedure before the Library Check.

Retro incorporation (this skill):

• Codebase discoveries: a past observation about a convention or a constraint is context for Section 2 — it often explains why something sits where it does, and saves reporting a deliberate arrangement as an oddity.
• Testing gaps: inform Section 4 — a suite's known blind spot is worth naming when reporting what the change set's own tests do and do not reach.

Library Check (Startup)

Follow the shared Library Check procedure with scope keyword inspect. Deep-read selectively when a document bears on the change set in hand — an architecture document before judging where a change sits, coding standards before calling something a deviation.

1. Derive the axis before you use it

The organising question is which changes are static and which are dynamic — but that distinction is domain-relative, and you must define it for this repository before classifying anything. Read enough of the codebase to work out what the split actually is here. Depending on the stack it may mean:

• deterministic code vs. model-driven prose or configuration
• build-time, compile-time or generated vs. run-time
• static assets and pre-rendered output vs. dynamically served or hydrated
• schema, migrations, config and DI wiring vs. request-path behaviour
• statically analysable surface vs. reflection, magic methods, dynamic dispatch, runtime registration
• server-rendered vs. client-interactive
• vendored or generated vs. hand-authored

State the definition you chose in one or two sentences, and say what in the repository made it the right one. If more than one reading is defensible, pick the one that explains the most of this change set and name the runner-up.

If the repository has no meaningful static/dynamic split, say so plainly and propose the axis that does explain the change set instead. Do not force the frame — a forced axis produces a page that describes the frame rather than the work.

Then classify every changed component. Components sitting on the boundary — especially ones that are one tier guarding the other — are usually the most interesting thing in the change set. Call them out rather than rounding them to a side.

2. Situate the changes in the repository

Answer with figures you actually measured:

• Proportion — how large is each touched area relative to what was already there? "This directory held 2 files and now holds 17" is worth more than any diffstat.
• Layering — where do the changes sit: entry points, domain, infrastructure, tests, build, docs? Does the change set introduce a new layer, thicken an existing one, or cut across all of them?
• Negative space — what sits immediately adjacent and was not touched, and is that deliberate or an omission? Unchanged config, unchanged public API, unchanged shared or global files, unchanged sibling modules. This is often the highest-signal part of the analysis — a file that everything pays a cost for and that this work avoided touching is a finding in its own right.
• Naming vs. reality — does anything now live somewhere whose name no longer describes what it is?

3. Join the changes to whatever records intent

Use whatever is present, in this order of preference.

If CPM artifacts exist — docs/specifications/, docs/epics/ with paired *-coverage-*.md matrices, docs/retros/, docs/quick/, docs/briefs/, docs/artifacts/index.md, **Satisfies** fields, or a cpm/ plugin tree — read them and map the change set onto that chain: which spec requirement, which epic and story, which coverage rows, which retro. Note requirements with no code behind them, code with no requirement behind it, and coverage rows marked verified with no test naming them. Note where the documented pipeline has gaps — a completed epic with no retro, for instance.

Otherwise fall back through whatever the repository does have: ADRs or decision records, RFCs, design docs, CHANGELOG, README, issue references, commit trailers, conventional-commit scopes, branch names.

If nothing records intent, say so and move on. Absence of a planning record is a finding to report, never a reason to fail or to invent one.

Beware the signal that cannot discriminate. If every file in the change set traces to the same record — one squashed commit carrying a whole epic chain, say — then that mapping tells a reader nothing about any individual file, and reporting it as provenance overstates it. Say that it is uniform and why.

4. Verify before you assert

If the repository has tests, a linter, a type checker or a build, run what is cheap and relevant and report what you actually observed. Never describe a suite as passing without running it. If you could not run something, say which and why.

Distinguish throughout between what you measured, what you read in a document, and what you inferred. Do not present an inference in the same voice as a count.

5. Say what you did not read

A large change set will not fit in one careful pass. That is expected; hiding it is not.

Name every file you did not examine, or characterise them exactly if the list is long ("the 25 test suites under cpm/hooks/tests/, none read"). A count is not enough — it is precisely the shape of disclosure that lets a reader move on without checking. An analysis that silently samples reads as complete, and the larger the change set the more confident that silence sounds.

6. Report

In conversation, lead with the finding: the one sentence that characterises this change set. Then the axis and what sits either side of it, where the change sits in the repository, what it traces to, what you verified, and what you did not read.

Arrange what follows the lead by disposition, per the shared Disposition convention. An inspection changes nothing, so the first disposition never has items and never appears. Something checked and found sound is a record — seen and deliberately left. A claim this environment could not check is still open, and says what would close it. Anything the reader has to act on comes last and together, each item naming the action and where to take it.

Step 5's unread files belong in that last block, not among the unchecked. A pass that did not reach them had road left and ran out of it, which is a fact about the run rather than about the environment — so they are the reader's to read. Filing them as something nothing here could have checked is the one move that would make Step 5's disclosure cost nothing, which is the whole of what it is for.

Publishing

An artifact can be published from this output on request — follow the shared Artifact Publishing procedure. It is always separately confirmed, and never the default.

This skill's output is the case where a page usually earns itself: the analysis is what a reader wants instead of the diff, and it is the thing no diff can render.

Lead with the finding, not the diffstat. A reader can already run git diff. The page should stand in for reading the change set: someone without the repository open should finish it knowing what changed, which tier it belongs to, where it sits, and what it traces back to.

Report counts and paths, not wholesale source. Quote code only where a specific point needs it — an unbounded excerpt is a diff, and rendering a diff is a mirror that earns nothing.

Design for the subject rather than from a template. The axis you derived in Section 1 is usually the page's organising idea, and it is often worth encoding structurally rather than labelling repeatedly.

If the change set is small, unremarkable, or has no interesting structure, say that and keep the page short. Do not inflate a routine change into an architectural narrative.

Register the artifact per the shared procedure once the URL comes back.

Degradation

Output

The report in conversation, and — on request — a published artifact plus its row in docs/artifacts/index.md. This skill writes no other file and commits nothing.

State Management

Follow the shared Progress File Management procedure, writing to docs/plans/.cpm-progress-{session_id}.md — or docs/plans/.cpm-progress.md when CPM_SESSION_ID is not in context. /cpm:clean, the Stale-Progress Check and compaction recovery all locate the file by globbing that exact stem, so one named anything else is invisible to every reader it exists for.

Lifecycle: Create the file once the selector has resolved — before that there is nothing worth recovering, and the selector is the one thing a resumed run cannot re-derive. Update it as each section is settled. Delete it after the report.

Format:

# CPM Progress

**Skill**: inspect
**Selector**: {the selector as given, and what it resolved to}
**Change set**: {commit count} commits, {file count} files, {n} uncommitted
**Axis**: {the static/dynamic definition chosen for this repo}
**Section**: {1-6}

## Settled
- {section}: {what it established}

## Not examined
- {path or characterisation}

The axis is carried because it is the expensive decision — re-deriving it after compaction risks a resumed run classifying the second half of the change set on a different definition from the first.

Notes

• Selector resolution is the only deterministic machinery here, and deliberately so. Provenance is not resolved mechanically: a join that links every file to some record is reproducible and says nothing, and it reports that emptiness as "no orphan changes". Reading the planning documents directly gives an answer that can say this signal does not discriminate here — which no join can.
• Everything above resolution is a reading, and it should sound like one. Counts are counts; inferences are inferences; the page and the conversation both keep them apart.

Next Action

After the report, offer one of:

• /cpm:audit — when the change set raised code-quality questions worth a proper sweep
• /cpm:quick — for something small and well-defined the analysis turned up
• /cpm:spec — when it describes work that needs planning
• /cpm:retro — when the change set is the end of an epic chain

Offer; do not run.