agentleFS
apokamoapokamo/kaji/.claude/skills/issue-small-change-execute/SKILL.md

issue-small-change-execute

Skill16 starsChanged yesterdayApache-2.0View on GitHub

dev-small workflow の方針確認・実装・検証工程。Issue の決定事項を要件の正本として小修正を実装し、commit 前の必須検証を通して commit・報告する。設計書は要求しない。

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    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:

    ワークフロー内の位置: start → baseline → change → review-change → (fix-change → verify-change) → pr → close

    line 20

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Issue Small Change Execute

dev-small(.kaji/wf/custom/dev/dev-small.yaml)の change / fix-change step。 Issue 本文と人間の決定事項を要件の正本とし、短い方針 → baseline scope 評価 → 実装・docs → 差分確認 → commit 前の必須検証 → commit → 報告 を 1 工程で行う。

いつ使うか

タイミングこのスキル
dev-small の change(初回・RETRY 再入)/ fix-change(review 系 RETRY 後)✅
標準 dev(dev.yaml / dev-thorough*)の実装❌ /issue-implement
docs-only(type:docs)❌ docs workflow

ワークフロー内の位置: start → baseline → change → review-change → (fix-change → verify-change) → pr → close

入力

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

変数用途
issue_id / issue_ref / step_id / verdict_path対象 Issue、phase(change / fix-change)、verdict 保存先
worktree_dir / branch_name / default_branch / git_remote作業対象(差分範囲の基点は [git_remote]/[default_branch])
cycle_count / max_iterations参照可

design_path は注入されても使わない。

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

$ARGUMENTS = <issue_id>

worktree_dir が無い場合だけ _shared/worktree-resolve.md で絶対パスを得る。 step_id が無い場合は verdict marker から phase を決める: review-change / verify-change の最新 RETRY が 最新 fix-change 報告より新しければ fix-change、それ以外は change (kaji issue resolve-verdict [issue_id] --step <step> の created_at を比較)。 marker が欠落して source: "artifact" で返った場合は ended_at を ISO 8601 の時刻として比較し、null(時刻不明)で比較が必要なら推測せず停止する。

以降の [worktree_dir] は注入値または解決した絶対パス。Bash は毎回 cd [worktree_dir] && ... で実行する。

読み込み条件

区分読むもの条件
通常Issue 本文・labels(kaji issue view [issue_id] --json title,body,labels)常時
通常git status --porcelain / git log --oneline [git_remote]/[default_branch]..HEAD常時
通常直近の review 系 RETRY 報告 1 件fix-change
通常直近の自 step RETRY 報告 1 件change の RETRY 再入
条件付きdocs/reference/python/*.mdPython コードを書く場合
条件付きdocs/dev/testing-convention.md § テストサイズ定義 / § テスト戦略の原則テストを追加・変更する場合
例外docs/dev/baseline-check.md--evaluate が clean 以外、または artifact 不整合
例外Issue 本文が参照する人間コメント本文が参照している、または決定の特定に不確実さがある場合
例外docs/dev/workflow_completion_criteria.md § type 別に追加で確認する項目bug で実ログを修正前 Red の代替にする場合
例外docs/dev/documentation_update_criteria.md 該当節docs 影響の判断に迷う場合
例外失敗した検証の関連ログ全文検証失敗時
例外_shared/report-unrelated-issues.md無関係な問題を発見した場合

設計書(draft/design/**)、標準 dev の実装手順・type 別ガイド・Pre-Handoff Review 資料は読まず、要求もしない。 Issue の全コメント履歴を無条件に読み直さない。

直近の RETRY 報告の取得(1 行目の verdict marker を厳密照合し最新 1 件):

# fix-change: review 系の最新 RETRY
kaji issue view [issue_id] --json comments \
  | jq -r '[.comments[] | select(.body | test("^<!-- kaji-verdict: step=(review-change|verify-change) status=RETRY -->"))] | last | .body'
# change の RETRY 再入: 自 step の最新 RETRY
kaji issue view [issue_id] --json comments \
  | jq -r '[.comments[] | select(.body | test("^<!-- kaji-verdict: step=change status=RETRY -->"))] | last | .body'

実行手順(change)

Step 1: 前提確認

  • worktree と branch が存在すること。
  • type:* ラベルがちょうど 1 件であること。0 件・複数は ABORT。type:docs は docs workflow を案内して ABORT (type を付け替えない)。
  • 下記「入場時の working tree 判定」を満たすこと。

Step 2: 適用判定

次をすべて満たさなければ適用外として ABORT する(正本: docs/dev/workflow_guide.md § dev-small の適用条件)。

  • 期待動作・対象・受け入れ条件が Issue で明確
  • 大きな設計判断が残らない(公開互換性・権限境界・データ移行・再開処理・状態永続化・merge 条件等の判断を伴わない)
  • 影響範囲を説明できる
  • 既存検証または局所的な回帰テストで確認できる
  • 通常の revert で戻せる
  • ### ワークフロー完了後の確認項目 を除く完了条件に、dev-small で満たせない項目がない (設計書の作成・設計書への準拠・設計レビューなど、dev-small にない工程の成果物を前提とする項目。 例: issue-create テンプレート由来の「設計書作成」「設計書のテスト戦略に従い S/M/L を網羅」。 判定基準の正本: docs/dev/workflow_guide.md § dev-small の適用条件)

完了条件に dev-small で満たせない項目がある場合は、実装前に(Step 3 以降に進まず)適用外として ABORT する。 判定に迷う項目は ABORT 側に倒し、報告に理由を書く。Issue 本文の該当項目は書き換え・削除・チェックしない。 報告には該当した項目(本文の文言をそのまま引用)と前提とする dev-small にない工程を記し、人間が決める事項として 「該当項目を dev-small に合わせて本文から変更するか、標準 dev に切り替えるか」を明記する。

Step 3: 短い方針(編集前に確定。承認待ちにしない)

変更内容 / 維持する不変条件 / 変更対象 path / 確認方法(追加・変更するテストと実行する検証コマンド)/ docs 影響。 根拠とした Issue の決定事項を示す。

Step 4: baseline scope 評価(1 回)

変更対象 path ごとに --scope を繰り返し、--worktree を必ず渡す。

cd [worktree_dir] && source .venv/bin/activate && \
  python -m kaji_harness.scripts.baseline_precheck --worktree [worktree_dir] \
    --evaluate --scope <path1> --scope <path2>
  • verdict が missing_baseline / stale_baseline、または baseline_status が blocked / invalid → ABORT
  • known_failures で stop: true、または stop: false でも既知 failure が変更対象と意味的に関連 → ABORT
  • clean、または無関係な known_failures → 継続。baseline_status で Step 7 の gate を決める

Step 5: 実装

  • bug: 修正前に失敗する回帰テストを置き、修正後の成功を確認する(実ログ代替は既存 escape clause の範囲内)
  • feature: 新しい挙動のテストを追加する
  • refactor: 既存テストで振る舞い非変更を確認する。測定方法が決まっていない改善指標が必要なら適用外 ABORT
  • その他の type: feature と同等
  • テストには small / medium / large marker を付ける。docs 更新は本工程で完了させる

Step 6: 実装者の差分確認

git status と git diff(未 commit 分を含む)で、Issue scope 外の変更・一時ファイル・秘密情報がないことを確認する。 commit message・報告に auto-close hazard pattern(closing keyword + Issue 番号)を書かない。

Step 7: commit 前の必須検証

成功するまで commit しない。検証後に編集したら再検証する。

  • baseline clean: source .venv/bin/activate && make check
  • baseline known_failures: 次の全 PASS と、--compare の verdict: ok かつ regressions: []。空配列や終了コードだけで成功扱いしない

    cd [worktree_dir] && source .venv/bin/activate && \
      ruff check kaji_harness/ tests/ experiments/ && \
      ruff format --check kaji_harness/ tests/ experiments/ && \
      mypy kaji_harness/ && \
      python -m kaji_harness.scripts.baseline_precheck --worktree [worktree_dir] --compare
  • 変更に応じた追加検証(docs を変更したら make verify-docs、workflow YAML を変更したら make validate-workflows 等)

Step 8: commit

commit 対象の差分がある場合だけ行う(fix-change で差分がなければ省略し、報告に「新規 commit なし」と理由を記す)。 対象 path を明示して stage し、Issue type に対応する Conventional Commits prefix(feat / fix / refactor / test / docs / chore)で commit する。commit 後に git status --porcelain が空であることと HEAD の full SHA を確認する。

Step 9: 報告

下記「報告」に従い Issue コメント → stdout → kaji verdict publish(verdict_path への公開)の順に残す。

実行手順(fix-change)

change との差分だけを示す。Step 1 と Step 6〜9 は共通。

  • 入力は直近の review 系 RETRY 報告 1 件。特定できなければ ABORT。指摘ごとに修正するか、根拠を示して反論する。指摘外の改善を混ぜない。
  • 「報告 SHA と HEAD の不一致」指摘は、追加 commit の差分を確認し、Step 6〜7 を行って報告に含める。 HEAD が確認済みの差分をすでに含み working tree が clean なら、Step 8 の commit は行わない(空 commit を作らない)。
  • 全指摘を反論で対応した場合など、修正による差分が生じなければ Step 8 の commit は行わない。
  • 引き継いだ dirty path は「入場時の working tree 判定」で受け入れた場合だけ扱う。
    • Issue scope 内の実装変更(例: レビュー前停止中の未 commit 変更): 差分確認・検証の上で commit する
    • review の検証が生成・変更した path: 原因(テストや設定が tracked file を書き換える等)を修正したうえで、 報告で検証由来と特定された path に限り HEAD の内容へ戻す
    • scope 外・意図を判断できない変更: 保全して ABORT
    • どの扱いにしたかを指摘対応表に記録する
  • 修正で大きな設計判断が必要と判明したら適用外 ABORT。検証失敗を解消できない場合も ABORT(fix-change は RETRY を持たない)。
  • Step 4 の scope 評価は、修正で変更対象 path が増えた場合だけ増えた path で再実行する。

入場時の working tree 判定

dirty tree を無条件に取り込まない。

入場の種類入力報告working tree が dirty の場合
change 初回(自 step の報告なし)なし不明な変更として保全し ABORT
change の RETRY 再入直近の自 step RETRY 報告下記 3 条件をすべて満たす場合だけ引き継ぐ
fix-change直近の review 系 RETRY 報告下記 3 条件をすべて満たす場合だけ引き継ぐ

引き継ぐ条件:

  1. 現在の HEAD full SHA が入力報告の記載 SHA と一致する
  2. 現在の git status --porcelain の全 path が入力報告の dirty path 一覧に含まれる
  3. 各 path の実際の差分が報告記載の原因(作業途中の実装変更 / レビュー前停止中の未 commit 変更 / 検証による変更 等)と矛盾しない

1 つでも満たさなければ、restore・stash・commit のいずれもせず保全し ABORT する(該当 path と不一致の内容を報告)。 working tree が clean の場合は、入力報告がある入場で記載 SHA と HEAD の一致だけを確認し、不一致なら同様に ABORT する。

報告

1 コメントにまとめる。1 行目の verdict marker は kaji issue comment が付与する。

kaji issue comment [issue_id] --commit \
  --verdict-step [step_id] --verdict-status <STATUS> --body-file - <<'EOF'
## 小修正 実装報告([step_id])

(本文)

---VERDICT---
(verdict block)
---END_VERDICT---
EOF

本文の項目:

  • change: 方針(Step 3)。fix-change: 指摘対応表(指摘 N → 修正 / 反論と根拠 / 引き継いだ dirty path の扱い)
  • 対象 commit(full SHA)と変更ファイル要約
  • 検証: コマンド・終了状態・pytest 集計・--evaluate / --compare JSON の要点。成功時はログ全文を貼らず、失敗時は関連部分を引用
  • docs 更新、未解決事項
  • 引き継ぎ状態: 報告時の HEAD full SHA と working tree(clean、または dirty path ごとの原因)
  • ABORT 時: 停止理由(該当条件と根拠。完了条件と dev-small の不整合なら該当項目の引用と前提とする工程)、 人間が決める必要のある事項(不整合なら本文変更 / 標準 dev 切替の選択)、完了済み / 未完了の作業、branch・worktree path・ HEAD full SHA・git status --porcelain の要約、関連報告の参照、「再実行は初めから」の案内

同じ説明を他工程・PR へ全文複製しない。Issue コメント投稿に失敗した場合は ABORT とし、verdict を stdout に出して kaji verdict publish で公開する。

副作用の境界

対象 worktree 内の編集・commit と Issue コメント投稿のみ。既存 commit の書き換え(amend / rebase / reset)はしない。 push・PR 作成・merge・label 変更・worktree 作成/削除・Issue 本文編集・session-state 編集・他 workflow 起動はしない。 適用外 ABORT でも worktree・branch・dirty 変更は保全する。

Verdict 出力

作業報告コメント末尾、stdout に同じ内容を残し、最後に prompt の kaji verdict publish で verdict_path へ公開する(verdict_path を直接書かない)。

---VERDICT---
status: PASS
reason: |
  方針どおり実装し、必須検証を通して commit した
evidence: |
  HEAD <full SHA>、make check exit 0(pytest N passed)、working tree clean
suggestion: |
---END_VERDICT---
stepstatus条件
changePASS実装・必須検証・commit・報告が完了し、working tree が clean
changeRETRY新しい session で解消できる実装・検証・報告の失敗が残る(dirty path は原因付きで報告)
changeABORT適用外(完了条件と dev-small の不整合を含む)、type ラベル不正、baseline 前提違反・停止、引き継ぎ条件を満たさない dirty tree・HEAD 不一致、provider 障害
fix-changePASS全指摘に対応(修正または反論)し、必須検証・報告が完了し(差分があれば commit 済み)、working tree が clean
fix-changeABORT適用外、検証失敗を解消できない、入力の RETRY 報告を特定できない、引き継ぎ条件を満たさない dirty tree・HEAD 不一致、scope 外・意図不明の未 commit 変更、provider 障害

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.