agentleFS
apokamoapokamo/kaji/.claude/skills/i-doc-review/SKILL.md

i-doc-review

Skill16 starsChanged 2 days agoApache-2.0View on GitHub

docs-only の変更をレビューし、事実整合性・実装整合性・運用整合性の観点から判定する。

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    ワークフロー内の位置: update-doc → review-doc → (fix-doc → verify-doc) → i-doc-final-check → i-pr

    line 20
  2. Distinctive:

    Must Fix / Should Fix を整理して Issue にコメントする。

    line 90

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

I Doc Review

重要: このスキルは更新を行ったセッションとは別のセッションで実行することを推奨します。

CRITICAL: このレビューの目的は文章を整えることではない。現行実装との差異、古い手順、誤誘導となる記述を発見すること。

docs-only の変更をレビューする。新規指摘を行ってよい。

いつ使うか

タイミングこのスキルを使用
i-doc-update 完了後✅ 必須

ワークフロー内の位置: update-doc → review-doc → (fix-doc → verify-doc) → i-doc-final-check → i-pr

入力

ハーネス経由(コンテキスト変数)

変数型説明
issue_idstr正規化済み Issue ID(GitHub 数値)
issue_refstr人間可読の Issue 参照(GitHub では #<issue_id>)
step_idstr現在のステップ ID
git_remotestrgit remote 名(provider.<type>.git_remote config から解決)。差分範囲の基点 [git_remote]/[default_branch] に使用
default_branchstrdefault branch 名(provider.<type>.default_branch config から解決)。差分範囲の基点に使用
cycle_countint現在のイテレーション
max_iterationsintサイクルの上限回数

手動実行(スラッシュコマンド)

$ARGUMENTS = <issue_id>

解決ルール

コンテキスト変数 issue_id が存在すればそちらを使用。 なければ $ARGUMENTS の第1引数を issue_id として使用。

issue_ref はハーネス経由ではプロンプトに自動注入される(prompt.py 側で provider 別に整形)。手動実行時は issue_id から #<issue_id> を導出する。

前提知識の読み込み

  1. docs/dev/documentation_update_criteria.md
  2. docs/dev/shared_skill_rules.md

実行手順

Step 1: コンテキストの取得

  1. _shared/worktree-resolve.md の手順に従い、Worktree の絶対パスを取得
  2. Issue コメントから直近の docs-only 更新報告を確認
  3. 設計書を確認:
    cat [worktree_dir]/draft/design/issue-[issue_id]-*.md
  4. 差分を確認:
    cd [worktree_dir] && git diff [git_remote]/[default_branch]...HEAD

Step 2: レビュー

docs/dev/documentation_update_criteria.md の 3 観点(事実整合性・実装整合性・運用整合性)で厳格にレビューする。

  1. 現行実装と一致しているか
  2. CLI コマンド例が現行仕様と一致するか
  3. AGENTS.md / CLAUDE.md の運用方針と矛盾しないか
  4. workflow / skill / docs 間で記述が矛盾しないか
  5. リンク切れ、古いパス、読者導線の破綻がないか

Step 3: 変更ファイル限定リンクチェック

変更された Markdown ファイルに絞って以下を実行する。

cd [worktree_dir] && python3 scripts/check_doc_links.py [changed-markdown-files...]

Step 4: 結果を Issue にコメント

Must Fix / Should Fix を整理して Issue にコメントする。

verdict マーカーの無条件付与(必須): 判定コメントには 常に --verdict-step doc-review --verdict-status <STATUS> を付ける。<STATUS> は本 skill が「Verdict 出力」で返す status(PASS / RETRY / ABORT)に置き換える。CLI が body 1 行目に <!-- kaji-verdict: step=doc-review status=<STATUS> --> を付け、kaji issue resolve-verdict --step doc-review と runner の comment fallback はこの marker で発行元 step を特定する。PASS でも省略しない(条件付きの付与は禁止。docs/dev/shared_skill_rules.md § verdict マーカー契約)。投稿前に判定を確定してから status を決める。末尾の ---VERDICT--- ブロックの status も <STATUS> と同じ値にする。

kaji issue comment [issue_id] --commit \
  --verdict-step doc-review --verdict-status <STATUS> \
  --body-file - <<'EOF'
# docs レビュー結果

## 概要

(一言で言うとどうだったか)

## 指摘事項 (Must Fix)

- [ ] **[対象ファイル:行]**: (指摘内容と根拠)

## 改善提案 (Should Fix)

- (任意の改善提案。なければ「なし」)

## リンクチェック結果

(Step 3 の `check_doc_links.py` の出力)

---VERDICT---
status: <STATUS>
reason: |
  (判定理由)
evidence: |
  (具体的根拠)
suggestion: |
  (次のアクション)
---END_VERDICT---
EOF

Verdict 出力

---VERDICT---
status: RETRY
reason: |
  docs の整合性レビューで修正事項が見つかった
evidence: |
  実装との差異、運用方針との不一致、または読者を誤誘導する記述を確認した
suggestion: |
  Issue コメントの指摘に従って `i-doc-fix` で修正すること
---END_VERDICT---

status の選択基準

status条件
PASS修正不要で i-doc-final-check へ進める
RETRYdocs 修正で解決可能
ABORTdocs-only の範囲を超える重大な問題

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.