writing-univer-plans

Univer プランの作成

SaC アサーションや移行ソースの作業に着手する前に、ワークブック領域の成功基準とプランを作成します。成功基準では、目標とする成果をチェックリストとして固定します。プランは、チャット内だけのメモではなく、ソースを起点とする作成成果物です。

これは一般的なソフトウェアの計画ではありません。スプレッドシートの動作を明確にするためのプランです。Excel 領域での意味、範囲の役割、数式、書式、入力規則、保持する範囲、アサーションのゲートを明示します。

複雑な SaC ワークブック動作が関わる場合、`assertions.ts` の作成や Migration Packs の編集より前に、ワークスペースのプランを必ず作成または更新してください。

このスキルが該当する場合は、成功基準を最初に作成します。次にプラン、3 番目にアサーション、4 番目に移行ソースを作成します。

ルール

実行する前に、ソース内でワークブックの動作を決定します。

digraph writing_univer_plans {
    "SaC workbook task received" [shape=doublecircle];
    "Write success criteria checklist" [shape=box];
    "Read workbook evidence" [shape=box];
    "Classify range roles" [shape=box];
    "Resolve workbook behavior decisions" [shape=box];
    "Decompose Migration Packs" [shape=box];
    "Define assertion gates" [shape=box];
    "Write plan file" [shape=box];
    "Plan self-review" [shape=box];
    "Ready for executing-univer-plans" [shape=doublecircle];

    "SaC workbook task received" -> "Write success criteria checklist";
    "Write success criteria checklist" -> "Read workbook evidence";
    "Read workbook evidence" -> "Classify range roles";
    "Classify range roles" -> "Resolve workbook behavior decisions";
    "Resolve workbook behavior decisions" -> "Decompose Migration Packs";
    "Decompose Migration Packs" -> "Define assertion gates";
    "Define assertion gates" -> "Write plan file";
    "Write plan file" -> "Plan self-review";
    "Plan self-review" -> "Ready for executing-univer-plans";
}

成功基準を作成または更新する前に、プランを作成してはいけません。 プランを作成する前に、assertions.ts を作成してはいけません。 プランから導出したアサーションを作成する前に、Migration Packs を編集してはいけません。 すでに順序を誤って作業を進めた場合は、いったん停止し、現在のワークブックの証拠に基づいて不足している成功基準とプランを作成してから、プランに沿って作業をやり直してください。

成功基準を最初に作成する

ワークスペースのプランを作成する前に、以下を作成または更新します。

<package.univer>/success-criteria/<topic>.md

このファイルはプランではなく、短いチェックリストです。ワークブックについて詳しく検討し始める前に、ユーザーの依頼を合格条件に置き換えます。

次の形式を使用します。

# <Feature Name> Success Criteria

**Task:** <one-sentence restatement of the user task>
**Source:** <workbook/package, user prompt, files, or commands that define the task>

## Success Checklist

- [ ] <user-visible outcome>
- [ ] <preservation or negative constraint>
- [ ] <required deliverable or output>
- [ ] <validation signal>

## Explicit Non-Goals

- [ ] <out-of-scope behavior>

## Ambiguities To Resolve In Plan

- <question the plan must resolve with evidence, probes, or an explicit assumption>

成功基準には、目に見える成果、保持に関する制約、必要な成果物、検証シグナル、明示的な対象外事項、曖昧な点を記載できます。

• Migration Packs を含めてはいけません。
• assertions.ts の設計を含めてはいけません。
• TDD の手順を含めてはいけません。
• 修復の適用／検証戦略を含めてはいけません。
• ワークブックの証拠が必要な数式や範囲の対応付けに関する判断を含めてはいけません。代わりに、そうした点はプランの曖昧な事項として記載します。

必須ゲート

プランは、アサーションを先行させた実装を導ける状態になって初めて完成です。

• ワークブックの意味をチャット内だけのメモにしてはいけません。
• 「通常のスプレッドシートの動作」に関する直感だけで Migration Packs に着手してはいけません。
• 例、回答範囲、プレビューウィンドウを、理由を記録せずに目標の出力として扱ってはいけません。
• 曖昧な領域上の判断を、仮定であるにもかかわらず実証済みとして扱ってはいけません。
• 変更するパックにアサーションゲートがない状態で、実行担当に引き継いではいけません。
• 複雑な動作について、ワークブックの動作契約に関する選択肢がプランで特定されていない状態で、引き継いではいけません。

スコープの確認

パックのタスクを定義する前に、依頼が一貫したワークブックの動作を対象としているのか、それとも複数の独立したワークブック成果物を対象としているのかを確認します。

依頼に、個別に検証・提供できる独立したシート、ソースモデル、レポート群、ワークフローが含まれる場合は、プランを分けます。パックがワークブック上の共通の目標を共有し、検証コマンドも一貫している場合に限り、プランを1つにまとめます。

スコープが広すぎる場合は、いったん停止し、最初にどのワークブック成果物をプランニングするか尋ねてください。独立したアサーションゲートを隠してしまう巨大なプランを作成してはいけません。

ソースファイルの対応表

パックのタスクを定義する前に、プランに基づく実行で変更する予定のファイルを整理します。

• 成功基準：<package.univer>/success-criteria/<topic>.md
• プラン：<package.univer>/plans/<topic>.md
• アサーション：<package.univer>/migrations/<pack>/assertions.ts
• Migration Packs：<package.univer>/migrations/<pack>/
• フィクスチャまたは読み取り専用プローブ：証拠として使用するワークブックの正確なパス、シート、範囲、またはコマンド

各ファイルの役割を明記します。これにより、実行開始前にワークブックの意図、アサーション、移行ソース、証拠の境界を明確にします。

出力先

SaC ワークスペース内に、成功基準とプランのファイルを作成または更新します。

<package.univer>/success-criteria/<topic>.md
<package.univer>/plans/<topic>.md

既存のプロジェクト命名規則があれば、それに従ってください。今後のエージェントが、目標のチェックリストと検討内容・実行設計を区別できるよう、成功基準のファイルをプランの近くに置きます。

プラン文書のヘッダー

すべてのプランは、必ず次のヘッダーから始めてください。

# <Feature Name> Univer Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-univer-plans` to
> execute this plan pack-by-pack. Each non-trivial changed Migration Pack needs
> plan-derived assertions before implementation.

**Goal:** <one sentence describing the workbook-visible outcome>

Success Criteria: <package.univer>/success-criteria/<topic>.md

**Workbook Contract:** <2-3 sentences describing the spreadsheet behavior, not code structure>

**Execution Scope:** <Migration Packs, assertions, and verify command involved>

---

必須の計画形式

## Workbook Intent

- User-visible outcome:
- Explicit non-goals:

## Baseline Evidence

- Source already read:
- Readonly probes:
- Unknowns:

## Source File Map

- Success Criteria:
- Plan:
- Assertions:
- Migration Packs:
- Fixtures/probes:

## Range Roles

- Source data:
- Target output:
- Helper/control input:
- Lookup/reference:
- Example/demo:
- Existing output:
- Preserve-only:

## Workbook Behavior Contract

- Visible target/state:
- Source/input dependency:
- Shape/layout boundary:
- Ordering/grouping/mapping policy:
- Value/formula semantics:
- Formatting/presentation semantics:
- Interaction/validation/protection behavior:
- Preservation and negative constraints:
- Example/demo/answer-range handling:

## Contract Decision Evidence

| Decision | Chosen rule | Plausible wrong rule | Discriminating evidence | Evidence strength | Assertions/probes |
| --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |

## Migration Packs

1. `<pack-id>`: durable workbook intent
   - reads:
   - writes:
   - must preserve:
   - rollback/verify boundary:
   - assertion gate:

## TDD Gates

- Assertions to write or update first:
- Allowed bootstrap/probe:
- Completion verify command:

## Pack Tasks

### Task 1: `<pack-id>`

**Files:**
- Plan: `<package.univer>/plans/<topic>.md`
- Test: `<package.univer>/migrations/<pack>/assertions.ts`
- Migration: `<package.univer>/migrations/<pack>/`

- [ ] **Step 1: Write the failing assertion**
- [ ] **Step 2: Run verify and confirm expected failure**
- [ ] **Step 3: Implement the minimal Migration Pack change**
- [ ] **Step 4: Run verify and confirm pass**
- [ ] **Step 5: Commit or prepare handoff**

範囲の役割に関するルール

関連するすべての範囲の役割について、移行時に読み取り、書き込み、置き換えが許可されるのか、または保持する必要があるのかを明記してください。

範囲の役割には、ソースデータ、ターゲット出力、補助／制御入力、参照情報、例／デモ、既存の出力、保持専用領域があります。

ソースデータ、補助／制御入力、参照情報、例／デモ、既存の出力、保持専用の範囲は、ユーザーが明示的に変更を指示しない限り、ターゲット出力ではありません。例／デモの範囲を使って数式、レイアウト、または動作を推定する場合は、その推論を計画に記録し、実際のターゲット出力と例を区別するアサーションゲートを追加してください。

回答範囲と出力範囲は、制約と根拠を示すウィンドウです。左上のセルが出力の開始位置であることも、その範囲に契約全体が含まれていることも証明しません。

ワークブック動作契約に関するルール

複雑なワークブックの動作については、移行元を編集する前に、該当するワークブック動作契約のフィールドを埋めてください。この契約により、ワークブック上で曖昧な動作を、アサーションで検証できる明示的な計画上の選択肢に落とし込みます。

出力が中心となる変換では、形状、マッピング、順序、グループ化、切り捨て、値／数式の意味を記録してください。書式、入力規則、保護、グラフ、コメント、レイアウト、またはシート構造を変更する場合は、表示状態、表示または操作上の意味、保持ルール、変更してはならない制約を記録してください。

契約上の判断に関する証拠ルール

リスクの高い、または自明でないブックの動作に関する判断はすべて、移行元を編集する前に証拠を記録してください。

リスクの高い判断には、並べ替えの優先順位、グループ化と切り捨ての順序、ソースからターゲットへのマッピング、符号から列へのマッピング、単数形・複数形のラベル表記、空白・ゼロ・エラーの扱い、日付範囲の境界を含むかどうか、不正な色の扱い、大文字・小文字や空白の保持、ヘッダーまたはセクション境界の扱い、数式と静的値のどちらを使うか、指示を複数の意味に合理的に解釈できる動作が含まれます。

ブック上に表示される値を正確に保持すること自体が、動作に関する判断です。テキスト、空白、句読点、識別子、日付値、ブール値、数値／テキストの型、空白セル、ゼロ、エラーのプレースホルダーが表示される場合、計画には、それらを正確に保持するのか、意図的に変換するのかを明記してください。正規化した形のほうがすっきりしている、または慣例的に見えるという理由だけで、値を正規化してはいけません。

• 判断がドメインに関する直感、曖昧な表現、部分的なプレビュー情報、未確認のサンプル／参照パターンに依存する場合は、Unknowns: none と記述しないでください。
• 複数の解釈が妥当な場合は、採用しなかった解釈と、それらを退けた理由を列挙してください。
• 選択したルールがブック上に表示される証拠に基づく場合は、参照元の範囲またはセルを明記してください。
• 選択したルールが指示の文言だけに基づく場合は、判断の決め手となった句を計画に引用してください。
• 決定的な証拠がない場合は、その判断を仮定として明記し、最終的なターゲット／出力の文言に最も合致するルールを選んでください。
• リスクの高い判断にはそれぞれ、反対の解釈を採用した場合に失敗するアサーションまたは読み取り専用の検証手順を少なくとも1つ設けてください。
• ソース側の符号や業務上の慣例だけから、借方／貸方、入／出、正／負、その他同様の意味ラベルを推測してはいけません。マッピングは、ターゲットのラベル、例、指示の文言、または明示された仮定に結び付けてください。
• ヘッダー、カテゴリ、ステータス、部門、名前を書き込む際は、ブック上に表示されるラベルのテキストを保持してください。指示で書き込むラベルの名称変更、単数形化、複数形化、整理、書式変更が明示されている場合を除き、ラベルの正規化は照合にのみ使用してください。
• 既存のターゲット値や回答範囲の値は証拠であり、確定事項ではありません。タスクでその範囲の計算、入力、修復、置換、形状変更、転置、統合、数式入力が求められる場合は、指示とブック上の証拠によって最終値として意図されていることが確認できるまで、既存値はサンプル、古い状態、または部分的な出力である可能性があるものとして扱ってください。
• 既存のターゲット値が、指示から導かれるルールと矛盾する場合は、解釈を両方とも「契約上の判断に関する証拠」に記録し、識別力のある指示の文言と確認済みのソース／ターゲットの証拠に基づいて選択してください。
• 空白セル、ゼロ、#N/A、n/a、空白文字、NBSPは、それぞれ異なる出力として扱ってください。計画には、どの出力が意図されているかを記載し、関連する場合は、少なくとも1つの空白／エラー／ゼロの境界ケースについて証拠を示してください。
• 日付範囲または期間のロジックでは、境界を含むか除外するかを記録し、最初に計算される行、境界の前後の行、中間の行1行、最後の行を検証してください。
• ブックのスタイルでは、不正な色や省略形の色を、適用前に有効な#RRGGBBまたは安全なrgb(r, g, b)に正規化してください。APIでその形式が明示的にサポートされている場合を除き、不正な16進数カラーや名前付きカラーをそのままスタイルAPIに渡してはいけません。

証拠の十分性に関するルール

リスクの高い判断には、単に矛盾しないだけの証拠ではなく、解釈を識別できる証拠が必要です。

証拠によって、少なくとも1つの妥当な解釈が可能性の低いものになる場合に限り、その証拠は識別力があるといえます。選択したルールにも却下したルールにも当てはまる証拠は、矛盾しない証拠ではありますが、証明にはなりません。

観測されたワークブックの事実と意味上のラベルは分けて扱います。ソース値によって残高が変化することは、ソース側の符号の挙動を証明できますが、それだけではどのターゲットラベルにその符号を割り当てるべきかは証明できません。セクションの境界によってデータの形状が変化する位置は証明できますが、それだけではヘッダーをコピーするのか、スキップするのか、書き換えるのかは証明できません。

ドメインに関する直感、隣接行の計算、ソース側のパターン、一般的なビジネス上の意味は、ワークブックに表示されるターゲットラベル、例、指示の文言、または既存の出力に直接結び付いていない限り、ターゲットへのマッピングを判断する決定的な証拠として扱わないでください。

Evidence strength フィールドを使用して、リスクの高い各判断を次のいずれかとして示します。

• explicit：指示または既存のワークブックに表示されるターゲット／例で直接指定されている
• inferred：ワークブックに表示される識別力のある証拠によって裏付けられている
• underdetermined assumption：他の妥当な解釈を排除する証拠がない

判断が未確定の仮定である場合：

• 対話型タスクでは、実行前にユーザーに確認します。
• 非対話型タスクでは、必要な場合に限り続行し、指示とターゲットのレイアウトに最も沿う最善のルールを選び、不確実性を計画と引き継ぎ資料に明記します。
• 仮定を、ワークブックで証明された証拠として提示しないでください。

パックの分解

ワークブックの持続的な目的に基づいて分割します。

• シートの作成または再構成
• データモデルの読み込みまたは正規化
• 数式ファミリーの追加
• レビュー用またはサマリーの出力の生成
• 表示または検証の動作の追加

個々のセル、個々の Facade 呼び出し、または付随的な実装手順に基づいて分割しないでください。パックは、明確なワークブック上の目的、妥当なロールバック境界、および独自のアサーションゲートを持つ場合、適切なサイズです。

パックタスクの構成

重要な Migration Pack には、実行者が推測なしで実行できるチェックボックス付きタスクが必要です。正確なファイルパス、正確なコマンド、期待される結果を記載してください。

### Task N: <pack-id> - <workbook intent>

**Files:**
- Plan: `<package.univer>/plans/<topic>.md`
- Test: `<package.univer>/migrations/<pack>/assertions.ts`
- Migration: `<package.univer>/migrations/<pack>/`

- [ ] **Step 1: Write the failing assertion**

Add or update the assertion that proves the current pack's workbook-visible behavior.

- [ ] **Step 2: Run verify and confirm expected failure**

Run: `univer sac verify <package.univer> --json`
Expected: FAIL for the intended workbook-visible reason, not setup or typo failure.

- [ ] **Step 3: Implement the minimal Migration Pack change**

Edit only `migrations/<pack>.ts` and any pack-local helper required by the current assertion.

- [ ] **Step 4: Run verify and confirm pass**

Run: `univer sac verify <package.univer> --json`
Expected: PASS with this pack's assertion checked in returned assertion evidence.

- [ ] **Step 5: Commit or prepare handoff**

Record the plan path, assertion evidence, migration file, and verify command.

「Task N と同様」と書かないでください。パックタスクは異なるエージェントが順不同で実行する場合があるため、詳細を繰り返してください。

プレースホルダー禁止

次の項目は計画の不備です。

• TBD、TODO、「後で実装する」、または必須セクションの空欄
• ワークブックに表示される動作を明示せずに「適切なアサーションを追加する」とすること
• 範囲や役割を明示せずに「既存のデータを保持する」とすること
• 別のパックに対して「上記と同じ」とすること
• 読み取り、書き込み、保持境界、またはアサーションゲートのない Migration Pack
• 証拠の強さを示していない判断項目
• チェックボックス付きの手順、正確なファイル、検証コマンド、失敗／成功の想定結果がないパックタスク

計画の自己レビュー

引き継ぎの前に、計画を次の項目に沿ってインラインでレビューします。

1. ワークブックの網羅性： ユーザーに見える各要件が、契約のフィールドとパックに対応している。
2. 範囲の役割の網羅性： 関連するすべてのソース、ターゲット、ヘルパー、例、既存の出力、保持のみの範囲に、読み取り／書き込み／保持のルールがある。
3. 判断の網羅性： Excel ドメインに関するリスクの高い判断すべてに、証拠の強さと、識別力のあるアサーションまたは調査手順がある。
4. 実行の網羅性： 変更のある重要なパックすべてに、計画に基づくアサーションゲートがある。
5. パックタスクの網羅性： 重要なパックすべてに、正確なファイル、コマンド、期待される結果を含む、実行可能なチェックボックス付き手順がある。
6. プレースホルダーの確認： プレースホルダー、曖昧なアサーション、詳細が指定されていない保持に関する主張を削除する。

危険信号

次のような考えが浮かんだら、作業を止めて計画を強化してください。

考え	実情
「ワークブックの意図は明らかだ。」	スプレッドシートの動作には、ドメインルールが隠れています。契約を明文化してください。
「先にアサーションを書いて、後で文書化しよう。」	アサーションは記憶ではなく、計画に基づいて作成する必要があります。
「この回答範囲が出力開始位置の根拠になる。」	回答範囲は根拠を示す範囲であり、契約全体ではありません。
「移行ですべてを維持できる。」	維持するには、範囲の役割と否定的な確認を明示する必要があります。
「ソースの符号を見れば、ターゲットのラベルがわかる。」	マッピングには、ターゲットラベル、例、文言、または明示された前提が必要です。

実行の引き継ぎ

計画の自己レビューに合格したら、executing-univer-plans に引き継ぎます。引き継ぎでは、次の項目を明記してください。

• 計画のパス
• パックの順序
• 最初に作成するアサーションゲート
• 検証コマンド
• 未解決の前提があれば、その内容