feat(agent): スキル表示名の human-in-the-loop 畳み込み確定フロー（ADR-0016 D11 #476） - #495
Merged
Conversation
ADR-0016 D8 の残課題「表示名・粒度の畳み込み（agent 提案→人間確定）」を D11 として 実装。package/infra の生スキル名を agent が読みやすい表示名・グループへ提案し、人間が 確認・編集して確定・永続化する。確定値は Layer 1-2（機械・洗い替え対象）から切り離した 独立テーブル github_skill_display_decisions に安定 identity で保存し、再連携の洗い替えに 耐える。serve 時の解決順は「確定値 > 機械 display_name(Linguist) > canonical」。 backend: - 新テーブル + migration 0048 / GitHubSkillDisplayDecisionRepository - services/agent/skill_display（proposer + output_schema）+ prompt。agent は提案のみ・ メンバーは動的 enum で捏造排除・リトライ1回・課金は既存契約流用（ADR-0010/0012/0013） - エンドポイント: POST propose（billed）/ PUT confirm（authz）/ GET skills（decision join） - 課金後処理 record_usage_after_llm を billing service へ集約（agent router と共用） - 提案は language を除外し package/infra に限定、キャップ 50（入力・enum 肥大の抑制） web: - ダッシュボードにスキル一覧 + 提案レビュー/確定 UI（SkillDisplaySection） - 決定論ロジックは utils/skillDisplay に切り出し TDD（red→green） - ダークモード対応のためテーマトークンで配色 ADR-0016 に D11 を追補・改訂履歴・索引整合を更新。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis PR adds a human-in-the-loop GitHub skill display workflow. It persists confirmed names and groups, generates constrained LLM proposals, exposes proposal and confirmation APIs, and adds frontend state management, review UI, tests, and ADR-0016 documentation. ChangesGitHub skill display decisions
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant SkillDisplaySection
participant useGitHubSkills
participant GitHubLinkAPI
participant LLMProposer
User->>SkillDisplaySection: Request display-name proposal
SkillDisplaySection->>useGitHubSkills: propose()
useGitHubSkills->>GitHubLinkAPI: POST display-names/propose
GitHubLinkAPI->>LLMProposer: Generate constrained groups
LLMProposer-->>GitHubLinkAPI: Proposed groups
GitHubLinkAPI-->>useGitHubSkills: Proposal response
User->>SkillDisplaySection: Edit and confirm groups
SkillDisplaySection->>useGitHubSkills: confirm()
useGitHubSkills->>GitHubLinkAPI: PUT display-decisions
GitHubLinkAPI-->>useGitHubSkills: Enriched skills
useGitHubSkills-->>SkillDisplaySection: Render confirmed names
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
backend/app/repositories/skill.py (1)
119-130: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winDeduplicate inputs to prevent potential Unique Constraint violations.
If
decisionscontains duplicate items for an identity that is not yet in the database,self.db.add()will be called multiple times for the same key. This will result in anIntegrityError(500 Internal Server Error) whenself.db.commit()is executed.Consider deduplicating the input array by its identity key to gracefully handle any duplicates from the client.
♻️ Proposed refactor to deduplicate items
existing = { (d.kind, d.ecosystem, d.canonical_name): d for d in self.get_for_user() } - for item in decisions:++ unique_decisions = {+ (d.kind, d.ecosystem, d.canonical_name): d for d in decisions+ }.values()++ for item in unique_decisions: key = (item.kind, item.ecosystem, item.canonical_name) current = existing.get(key) if current is not None:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@backend/app/repositories/skill.py` around lines 119 - 130, Deduplicate decisions by the (kind, ecosystem, canonical_name) identity before the add/commit flow in the repository method containing the existing map and decisions loop. Ensure only one item per key is processed, while preserving updates for existing records and preventing duplicate new records from reaching self.db.add().
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@backend/app/routers/github_link/endpoints.py`:
- Around line 237-272: Cap the number of entries accepted by
SkillDisplayConfirmRequest.decisions using the project’s established
request-validation convention, such as a max_items constraint. Choose the
intended maximum batch size and ensure oversized requests are rejected before
confirm_skill_display_decisions performs identity validation or calls
upsert_many.
- Around line 237-257: Update confirm_skill_display_decisions to reject
decisions whose kind is SKILL_KIND_LANGUAGE, matching the exclusion used by the
propose-side flow. Apply this validation before persisting any decisions, while
preserving the existing identity validation and allowing only package/infra
skills.
In `@web/src/components/github-link/SkillDisplaySection.tsx`:
- Around line 58-69: Disable the Propose button whenever an existing proposal is
open, in addition to the current proposing and confirming guards, so propose()
cannot replace a proposal while confirm() is still using it. Update the matching
button guard in the alternate section around the referenced lines as well,
preserving the existing loading labels and click behavior.
- Around line 83-89: Update the proposal name input in SkillDisplaySection so
each field’s aria-label uniquely identifies its skill group, incorporating the
row’s group-specific display name or another available unique identifier while
retaining the existing label context. Ensure assistive technology can
distinguish inputs across all proposal rows.
In `@web/src/hooks/useGitHubSkills.ts`:
- Around line 39-49: Clear the existing error state at the start of the reload
callback in useGitHubSkills, before calling getGitHubSkills. Preserve the
current success, failure, loading, and cleanup behavior so a successful retry
leaves error null while failures still record the converted error.
---
Nitpick comments:
In `@backend/app/repositories/skill.py`:
- Around line 119-130: Deduplicate decisions by the (kind, ecosystem,
canonical_name) identity before the add/commit flow in the repository method
containing the existing map and decisions loop. Ensure only one item per key is
processed, while preserving updates for existing records and preventing
duplicate new records from reaching self.db.add().
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 948bf89e-19b3-4bab-9440-df3b1289e7c7
📒 Files selected for processing (30)
backend/alembic_migrations/versions/0048_add_github_skill_display_decision.pybackend/app/messages.jsonbackend/app/models/__init__.pybackend/app/models/skill.pybackend/app/prompts/agent_skill_display.mdbackend/app/repositories/skill.pybackend/app/routers/agent.pybackend/app/routers/github_link/_responses.pybackend/app/routers/github_link/endpoints.pybackend/app/schemas/github_skill.pybackend/app/services/agent/skill_display/__init__.pybackend/app/services/agent/skill_display/output_schema.pybackend/app/services/agent/skill_display/proposer.pybackend/app/services/billing/credit_service.pybackend/tests/test_skill_display_api.pybackend/tests/test_skill_display_service.pydocs/adr/0016-github-skill-inference.mdweb/e2e/github-link.spec.tsweb/src/api/generated.tsweb/src/api/githubLink.tsweb/src/api/paths.tsweb/src/api/types.tsweb/src/components/github-link/GitHubLinkDashboard.tsxweb/src/components/github-link/SkillDisplaySection.module.cssweb/src/components/github-link/SkillDisplaySection.tsxweb/src/constants/messages.tsweb/src/hooks/useGitHubSkills.test.tsweb/src/hooks/useGitHubSkills.tsweb/src/utils/skillDisplay.test.tsweb/src/utils/skillDisplay.ts
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
- レビュー中（提案表示中）は再提案ボタンを無効化し、確定待ちの提案を取りこぼさない - 提案レビューの表示名入力に対象スキルを含めた aria-label を付与（各行を支援技術で区別可能に） - useGitHubSkills.reload の成功時に error をクリア（前回の失敗表示が残らないように） Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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 freeto 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.
概要
issue #476（ADR-0016 D8 の残課題「表示名・粒度の畳み込みの human-in-the-loop 確定」）を D11 として実装。GitHub 連携で検出した package / infra の生スキル名を agent が読みやすい表示名・グループへ提案し、人間が確認・編集して確定・永続化する一連のフローを追加する。
Closes#476
設計（ADR-0016 D11 として追補）
github_skills）から切り離したgithub_skill_display_decisionsに安定 identity（kind + ecosystem + canonical_name）で保存。これで再連携の洗い替えに耐え、N:1 グルーピングも表現できる（D1「機械=幅 / 人間=深さ」）。display_name（Linguist）>canonical_name。既存display_nameは機械フォールバックとして温存。主な変更
backend
0048/GitHubSkillDisplayDecisionRepositoryservices/agent/skill_display/（proposer + output_schema）+ prompt。リトライ1回・課金 usage の合算・エラー契約はチャット/ドラフトと同一POST .../skills/display-names/propose（billed・rate limit）/PUT .../skills/display-decisions（authz 付き確定・バッチ upsert）/GET .../skills（decision を join）record_usage_after_llmを billing service へ集約（agent router と共用・DRY化）web
SkillDisplaySection）utils/skillDisplay.tsに切り出し TDD（red→green）--bg-section等）で配色ドキュメント
テスト
make test-backend全 passutils/skillDisplay.test.ts/hooks/useGitHubSkills.test.ts（loading/success/error）make cigreen /make codegen-types反映済み（drift なし）補足
🤖 Generated with Claude Code
Summary by CodeRabbit