docs: skill-selection troubleshooting guide + executionDeferred deprecation (D2+D3) by s977043 · Pull Request #866 · s977043/river-review

s977043 · 2026-05-21T06:10:48Z

Summary

Documentation follow-up for #865 (A2-fix-1). Covers two items from the session plan:

D3 -- docs/review/troubleshooting.md (new file)
Explains the silent-skip problem fixed in v0.51.0: river review exec returned
empty findings with no error when availableContexts was not forwarded to
buildExecutionPlan. Includes: diagnosis with --debug, the fix, RIVER_AVAILABLE_CONTEXTS
usage, and how to handle per-skill skippedSkills reasons.

D2 -- docs/deprecated.md (append)
Marks artifact.executionDeferred as deprecated in v0.51.0 (planned removal v0.53.0).
Points to plan.skippedSkills as the richer replacement with per-skill reasons.

Changes

File	What
docs/review/troubleshooting.md	New file: river review exec troubleshooting guide
docs/deprecated.md	Append: executionDeferred deprecation notice

No code changes

Pure documentation. All tests continue to pass unchanged.

Closes documentation gap for: #865 (A2-fix-1), #802 Phase 3.

Co-authored-by: Claude Opus 4.7 (1M context) [email protected]

vercel · 2026-05-21T06:10:53Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ai-review-kit	Ready	Preview, Comment	May 21, 2026 6:31am

github-actions · 2026-05-21T06:11:44Z

No changes to review compared to main.

github-actions · 2026-05-21T06:12:56Z

PlanGate Review

decision: pass
plan status: skipped-by-label
exec status: skipped-by-label

PlanGate review decision: pass

severity	count	policy
critical	0	fail
major	0	fail-if-required / warn
minor	0	comment-only
info	0	skipped

_{ポリシー: critical=fail / major=fail-if-required (warn) / minor=comment-only / info=skipped — spec: pages/reference/cli-review-plan-spec.md}

gemini-code-assist

Code Review

このプルリクエストでは、artifact.executionDeferred フィールドの非推奨化に伴う docs/deprecated.md の更新と、river review exec に関するトラブルシューティングガイド docs/review/troubleshooting.md の新規追加が行われました。レビューでは、スキーマ定義に合わせて reasons を複数形に修正する提案や、コード例内でのプロパティ名の誤り、およびドキュメント間の相対パスの不備に関する指摘があり、これらはドキュメントの正確性を向上させるための重要な改善点です。

gemini-code-assist · 2026-05-21T06:14:13Z

+
+The boolean executionDeferred field on the review artifact was added during Phase 3
+to signal that some skills were deferred/skipped. It is superseded by the richer
+plan.skippedSkills array, which carries a per-skill skip reason.


スキーマ定義（review-artifact.schema.json）では、各スキルのスキップ理由は reasons（複数形）という配列で定義されています。説明文もこれに合わせて複数形にするのが正確です。

Suggested change

plan.skippedSkills array, which carries a per-skill skip reason.

plan.skippedSkills array, which carries per-skill skip reasons.

gemini-code-assist · 2026-05-21T06:14:14Z

+```js
+const skipped = artifact.plan?.skippedSkills ?? [];
+if (skipped.length > 0) {
+  console.warn(skipped.length + " skills skipped:", skipped.map(s => s.reason));


skippedSkills の各要素に含まれるプロパティ名は reasons（複数形）です。提供されているコード例では s.reason となっているため、期待通りに理由が表示されません。

Suggested change

console.warn(skipped.length + " skills skipped:", skipped.map(s => s.reason));

console.warn(skipped.length + " skills skipped:", skipped.map(s => s.reasons));

gemini-code-assist · 2026-05-21T06:14:14Z

+## See also
+
+- [CLI reference: river review exec](../pages/reference/cli-review-exec-spec.md)
+- [Deprecated: executionDeferred](deprecated.md#output-artifact-field-executiondeferred-v0510)


deprecated.md への相対パスが正しくありません。docs/review/ ディレクトリから docs/ 直下のファイルを参照するには、../deprecated.md とする必要があります。

Suggested change

- [Deprecated: executionDeferred](deprecated.md#output-artifact-field-executiondeferred-v0510)

- [Deprecated: executionDeferred](../deprecated.md#output-artifact-field-executiondeferred-v0510)

…Deferred D3: docs/review/troubleshooting.md — documents the silent-skip problem fixed in A2-fix-1 (v0.51.0): river review exec returned empty findings when availableContexts was not forwarded to buildExecutionPlan. Covers diagnosis with --debug, the fix, and RIVER_AVAILABLE_CONTEXTS usage. D2: docs/deprecated.md — marks artifact.executionDeferred as deprecated in v0.51.0 (planned removal v0.53.0) and points to plan.skippedSkills as the replacement. Closes documentation gap for PR #865 (A2-fix-1). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

- Fix the deprecation narrative for `debug.executionDeferred`: the replacement is the new `debug.execution` trace (introduced in v0.51.0 / A2-1), not `plan.skippedSkills`. Migration snippet now shows both the execution trace check and the skippedSkills check side by side. - Fix the heading anchor: the deprecation header is now `output-artifact-field-debugexecutiondeferred-v0510`. - In troubleshooting.md, code-format every reference to skill metadata (`inputContext: ['diff']`, `--context`, schema field names) so the prose does not look like Markdown links. - Fix the relative path to the CLI spec (`../../pages/...` from `docs/review/`). - Note explicitly that the v0.51.0 `alwaysInclude: ['diff']` semantics protect the diff context from being stripped by `--context tests`. No code changes. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Address Gemini PR #879 review: the English README still listed the roadmap as a bullet list without status information after the JA README gained a status table in this PR. Bring it in sync. The second Gemini comment (use pages/guides/troubleshooting.md instead of docs/review/troubleshooting.md in Epic 6) is intentionally skipped: the two are different files. docs/review/troubleshooting.md was added by #866/#872 specifically for silent-skip cleanup diagnosis aimed at developers, while pages/guides/troubleshooting.md is the public general-purpose troubleshooting page. Both serve their audiences and should not be conflated. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…low-up) (#879) * docs(readme): add roadmap status column (codex review follow-up) Multi-perspective session review (Codex 86, Gemini 95) flagged the README roadmap as a list of epic names with no implementation status, making it hard to tell which slice was Implemented vs Partial vs Planned. Convert the 7-epic list to a table with an explicit 状態 column, v0.53.0 reality: - Epic 0 Partial (community skills #873/#875 landed, official pack registry not yet) - Epic 1 Planned (#800 npm, untouched) - Epic 2 Partial (plan/exec stable, --plan replay execution #878, verify not implemented) - Epic 3 Implemented (v0.51.0 #860) - Epic 4 Planned - Epic 5 Planned (promptfoo per-skill in place, dashboard not yet) - Epic 6 Partial (troubleshooting.md #866 #872) Adds a 凡例 line so adopters can interpret the status column. No code changes. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * docs(readme.en): sync roadmap status column with the JA README Address Gemini PR #879 review: the English README still listed the roadmap as a bullet list without status information after the JA README gained a status table in this PR. Bring it in sync. The second Gemini comment (use pages/guides/troubleshooting.md instead of docs/review/troubleshooting.md in Epic 6) is intentionally skipped: the two are different files. docs/review/troubleshooting.md was added by #866/#872 specifically for silent-skip cleanup diagnosis aimed at developers, while pages/guides/troubleshooting.md is the public general-purpose troubleshooting page. Both serve their audiences and should not be conflated. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

gemini-code-assist Bot reviewed May 21, 2026

View reviewed changes

s977043 and others added 2 commits May 21, 2026 15:22

s977043 force-pushed the docs/phase3-skill-selection-troubleshooting branch from a05fd88 to ef650d4 Compare May 21, 2026 06:30

vercel Bot deployed to Preview May 21, 2026 06:31 View deployment

s977043 merged commit 3801edd into main May 21, 2026
19 checks passed

s977043 mentioned this pull request May 22, 2026

docs(readme): add roadmap status column (multi-perspective review follow-up) #879

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: skill-selection troubleshooting guide + executionDeferred deprecation (D2+D3)#866

docs: skill-selection troubleshooting guide + executionDeferred deprecation (D2+D3)#866
s977043 merged 2 commits into
mainfrom
docs/phase3-skill-selection-troubleshooting

s977043 commented May 21, 2026

Uh oh!

vercel Bot commented May 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

github-actions Bot commented May 21, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 21, 2026

Uh oh!

gemini-code-assist Bot May 21, 2026

Uh oh!

gemini-code-assist Bot May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	plan.skippedSkills array, which carries a per-skill skip reason.
	plan.skippedSkills array, which carries per-skill skip reasons.

	console.warn(skipped.length + " skills skipped:", skipped.map(s => s.reason));
	console.warn(skipped.length + " skills skipped:", skipped.map(s => s.reasons));

	- [Deprecated: executionDeferred](deprecated.md#output-artifact-field-executiondeferred-v0510)
	- [Deprecated: executionDeferred](../deprecated.md#output-artifact-field-executiondeferred-v0510)

Conversation

s977043 commented May 21, 2026

Summary

Changes

No code changes

Uh oh!

vercel Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PlanGate Review

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading