docs(concept): refresh positioning around Skill Registry × SDLC gates#860
Merged
Conversation
Adopt the v4 concept refresh agreed via a three-agent discussion (Claude → Codex → Gemini → Codex final, 91/100). - README hero rewritten to "Codify your team's judgment into automated PR gates." - 5-axis comparison table distinguishes River Reviewer from existing AI review tools - Three-layer Core Model (Skills define / Gates execute / Riverbed remembers) introduced - FAQ added covering Linter boundary, data boundary, PlanGate independence, cost control - Roadmap restructured into Epic 0-6, folding #800 (npm) and #802 (PlanGate CLI) - docs/vision.md promoted from internal draft to concept SSoT - pages/explanation/intro.md(.en.md) updated to drop upstream/midstream/downstream in favor of the new three-layer model and the team-owned audit layer framing - docs/Working/ (session-local drafts) added to .gitignore Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
River Reviewer
選択されたスキル (0)
スキップされたスキル (83)
優先度サマリー
スコア (参考値)結果(スコア): 96/100 内訳:
指摘
|
Contributor
PlanGate Review
PlanGate review decision: pass
ポリシー: critical=fail / major=fail-if-required (warn) / minor=comment-only / info=skipped — spec: |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request performs a significant concept refresh for River Reviewer, updating the READMEs, vision document, and introductory pages in both English and Japanese. The changes redefine the framework as a team-owned audit layer for AI-assisted development, focusing on 'skills' that define judgment and 'gates' that execute it across SDLC artifacts. The roadmap has also been restructured into seven epics. Feedback was provided to ensure consistent terminology (e.g., using 'アーティファクト' and 'tests/JUnit' consistently) and to remove temporary phrasing like 'landing with this PR' that would become outdated after merging.
| 日本語版READMEです。[English README is available here.](./README.en.md) | ||
|
|
||
| ## ライセンス概要 | ||
| River Reviewer は、レビュー基準を **versioned / repo-owned な skill** として扱う OSS フレームワークです。plan / diff / test-cases / junit / 既存レビュー結果といった SDLC のアーティファクトをまたいで実行できます。 |
Contributor
There was a problem hiding this comment.
用語の表記揺れを解消するため、28行目の比較表と合わせて tests および JUnit に表記を統一することをお勧めします。また、他の箇所（13行目冒頭や intro.md）では「アーティファクト」とカタカナ表記されているため、ここでも統一感を出すのが良いでしょう。
Suggested change
| River Reviewer は、レビュー基準を **versioned / repo-owned な skill** として扱う OSS フレームワークです。plan / diff / test-cases / junit / 既存レビュー結果といった SDLC のアーティファクトをまたいで実行できます。 | |
| River Reviewer は、レビュー基準を **versioned / repo-owned な skill** として扱う OSS フレームワークです。plan / diff / tests / JUnit / 既存レビュー結果といった SDLC のアーティファクトをまたいで実行できます。 |
| チーム固有のレビュー知識を「スキル」として明示化・バージョン管理し、GitHub Actions/CLI/Node APIなど、あらゆる環境で再利用できます。スキルはテスト可能で、継続的に改善できる資産です。 | ||
| linter や静的解析は、コード内で完結する決定論的なチェック（構文、型、危険な API、スタイル、複雑度、重複、既知のセキュリティパターン）が得意です。 | ||
|
|
||
| River Reviewer が扱うのは、**artifact を跨ぐレビュー判断**です。 |
Contributor
There was a problem hiding this comment.
13行目や intro.md での表記に合わせて、「artifact」を「アーティファクト」に統一することをお勧めします。
Suggested change
| River Reviewer が扱うのは、**artifact を跨ぐレビュー判断**です。 | |
| River Reviewer が扱うのは、**アーティファクトを跨ぐレビュー判断**です。 |
| - この依存追加はリポジトリのポリシー上許容されるか？ | ||
| - PR は別のレビュアーが既に指摘した観点に対応しているか？ | ||
|
|
||
| これらは plan / diff / tests / 既存コメント / チーム基準といった構造化された文脈を必要とします。ルールベース linter では書けない判断を、**LLM + 構造化された artifact + テスト可能な skill** で扱います。 |
Contributor
There was a problem hiding this comment.
他の箇所との整合性を保つため、「artifact」を「アーティファクト」と表記することをお勧めします。
Suggested change
| これらは plan / diff / tests / 既存コメント / チーム基準といった構造化された文脈を必要とします。ルールベース linter では書けない判断を、**LLM + 構造化された artifact + テスト可能な skill** で扱います。 | |
| これらは plan / diff / tests / 既存コメント / チーム基準といった構造化された文脈を必要とします。ルールベース linter では書けない判断を、**LLM + 構造化されたアーティファクト + テスト可能な skill** で扱います。 |
|
|
||
| skill を CI job のように扱ってください。 | ||
|
|
||
| 安価で決定論的なチェックを先に走らせる、変更に関係する artifact と skill にだけ River Reviewer を当てる、まずは小さな公式 skill pack から始めて、人間のレビューコストや回帰リスクが高い箇所にだけリポジトリ固有 skill を追加する、という運用が現実的です。 |
Contributor
There was a problem hiding this comment.
他の箇所との整合性を保つため、「artifact」を「アーティファクト」と表記することをお勧めします。
Suggested change
| 安価で決定論的なチェックを先に走らせる、変更に関係する artifact と skill にだけ River Reviewer を当てる、まずは小さな公式 skill pack から始めて、人間のレビューコストや回帰リスクが高い箇所にだけリポジトリ固有 skill を追加する、という運用が現実的です。 | |
| 安価で決定論的なチェックを先に走らせる、変更に関係するアーティファクトと skill にだけ River Reviewer を当てる、まずは小さな公式 skill pack から始めて、人間のレビューコストや回帰リスクが高い箇所にだけリポジトリ固有 skill を追加する、という運用が現実的です。 |
| - **Epic 0**: 公式 Skill Pack と最小 Registry（security / a11y / migration-safety / dependency-policy / plan-conformance） | ||
| - **Epic 1**: First-Run Adoption（npm 配布、`npx river try`、10 分 Quick Start、[#800](https://github.com/s977043/river-reviewer/issues/800)） | ||
| - **Epic 2**: SDLC Gates（`plan` / `exec` / `verify` CLI 安定化、artifact-input-contract v1、[#802](https://github.com/s977043/river-reviewer/issues/802)） | ||
| - **Epic 3**: Concept Refresh（README / vision / intro 刷新—本 PR で着手） |
Contributor
There was a problem hiding this comment.
「本 PR で着手」という表現は、マージ後にドキュメントが古くなってしまうため、削除するか「v0.50.0 で実施」などの永続的な表現にすることをお勧めします。
Suggested change
| - **Epic 3**: Concept Refresh（README / vision / intro 刷新—本 PR で着手） | |
| - **Epic 3**: Concept Refresh（README / vision / intro 刷新） |
| | Understand the design | [Architecture docs](https://river-reviewer.vercel.app/explanation/river-architecture/) | | ||
|
|
||
| Philosophy: [Why we built it](#philosophy) | ||
| License details are at the [bottom of this file](#license). |
Contributor
There was a problem hiding this comment.
The Japanese version of the README includes a link to the development runbook (docs/runbook/dev.md). It would be better to include it here as well for consistency.
Suggested change
| License details are at the [bottom of this file](#license). | |
| See [docs/runbook/dev.md](docs/runbook/dev.md) for development procedures. License details are at the [bottom of this file](#license). |
| - **Epic 0**: Official Skill Pack and Minimal Registry (security / a11y / migration-safety / dependency-policy / plan-conformance) | ||
| - **Epic 1**: First-Run Adoption (npm distribution, `npx river try`, 10-minute Quick Start, [#800](https://github.com/s977043/river-reviewer/issues/800)) | ||
| - **Epic 2**: SDLC Gates (stabilize `plan` / `exec` / `verify` CLI, artifact-input-contract v1, [#802](https://github.com/s977043/river-reviewer/issues/802)) | ||
| - **Epic 3**: Concept Refresh (README / vision / intro — landing with this PR) |
Contributor
There was a problem hiding this comment.
The phrase "landing with this PR" will become outdated once the PR is merged. It is better to remove it or use a more durable description.
Suggested change
| - **Epic 3**: Concept Refresh (README / vision / intro — landing with this PR) | |
| - **Epic 3**: Concept Refresh (README / vision / intro) |
| --- | ||
|
|
||
| River Reviewer (RR) は **Context Engineering に基づく Skill Registry 中心のコードレビューフレームワーク**です。チーム固有の暗黙知を再利用可能な「Agent Skills」として明示化・バージョン管理し、**Upstream → Midstream → Downstream** の流れに沿って実行します。 | ||
| River Reviewer (RR) は、**チームのレビュー判断を skill として明示化・バージョン管理し、SDLC の各ゲートで実行する OSS フレームワーク**です。plan / diff / test-cases / junit / 既存レビュー結果といったアーティファクトをまたいで動作し、AI 支援開発における **チーム所有の監査レイヤー** として機能します。 |
Contributor
There was a problem hiding this comment.
READMEの比較表（28行目）に合わせて、tests および JUnit に表記を統一することをお勧めします。
Suggested change
| River Reviewer (RR) は、**チームのレビュー判断を skill として明示化・バージョン管理し、SDLC の各ゲートで実行する OSS フレームワーク**です。plan / diff / test-cases / junit / 既存レビュー結果といったアーティファクトをまたいで動作し、AI 支援開発における **チーム所有の監査レイヤー** として機能します。 | |
| River Reviewer (RR) は、**チームのレビュー判断を skill として明示化・バージョン管理し、SDLC の各ゲートで実行する OSS フレームワーク**です。plan / diff / tests / JUnit / 既存レビュー結果といったアーティファクトをまたいで動作し、AI 支援開発における **チーム所有の監査レイヤー** として機能します。 |
| - **CodeRabbit / Copilot Review / Gemini Code Assist**: diff を入力に PR コメントを返す SaaS。判断ロジックはプロバイダ側に閉じる。 | ||
| - **Claude Code / Codex / Cursor**: 実装を行うエージェント IDE/CLI。レビューは付帯機能。River Reviewer はこれらの**横で動く検査ゲート**として設計されている。 | ||
| - **Anthropic Agent Skills**: 業務マニュアル付きの道具箱（能力単位）。River Reviewer の skill は「**レビュー職務単位**」で、artifact 契約と評価可能性をもつ。 | ||
| - **ESLint / SonarQube などの静的解析**: 1 ファイル内で完結する決定論的チェック。River Reviewer は **artifact を跨ぐ判断**（plan と diff の乖離、テストと境界条件の整合、過去レビューとの一貫性）を扱う。 |
Contributor
There was a problem hiding this comment.
他のドキュメント（README や intro.md）での表記に合わせて、「artifact」を「アーティファクト」に統一することをお勧めします。
Suggested change
| - **ESLint / SonarQube などの静的解析**: 1 ファイル内で完結する決定論的チェック。River Reviewer は **artifact を跨ぐ判断**（plan と diff の乖離、テストと境界条件の整合、過去レビューとの一貫性）を扱う。 | |
| - **ESLint / SonarQube などの静的解析**: 1 ファイル内で完結する決定論的チェック。River Reviewer は **アーティファクトを跨ぐ判断**（plan と diff の乖離、テストと境界条件の整合、過去レビューとの一貫性）を扱う。 |
| ## 拡張可能性 | ||
|
|
||
| - レビュー以外（ADR、設計、運用、SRE）にも横展開できる設計を想定する。 | ||
| - レビューに留まらず、ADR / 設計 / 運用 / SRE などの判断職務にも横展開できる artifact 契約と skill スキーマを目指す。 |
Contributor
There was a problem hiding this comment.
他のドキュメントとの整合性を保つため、「artifact」を「アーティファクト」と表記することをお勧めします。
Suggested change
| - レビューに留まらず、ADR / 設計 / 運用 / SRE などの判断職務にも横展開できる artifact 契約と skill スキーマを目指す。 | |
| - レビューに留まらず、ADR / 設計 / 運用 / SRE などの判断職務にも横展開できるアーティファクト契約と skill スキーマを目指す。 |
Apply terminology unification and durable phrasing suggestions:
- artifact -> アーティファクト in flowing Japanese prose (README/vision)
- test-cases/junit -> tests/JUnit in hero paragraphs to match the comparison
table and the English README
- Remove the PR-relative phrasing ("本 PR で着手" / "landing with this PR")
from the Epic 3 roadmap entry so the line stays accurate post-merge
- Add the development runbook link to the English README to match the
Japanese version
Technical identifiers (artifact-input-contract, artifact-based, CLI
--artifact flags, schema labels) are kept in roman as they are stable names.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
3 tasks
s977043
added a commit
that referenced
this pull request
May 22, 2026
…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]>
s977043
added a commit
that referenced
this pull request
May 25, 2026
#898) Capture the 5-day sprint (35 PR, 6 release, 1 production CVE close) as durable record before starting the next session. Codex consultation was the foundation; the primary takeaway is: > 最大の問題は速度ではなく、停止条件の弱さ。次は「作る量」 > より「どこから保留に戻すか」を先に設計すべき。 Sections - Numerical summary - What worked (5 items: multi-perspective review, silent-skip thread, memory persistence, gh-api recovery, dogfood detection) - What didn't work (6 items: overproduction past Codex stop, eval-less skill increase, manual release-please kick x4, AGENTS.md pollution, reviewer mis-suggestions, single-shot multi-perspective) - Surprises (npm pack audit findings, CLI boundary, fs-loss recovery) - 5 pivot points (timeline of where direction should have changed) - Codex 100-char summary on the sprint - Improvement priorities split into Skills / Agents / Workflow with P0/P1/P2 ranking - Stop-on-stop-judge operational rule with Continue / Consult / Park buckets, plus post-hoc classification of this sprint's 35 PRs (Continue: A2-fix and CVE-class items; Consult: skill registry decisions; Park: ~13 PRs of docs-about-docs / marginal polish) - Next sprint opening checklist No code change. Foundation for two follow-up PRs (S3 registry section, W1+W5 release-please kick automation). Refs: Codex consultations during the 5-day sprint (PR #860 78→91, PR #864 dogfood, PR #877 riskAssessment, post-stop 13 PRs). Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
3 者ディスカッション (Claude → Codex → Gemini → Codex 最終 / 91/100) を経て確定した コンセプト v4 を README / vision / intro に反映します。
新ポジショニング: "Codify your team's judgment into automated PR gates."
Changes
README.mdREADME.en.mddocs/vision.mdpages/explanation/intro.md(.en.md).gitignoredocs/Working/(session-local 草稿) を除外持続的な差別化の主張順
AI 監査軸は副軸として残し、主軸は「判断基準の所有権」に据えています。実装エージェント (Claude Code / Cursor / Codex) は変わっても、repo-owned skills と gates は残る、という設計判断です。
ディスカッション履歴
隣接 PR / Issue
Verification
npm run lint(markdownlint + prettier + dashes + textlint) ✅npm run check:links:local(lychee 942 links, 0 errors) ✅npm run build(Docusaurus production build) ✅src/lib/riverbed-memory.mjs)Test plan
🤖 Generated with Claude Code