SKILLOfficialdevelopment

aidp-fixup-cell

プラグイン: oracle-ai-data-platform-workbench-databricks-migrator
ソース: GitHub で見る ↗

説明

移行済みノートブックの対象を絞った巻き戻し。履歴インデックスNの位置から以降のセル（または指定した範囲のセル）を、実行→検証→修正のループを通じて再度実行します。その際に「なぜ修正が必要なのか」という理由を Claudeに与えることで、何を直せばよいかを理解できるようにします。 **次のような場合に使用:** - aidp-migrate-job（ノートブック移行ツール）でノートブックが RESULT=PARTIAL（部分的な成功）の状態で終わった場合 - ユーザーが移行後に特定のセルが間違っていることに気づいた場合

原文を表示

Targeted rewind of a migrated notebook. Re-executes cells from history index N onwards (or a specific cell range) through the execute+verify+fix loop, with a 'why' reason injected so Claude knows what to fix. Use when aidp-migrate-job left a notebook at RESULT=PARTIAL or the user identifies a specific cell that is wrong post-migration.

ユースケース

ノートブック移行が部分的に失敗した場合
移行後のセルに誤りを発見した場合
特定範囲のセルを再実行・検証する場合

本文（日本語訳）

`aidp-fixup-cell` — 移行済みノートブックのセルを外科的に再実行する

フルジョブ移行ツール（job_migrate.py）は全セルを順次実行し、各セルに最大10回の修正を試みます。fixup_cell は、その10回の試行では不十分だった場合、またはユーザーが後続処理で潜在的な問題を発見した場合のための、セル単位のエスケープハッチです。

次のような場合に使用:

aidp-migrate-job の完了後、JOB_REPORT.md に特定セルが FAIL と表示されている。
ユーザーが以前に移行済みのノートブックの特定セルを指して「ここがおかしい、修正してほしい」と言っている。
ユーザーがセル K を手動編集して事前条件を設定し、その変更を反映した状態でセル K+1〜K+N を再実行したい。

2つの起動モード

モード A — 履歴インデックスからの再実行（Opus ツール）

既に実行中の移行処理の中で、Claude は fixup_cell ツールを次のように呼び出せます:

fixup_cell(start_index=12, why="cell 11 redefined `<base_table>` to use a different schema; replay downstream so the new var flows through")

これはインプロセスモードです。以下の処理を行います:

_cell_history[start_index:] を切り捨てる（インデックス12以降をすべて破棄）。
各エントリを _replay_cell_entry() で再実行する — 実行・検証・修正のループで、why が Claude プロンプトに注入され、モデルが何が変わったかを把握できる。
新しい（再実行後の）エントリを _cell_history に追記する。

再実行されるセルは、絶対履歴インデックス12から始まります。%run によってインライン展開されたセルの場合、同じノートブック内のセルとは限らず、後続のノートブックのセルである可能性もあります。

モード B — 保存済みノートブックに対するスタンドアロン再実行

移行が完了した後、「この1セルを修正したい」場合:

python3 ${CLAUDE_PLUGIN_ROOT}/engine/scripts/job_migrate.py \
  --manifest reports/<MyJob>_manifest.json \
  --cluster <CLUSTER_ID> \
  --only-tasks <task_key> \
  --no-skip-migrated

これにより、該当タスクを最初から最後まで再実行します（依存関係はすでにキャッシュ済みのため高速）。--start-task <substring> と組み合わせることで、そのタスクだけを実行できます。

より細かい制御（タスク全体ではなく特定セルのみ）が必要な場合は、保存済みの .ipynb を開いて手動編集する必要があります。移行ツールは、インプロセスの fixup_cell ツール以外に「セル K だけを再実行する」CLI を提供していません。

`fixup_cell` が有効な場合と有効でない場合

有効な場合:

移行ツールの自動修正では想定していなかった上流の状態（変数の形状、スキーマのドリフト、import の欠落）によってセルが失敗している。
最初のパスで Claude が持っていなかったコンテキストがセルに必要（隠れた依存関係、ユーザーが直前に適用した手動オーバーライドなど）。
構造的な修正（例: 関数の再定義）の後、ノートブックのフローを最初から再実行する必要がある。

有効でない場合:

クラスター自体の設定が誤っている（JAR の欠損、Spark バージョンの不一致）— セルではなくクラスターを修正する。
ソースデータが存在しない、または形状が誤っている — セルではなくデータを修正する。
移行ツールが既知の不正なコードを生成している（例: 書き換えられるべき dbutils 呼び出し）— references/gotchas.md でレシピを確認し、修正を適用してから再実行する。

重要: べき等性の要件

fixup_cell はセルを start_index 以降の順に再実行します。これは再実行するセルがべき等である場合にのみ安全です。セルが以下のような処理を行う場合:

.mode("overwrite") でサンドボックステーブルに書き込む → 安全。
.mode("append") でサンドボックステーブルに書き込む → 危険。再実行時に行が重複する。
外部状態を変更する（REST API 呼び出し、OCI Object Storage への書き込みなど）→ 危険。

再実行をトリガーする前に、start_index 以降のセルにべき等でない操作がないか確認してください。見つかった場合は、まずそのセルを修正してから再実行してください。

`why` の理由がどのように伝わるか

why 文字列は以下のように Claude プロンプトに注入されます:

=== CONTEXT: WHY WE'RE REPLAYING ===
The previous run hit a problem at this stage. Reason: <your why>

Replay each cell with this context in mind. If the prior code was correct
and only the upstream state changed, you can keep it as-is. If the prior
code needs adjustment to handle the new state, rewrite as needed.

why は正確に記述してください — 曖昧な理由は曖昧な修正しか生みません:

✅ 良い例: "cell 11 was rewritten to use spark.read.table('<sandbox_schema>.events') instead of spark.read.parquet('s3://...'); downstream cells reference the same path and need similar adjustment"
❌ 悪い例: "something broke, please retry"

`fixup_cell` が必要な失敗とそうでない失敗の見分け方

症状	対処
セル K が10回試行してもすべて同じエラーで失敗する	エラーを明記した具体的な `why` を指定して `fixup_cell` を試みる。
セル K-2 が想定と異なるスキーマを出力したため、セル K が失敗した	K-2 から `fixup_cell` を実行し（K からではなく）、`why` に上流の変更を記述する。
既知の落とし穴（references/gotchas.md 参照）によってセル K が失敗した	セル K に落とし穴のレシピを手動適用してから、`why="applied gotcha #N fix"` を指定して K から `fixup_cell` を実行する。
実行途中でクラスターがダウンしてセル K が失敗した	クラスターを再起動し、`--skip-migrated` オプションで `aidp-migrate-job` を再実行する — `fixup_cell` は不要。

実行後の確認

JOB_REPORT.md を再確認し、該当セルが OK になっていることを確認する（/migration-status）。
再実行後にさらに別の失敗が発生した場合は、構造的な問題の可能性があります — セカンドオピニオンとして migration-reviewer にエスカレーションしてください。

原文（English）を表示

`aidp-fixup-cell` — surgical re-execute of cells in a migrated notebook

The full-job migrator (job_migrate.py) runs every cell linearly with up to 10 fix attempts each. fixup_cell is the per-cell escape hatch when those 10 attempts weren't enough OR when the user discovers a latent issue downstream.

When to use

JOB_REPORT.md shows specific cells as FAIL after aidp-migrate-job finished.
User points at a specific cell of a previously-migrated notebook and says "this is wrong, fix it".
User has manually edited cell K to set up a precondition, wants K+1..K+N to re-run accounting for the change.

Two invocation modes

Mode A — re-run from a history index (Opus tool)

Inside an already-running migration, Claude can call the fixup_cell tool:

fixup_cell(start_index=12, why="cell 11 redefined `<base_table>` to use a different schema; replay downstream so the new var flows through")

This is the in-process mode. It:

Truncates _cell_history[start_index:] (drops everything from index 12 forward).
Replays each old entry through _replay_cell_entry() — execute + verify + fix loop with the why injected into the Claude prompt so the model knows what changed.
Appends the new (post-replay) entries back to _cell_history.

The cells replayed start at the absolute history index 12 — could be in the SAME notebook or a downstream one if the cells were inlined via %run.

Mode B — standalone replay against a saved notebook

When the migration is done and the user wants to "fix this one cell":

python3 ${CLAUDE_PLUGIN_ROOT}/engine/scripts/job_migrate.py \
  --manifest reports/<MyJob>_manifest.json \
  --cluster <CLUSTER_ID> \
  --only-tasks <task_key> \
  --no-skip-migrated

This re-runs that single task end-to-end (deps already cached → fast). Combine with --start-task <substring> to run only that one task.

If the user wants finer-grained control (specific cell, not full task), they need to open the saved .ipynb and edit manually. The migrator doesn't expose a "replay cell K only" CLI outside of the in-process fixup_cell tool.

When fixup_cell will help — and when it won't

Helps:

The cell's failure is due to upstream state the migrator's auto-fix didn't anticipate (variable shape, schema drift, missing import).
The cell needs context Claude didn't have in the first pass (a hidden dependency, a manual override the user just applied).
The notebook flow needs to be replayed after a structural fix (e.g. you redefined a function).

Won't help:

The cluster itself is misconfigured (missing JAR, wrong Spark version) — fix the cluster, not the cell.
The source data is missing / wrong shape — fix the data, not the cell.
The migrator is generating a known-bad construct (e.g. a dbutils call that should have been rewritten) — check references/gotchas.md for the recipe, then re-run with the fix.

Important: idempotency requirement

fixup_cell replays cells from start_index FORWARD. This is only safe if the replayed cells are idempotent. If a cell:

writes to a sandbox table with .mode("overwrite") → safe.
writes to a sandbox table with .mode("append") → unsafe, will duplicate rows on replay.
mutates external state (REST API call, write to OCI Object Storage) → unsafe.

Before triggering a replay, scan the cells from start_index for non-idempotent ops. If you find any, fix THEM first, then replay.

How the `why` reason flows

The why string is injected into the Claude prompt as:

=== CONTEXT: WHY WE'RE REPLAYING ===
The previous run hit a problem at this stage. Reason: <your why>

Replay each cell with this context in mind. If the prior code was correct
and only the upstream state changed, you can keep it as-is. If the prior
code needs adjustment to handle the new state, rewrite as needed.

So make the why precise — vague reasons produce vague fixes:

✅ Good: "cell 11 was rewritten to use spark.read.table('<sandbox_schema>.events') instead of spark.read.parquet('s3://...'); downstream cells reference the same path and need similar adjustment"
❌ Bad: "something broke, please retry"

Spotting a failure that NEEDS fixup_cell vs one that doesn't

Symptom	Action
Cell K failed 10 attempts, all with the same error	Try fixup_cell with a specific `why` that names the error.
Cell K failed because cell K-2 produced a different schema than expected	fixup_cell from K-2 (not K) with `why` describing the upstream change.
Cell K failed because of a known gotcha (see references/gotchas.md)	Apply the gotcha-recipe fix in cell K manually, then fixup_cell from K with `why="applied gotcha #N fix"`.
Cell K failed because the cluster died mid-execution	Restart the cluster, re-invoke `aidp-migrate-job` with `--skip-migrated` — fixup not needed.

After this

Re-read JOB_REPORT.md to confirm the cell is now OK (/migration-status).
If the replay produced more failures, that's a structural problem — escalate to migration-reviewer for a second-opinion review.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。

SKILLOfficialdevelopment

aidp-fixup-cell

プラグイン: oracle-ai-data-platform-workbench-databricks-migrator
ソース: GitHub で見る ↗

説明

原文を表示

ユースケース

ノートブック移行が部分的に失敗した場合
移行後のセルに誤りを発見した場合
特定範囲のセルを再実行・検証する場合

本文（日本語訳）

`aidp-fixup-cell` — 移行済みノートブックのセルを外科的に再実行する

次のような場合に使用:

aidp-migrate-job の完了後、JOB_REPORT.md に特定セルが FAIL と表示されている。
ユーザーが以前に移行済みのノートブックの特定セルを指して「ここがおかしい、修正してほしい」と言っている。
ユーザーがセル K を手動編集して事前条件を設定し、その変更を反映した状態でセル K+1〜K+N を再実行したい。

2つの起動モード

モード A — 履歴インデックスからの再実行（Opus ツール）

既に実行中の移行処理の中で、Claude は fixup_cell ツールを次のように呼び出せます:

fixup_cell(start_index=12, why="cell 11 redefined `<base_table>` to use a different schema; replay downstream so the new var flows through")

これはインプロセスモードです。以下の処理を行います:

_cell_history[start_index:] を切り捨てる（インデックス12以降をすべて破棄）。
各エントリを _replay_cell_entry() で再実行する — 実行・検証・修正のループで、why が Claude プロンプトに注入され、モデルが何が変わったかを把握できる。
新しい（再実行後の）エントリを _cell_history に追記する。

モード B — 保存済みノートブックに対するスタンドアロン再実行

移行が完了した後、「この1セルを修正したい」場合:

python3 ${CLAUDE_PLUGIN_ROOT}/engine/scripts/job_migrate.py \
  --manifest reports/<MyJob>_manifest.json \
  --cluster <CLUSTER_ID> \
  --only-tasks <task_key> \
  --no-skip-migrated

`fixup_cell` が有効な場合と有効でない場合

有効な場合:

移行ツールの自動修正では想定していなかった上流の状態（変数の形状、スキーマのドリフト、import の欠落）によってセルが失敗している。
最初のパスで Claude が持っていなかったコンテキストがセルに必要（隠れた依存関係、ユーザーが直前に適用した手動オーバーライドなど）。
構造的な修正（例: 関数の再定義）の後、ノートブックのフローを最初から再実行する必要がある。

有効でない場合:

クラスター自体の設定が誤っている（JAR の欠損、Spark バージョンの不一致）— セルではなくクラスターを修正する。
ソースデータが存在しない、または形状が誤っている — セルではなくデータを修正する。
移行ツールが既知の不正なコードを生成している（例: 書き換えられるべき dbutils 呼び出し）— references/gotchas.md でレシピを確認し、修正を適用してから再実行する。

重要: べき等性の要件

.mode("overwrite") でサンドボックステーブルに書き込む → 安全。
.mode("append") でサンドボックステーブルに書き込む → 危険。再実行時に行が重複する。
外部状態を変更する（REST API 呼び出し、OCI Object Storage への書き込みなど）→ 危険。

`why` の理由がどのように伝わるか

why 文字列は以下のように Claude プロンプトに注入されます:

=== CONTEXT: WHY WE'RE REPLAYING ===
The previous run hit a problem at this stage. Reason: <your why>

Replay each cell with this context in mind. If the prior code was correct
and only the upstream state changed, you can keep it as-is. If the prior
code needs adjustment to handle the new state, rewrite as needed.

why は正確に記述してください — 曖昧な理由は曖昧な修正しか生みません:

✅ 良い例: "cell 11 was rewritten to use spark.read.table('<sandbox_schema>.events') instead of spark.read.parquet('s3://...'); downstream cells reference the same path and need similar adjustment"
❌ 悪い例: "something broke, please retry"

`fixup_cell` が必要な失敗とそうでない失敗の見分け方

症状	対処
セル K が10回試行してもすべて同じエラーで失敗する	エラーを明記した具体的な `why` を指定して `fixup_cell` を試みる。
セル K-2 が想定と異なるスキーマを出力したため、セル K が失敗した	K-2 から `fixup_cell` を実行し（K からではなく）、`why` に上流の変更を記述する。
既知の落とし穴（references/gotchas.md 参照）によってセル K が失敗した	セル K に落とし穴のレシピを手動適用してから、`why="applied gotcha #N fix"` を指定して K から `fixup_cell` を実行する。
実行途中でクラスターがダウンしてセル K が失敗した	クラスターを再起動し、`--skip-migrated` オプションで `aidp-migrate-job` を再実行する — `fixup_cell` は不要。

実行後の確認

JOB_REPORT.md を再確認し、該当セルが OK になっていることを確認する（/migration-status）。
再実行後にさらに別の失敗が発生した場合は、構造的な問題の可能性があります — セカンドオピニオンとして migration-reviewer にエスカレーションしてください。

原文（English）を表示

`aidp-fixup-cell` — surgical re-execute of cells in a migrated notebook

When to use

JOB_REPORT.md shows specific cells as FAIL after aidp-migrate-job finished.
User points at a specific cell of a previously-migrated notebook and says "this is wrong, fix it".
User has manually edited cell K to set up a precondition, wants K+1..K+N to re-run accounting for the change.

Two invocation modes

Mode A — re-run from a history index (Opus tool)

Inside an already-running migration, Claude can call the fixup_cell tool:

fixup_cell(start_index=12, why="cell 11 redefined `<base_table>` to use a different schema; replay downstream so the new var flows through")

This is the in-process mode. It:

Truncates _cell_history[start_index:] (drops everything from index 12 forward).
Replays each old entry through _replay_cell_entry() — execute + verify + fix loop with the why injected into the Claude prompt so the model knows what changed.
Appends the new (post-replay) entries back to _cell_history.

The cells replayed start at the absolute history index 12 — could be in the SAME notebook or a downstream one if the cells were inlined via %run.

Mode B — standalone replay against a saved notebook

When the migration is done and the user wants to "fix this one cell":

python3 ${CLAUDE_PLUGIN_ROOT}/engine/scripts/job_migrate.py \
  --manifest reports/<MyJob>_manifest.json \
  --cluster <CLUSTER_ID> \
  --only-tasks <task_key> \
  --no-skip-migrated

This re-runs that single task end-to-end (deps already cached → fast). Combine with --start-task <substring> to run only that one task.

When fixup_cell will help — and when it won't

Helps:

The cell's failure is due to upstream state the migrator's auto-fix didn't anticipate (variable shape, schema drift, missing import).
The cell needs context Claude didn't have in the first pass (a hidden dependency, a manual override the user just applied).
The notebook flow needs to be replayed after a structural fix (e.g. you redefined a function).

Won't help:

The cluster itself is misconfigured (missing JAR, wrong Spark version) — fix the cluster, not the cell.
The source data is missing / wrong shape — fix the data, not the cell.
The migrator is generating a known-bad construct (e.g. a dbutils call that should have been rewritten) — check references/gotchas.md for the recipe, then re-run with the fix.

Important: idempotency requirement

fixup_cell replays cells from start_index FORWARD. This is only safe if the replayed cells are idempotent. If a cell:

writes to a sandbox table with .mode("overwrite") → safe.
writes to a sandbox table with .mode("append") → unsafe, will duplicate rows on replay.
mutates external state (REST API call, write to OCI Object Storage) → unsafe.

Before triggering a replay, scan the cells from start_index for non-idempotent ops. If you find any, fix THEM first, then replay.

How the `why` reason flows

The why string is injected into the Claude prompt as:

=== CONTEXT: WHY WE'RE REPLAYING ===
The previous run hit a problem at this stage. Reason: <your why>

Replay each cell with this context in mind. If the prior code was correct
and only the upstream state changed, you can keep it as-is. If the prior
code needs adjustment to handle the new state, rewrite as needed.

So make the why precise — vague reasons produce vague fixes:

✅ Good: "cell 11 was rewritten to use spark.read.table('<sandbox_schema>.events') instead of spark.read.parquet('s3://...'); downstream cells reference the same path and need similar adjustment"
❌ Bad: "something broke, please retry"

Spotting a failure that NEEDS fixup_cell vs one that doesn't

Symptom	Action
Cell K failed 10 attempts, all with the same error	Try fixup_cell with a specific `why` that names the error.
Cell K failed because cell K-2 produced a different schema than expected	fixup_cell from K-2 (not K) with `why` describing the upstream change.
Cell K failed because of a known gotcha (see references/gotchas.md)	Apply the gotcha-recipe fix in cell K manually, then fixup_cell from K with `why="applied gotcha #N fix"`.
Cell K failed because the cluster died mid-execution	Restart the cluster, re-invoke `aidp-migrate-job` with `--skip-migrated` — fixup not needed.

After this

Re-read JOB_REPORT.md to confirm the cell is now OK (/migration-status).
If the replay produced more failures, that's a structural problem — escalate to migration-reviewer for a second-opinion review.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。

aidp-fixup-cell

aidp-fixup-cell — 移行済みノートブックのセルを外科的に再実行する

次のような場合に使用:

2つの起動モード

モード A — 履歴インデックスからの再実行（Opus ツール）

モード B — 保存済みノートブックに対するスタンドアロン再実行

fixup_cell が有効な場合と有効でない場合

重要: べき等性の要件

why の理由がどのように伝わるか

fixup_cell が必要な失敗とそうでない失敗の見分け方

実行後の確認

aidp-fixup-cell — surgical re-execute of cells in a migrated notebook

When to use

Two invocation modes

Mode A — re-run from a history index (Opus tool)

Mode B — standalone replay against a saved notebook

When fixup_cell will help — and when it won't

Important: idempotency requirement

How the why reason flows

Spotting a failure that NEEDS fixup_cell vs one that doesn't

After this

aidp-fixup-cell

aidp-fixup-cell — 移行済みノートブックのセルを外科的に再実行する

次のような場合に使用:

2つの起動モード

モード A — 履歴インデックスからの再実行（Opus ツール）

モード B — 保存済みノートブックに対するスタンドアロン再実行

fixup_cell が有効な場合と有効でない場合

重要: べき等性の要件

why の理由がどのように伝わるか

fixup_cell が必要な失敗とそうでない失敗の見分け方

実行後の確認

aidp-fixup-cell — surgical re-execute of cells in a migrated notebook

When to use

Two invocation modes

Mode A — re-run from a history index (Opus tool)

Mode B — standalone replay against a saved notebook

When fixup_cell will help — and when it won't

Important: idempotency requirement

How the why reason flows

Spotting a failure that NEEDS fixup_cell vs one that doesn't

After this

`aidp-fixup-cell` — 移行済みノートブックのセルを外科的に再実行する

`fixup_cell` が有効な場合と有効でない場合

`why` の理由がどのように伝わるか

`fixup_cell` が必要な失敗とそうでない失敗の見分け方

`aidp-fixup-cell` — surgical re-execute of cells in a migrated notebook

How the `why` reason flows

`aidp-fixup-cell` — 移行済みノートブックのセルを外科的に再実行する

`fixup_cell` が有効な場合と有効でない場合

`why` の理由がどのように伝わるか

`fixup_cell` が必要な失敗とそうでない失敗の見分け方

`aidp-fixup-cell` — surgical re-execute of cells in a migrated notebook

How the `why` reason flows