Skip to content

Commit d2f4fb1

Browse files
review-changes: Own remediation and convergence
Keep independent reporting in inspect-changes so review-changes can carry findings through fixes, tracking, and reinspection. Preserve the original scope and work layers, and report incomplete runs explicitly.
1 parent ada4c15 commit d2f4fb1

17 files changed

Lines changed: 1732 additions & 1256 deletions

File tree

.github/linters/.jscpd.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"**/zsh/.p10k.zsh"
1313
],
1414
"ignorePattern": [
15-
"(?s)description: >-\\n Internal step of review-changes:.*?Glob"
15+
"(?s)description: >-\\n Internal step of inspect-changes:.*?Glob"
1616
],
1717
"absolute": true
1818
}

ai/.claude/CLAUDE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ When presenting multiple options/alternatives to choose from, NEVER use Greek
1111
letters (α, β, γ, δ, ...). The user does not know the full Greek alphabet and
1212
it's awkward to type them in conversation.
1313

14-
Never reference ephemeral IDs (review IDs from `review-changes` or similar
14+
Never reference ephemeral IDs (review IDs from `inspect-changes` or similar
1515
tools) in any artifact — duplicate the relevant finding text instead.
1616

1717
## Task Management

ai/.claude/skills/review-changes-analyze/SKILL.md renamed to ai/.claude/skills/inspect-changes-analyze/SKILL.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2+
name: inspect-changes-analyze
23
description: >-
3-
Internal step of review-changes: deeply analyze one kept finding and
4+
Internal step of inspect-changes: deeply analyze one kept finding and
45
return its analysis block (or a rejection).
56
user-invocable: false
67
allowed-tools: >-
@@ -44,7 +45,7 @@ Your invocation prompt supplies, for the single finding you must analyze:
4445
Procedure below and change one only through `## Correction`, never by
4546
restating it in the analysis body.
4647
- Any **caller requirements**, if present. Apply the
47-
[shared caller-requirements guidance](../review-changes/references/caller-requirements.md).
48+
[shared caller-requirements guidance](../inspect-changes/references/caller-requirements.md).
4849
- **Only when a placement decision applies** (the caller supplied a stack and
4950
a `REV`): the **stack** as a list of SHA + subject, each entry carrying
5051
neither, either, or both of `[behind a merge]` and `[merge commit]`, and the
@@ -61,7 +62,7 @@ Your invocation prompt supplies, for the single finding you must analyze:
6162
locate the defect in `REV` by content, and note that the index holds the
6263
reviewed change, so amending there is not a bare `git commit --amend`.
6364
- Existing **prior draft paths**. Follow the
64-
[shared prior-draft guidance](../review-changes/references/prior-drafts.md)
65+
[shared prior-draft guidance](../inspect-changes/references/prior-drafts.md)
6566
when filtering issues discovered during analysis.
6667
- Any **experiment results** for this finding (the matching `EXP` blocks), if
6768
present.
@@ -92,11 +93,11 @@ tools are read and Git only.
9293
positives, not disagreements of emphasis or severity. You can only reject;
9394
you cannot revive a finding verification dropped.
9495
1. Re-assess the verdict's **provenance** (per the
95-
[shared provenance guidance](../review-changes/references/provenance.md)),
96+
[shared provenance guidance](../inspect-changes/references/provenance.md)),
9697
**severity** (per the
97-
[shared severity guidance](../review-changes/references/severity.md)), and
98+
[shared severity guidance](../inspect-changes/references/severity.md)), and
9899
**confidence** (per the
99-
[shared confidence guidance](../review-changes/references/confidence.md))
100+
[shared confidence guidance](../inspect-changes/references/confidence.md))
100101
against what your deeper study found. When one of the three is
101102
wrong, append a `## Correction` section (schema below) carrying only the
102103
fields you are correcting, and state the reasoning in your analysis body as
@@ -169,7 +170,7 @@ tools are read and Git only.
169170
naming an owner prematurely.
170171
Pickaxe matches the exact removed string, so when the fix rephrases or
171172
re-indents it, prefer the bracketing `-L` form. The [attribution
172-
procedure](../review-changes/references/provenance-attribution.md)
173+
procedure](../inspect-changes/references/provenance-attribution.md)
173174
carries pickaxe search and merge-propagation caveats; apply those in the
174175
removal direction, with `<REV>` as the search endpoint. Exclude its
175176
containment and post-image blame tests: those classify surviving content.
@@ -217,7 +218,7 @@ tools are read and Git only.
217218
Provenance and placement can identify different owning commits. Determine
218219
provenance from whether the defect already exists in the scope's pre-image,
219220
including when introduced by the baseline commit itself, per the
220-
[shared provenance guidance](../review-changes/references/provenance.md).
221+
[shared provenance guidance](../inspect-changes/references/provenance.md).
221222
Placement follows the fix's target and cases (a)–(d) above, including the
222223
candidate-stack and never-published conditions for amendment. Compare blame
223224
results for consistency only when the revision, region, and attribution
@@ -296,7 +297,7 @@ carries an analysis block: never on a deferral, and never with a `## Rejection`
296297

297298
If — and only if — analysis surfaced a genuinely new issue, append a
298299
`## Proposed new findings` section after the analysis block, following the
299-
[shared output-section contract](../review-changes/references/shared-output-sections.md).
300+
[shared output-section contract](../inspect-changes/references/shared-output-sections.md).
300301

301302
`## Rejection`, `## Correction`, `## Proposed new findings`, and
302303
`## Experiment requests` are the only higher-level (`##`) headings allowed in a
@@ -309,7 +310,7 @@ rejecting analyst that also spotted a genuinely different issue still reports it
309310
## Experiment requests
310311

311312
Follow the [shared experiment-request format and safety
312-
constraints](../review-changes/references/shared-output-sections.md). Request
313+
constraints](../inspect-changes/references/shared-output-sections.md). Request
313314
runtime evidence when it would sharpen the analysis — **including whether a
314315
suggested action or one of your options is actually feasible given the tooling,
315316
environment, or APIs, not only whether the finding is valid**. Return the

ai/.claude/skills/review-changes-step/SKILL.md renamed to ai/.claude/skills/inspect-changes-step/SKILL.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2+
name: inspect-changes-step
23
description: >-
3-
Internal step of review-changes: perform one code-review pass over a
4+
Internal step of inspect-changes: perform one code-review pass over a
45
given scope and return the draft findings.
56
user-invocable: false
67
allowed-tools: >-
@@ -40,7 +41,7 @@ Your invocation prompt supplies:
4041
`git diff A..B`). Run it to see the changes to review.
4142
- The **pre-image baseline** to tag provenance against, if supplied.
4243
- Any **caller requirements**, if present. Apply the
43-
[shared caller-requirements guidance](../review-changes/references/caller-requirements.md).
44+
[shared caller-requirements guidance](../inspect-changes/references/caller-requirements.md).
4445

4546
You do a single fresh pass each invocation; you carry no state between runs.
4647

@@ -150,11 +151,11 @@ Return the scope line first — including the round index, e.g.
150151
- IDs use the format `R<N>-<NNN>`, where `N` is the round index you were given
151152
and `NNN` runs in per-round discovery order (`001`, `002`, …).
152153
- Grade every finding's severity per the
153-
[shared severity guidance](../review-changes/references/severity.md).
154+
[shared severity guidance](../inspect-changes/references/severity.md).
154155
- Calibrate every finding's confidence per the
155-
[shared confidence guidance](../review-changes/references/confidence.md).
156+
[shared confidence guidance](../inspect-changes/references/confidence.md).
156157
- Classify every finding's provenance per the
157-
[shared provenance guidance](../review-changes/references/provenance.md),
158+
[shared provenance guidance](../inspect-changes/references/provenance.md),
158159
which says when the scope's diff settles it, when Git history is needed, and
159160
how cheap a first-pass tag may be. Tag it from the diff and a cheap baseline
160161
read; never run history attribution at this tier.

ai/.claude/skills/review-changes-verify/SKILL.md renamed to ai/.claude/skills/inspect-changes-verify/SKILL.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2+
name: inspect-changes-verify
23
description: >-
3-
Internal step of review-changes: verify one draft finding against the
4+
Internal step of inspect-changes: verify one draft finding against the
45
code and return its verdict block.
56
user-invocable: false
67
allowed-tools: >-
@@ -38,12 +39,12 @@ Your invocation prompt supplies, for the single finding you must verify:
3839
`git diff A..B`). Run it to see the reviewed change.
3940
- The **pre-image baseline** to re-derive provenance against, if supplied.
4041
- Paths of **existing prior drafts**. Use the
41-
[shared prior-draft guidance](../review-changes/references/prior-drafts.md)
42+
[shared prior-draft guidance](../inspect-changes/references/prior-drafts.md)
4243
to screen issues discovered during verification.
4344
- Any **experiment results** for this finding (the matching `EXP` blocks), if
4445
present.
4546
- Any **caller requirements**, if present. Apply the
46-
[shared caller-requirements guidance](../review-changes/references/caller-requirements.md).
47+
[shared caller-requirements guidance](../inspect-changes/references/caller-requirements.md).
4748

4849
## Procedure
4950

@@ -53,7 +54,7 @@ files** — your tools are read and Git only.
5354
1. Independently confirm the finding by reading the code, following references,
5455
or consulting Git history. Do not hypothesize. Before deciding, run rule 3's
5556
in-image check from the [shared provenance
56-
guidance](../review-changes/references/provenance.md): a site in neither the
57+
guidance](../inspect-changes/references/provenance.md): a site in neither the
5758
pre-image nor the post-image is outside the reviewed content, and the rule's
5859
re-location half can move `Final location:` onto in-image content that
5960
depends on it, which is why the check belongs here rather than after the
@@ -70,7 +71,7 @@ files** — your tools are read and Git only.
7071
(give that as the reason) rather than keeping it as a zero-action
7172
SUGGESTION.
7273
1. Re-derive the finding's confidence from the evidence per the
73-
[shared confidence guidance](../review-changes/references/confidence.md),
74+
[shared confidence guidance](../inspect-changes/references/confidence.md),
7475
rather than adjusting the draft's number. On either outcome the number
7576
grades the evidence for the finding's claim, not the verdict you reach
7677
about it. Give the evidence that settled it in `Verification trace:`, and
@@ -79,14 +80,14 @@ files** — your tools are read and Git only.
7980
should usually become a `drop` — a gate on the number, not a fourth way of
8081
failing verification.
8182
1. On `keep`, re-derive the finding's severity per the
82-
[shared severity guidance](../review-changes/references/severity.md), rather
83+
[shared severity guidance](../inspect-changes/references/severity.md), rather
8384
than inheriting the draft's grade. When your severity differs from the
8485
draft's, say so in `Verification trace:` and give the consequence that
8586
settled it.
8687
1. On `keep`, re-derive the finding's provenance per the
87-
[shared provenance guidance](../review-changes/references/provenance.md).
88+
[shared provenance guidance](../inspect-changes/references/provenance.md).
8889
Where that guidance sends you to attribution, read the [attribution
89-
procedure](../review-changes/references/provenance-attribution.md) before
90+
procedure](../inspect-changes/references/provenance-attribution.md) before
9091
running any of its commands — several fail by printing a plausible wrong
9192
answer rather than an error. Yours is the only tier that runs them.
9293
Establish it yourself rather than inheriting the draft's tag; the draft's
@@ -119,12 +120,12 @@ Return one verdict block:
119120

120121
Optionally append a `## Proposed new findings` section after the verdict,
121122
listing additional issues spotted while verifying. Follow the
122-
[shared output-section contract](../review-changes/references/shared-output-sections.md).
123+
[shared output-section contract](../inspect-changes/references/shared-output-sections.md).
123124

124125
## Experiment requests
125126

126127
Follow the [shared experiment-request format and safety
127-
constraints](../review-changes/references/shared-output-sections.md). Request
128+
constraints](../inspect-changes/references/shared-output-sections.md). Request
128129
runtime evidence in two cases:
129130

130131
- If the experiment is needed to **decide**, return the requests with **no**

0 commit comments

Comments
 (0)