Transcribe

---
name: transcribe
description: Read ツールで開けない表計算ファイル (xlsx, ods, csv) を読み、セル結合された業務文書を Markdown へ変換し、セルの取りこぼしが無いことを検証する。
when_to_use: .xlsx / .xls / .ods ファイルのパスが渡された, Excel の中身を読む, スプレッドシートの内容を調べる, 設計書を読む, read an Excel file, spreadsheet contents, xlsx
allowed-tools: Bash(node:*) Read
---

# /transcribe - スプレッドシート読み取り

Read ツールは xlsx を開けない。このリポジトリに入れた hucre をライブラリとして使い、シートを読む。

## 手順

1. 中身の形を見る。

```bash
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts list <xlsx>
```

シート一覧と充填率が出る。充填率は値が入っているセルの割合で、ここで次の分岐が決まる。

2. 充填率で読み方を決める。

| 充填率   | 状態                                           | 読み方                                                 |
| -------- | ---------------------------------------------- | ------------------------------------------------------ |
| 20% 未満 | セル結合とレイアウト目的の空セルが大半を占める | extract で整形してから読む                             |
| 20% 以上 | 1 行 1 レコードに近い                          | `--sheet` でシートを絞り `generic` のまま extract する |

3. 整形する。出力先はリポジトリの外か、ユーザーが指定した場所にする。

```bash
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts extract <xlsx> --out <dir> [--profile <name>] [--sheet <n|name>]
```

4. 欠落が無いか確かめる。この確認を飛ばさない。書式判定を誤るとエラーを出さずにセルが消えるため、消えたかどうかは照合でしか分からない。

```bash
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts verify <xlsx> <dir>
```

`OK: every cell of N sheets survived into the output.` が出たら完了。欠落があればシート名と欠落セルの先頭 40 字を返すので、プロファイルの判定を直してから再実行する。

## プロファイル

書式固有の判定はプロファイルが持つ。`scripts/convert.ts` の `profiles` に定義がある。

未知の書式にはまず `generic` を使う。表として整形したい場合だけプロファイルを足す。プロファイルが持つ判定は 5 つで、null にした判定は行わない。

| プロファイル     | 対象                                            | 挙動                                                       |
| ---------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| `generic` (既定) | 書式が不明なファイル                            | 表として解釈しない。セル結合を畳むだけで、情報は落ちない   |
| `ja-api-spec`    | 項番とパラメータ名の列を持つ日本語の API 設計書 | 見出し、パラメータ表、2 段ヘッダ、コードブロックを復元する |

| キー                 | 判定                                                             |
| -------------------- | ---------------------------------------------------------------- |
| `docHeaderFirstCell` | この文字列が A1 にあるとき、先頭 3 行を文書情報として畳む        |
| `heading`            | この正規表現に一致する 1〜2 セルの行を見出しにする               |
| `tableHeadWords`     | この正規表現に一致し、かつ 3 セル以上ある行を表ヘッダにする      |
| `nestColumnLabel`    | この語を含む列で、列内のセル位置を階層の深さとして復元する       |
| `code`               | この正規表現に一致する単独セルの行を連結してコードブロックにする |

## 判断の基準

単発で内容を知りたいだけなら、`extract --sheet <n|name> --out` の出力先を一時ディレクトリにして読み、リポジトリには残さない。Markdown ファイルとして残すのは、横断 grep を繰り返すとき、人が読むとき、git で差分を追うときに限る。

整形の効果は充填率で決まる。充填率が低いほど空セルがトークンを食い、整形で落ちる分が大きくなる。

## 依存

`hucre` をリポジトリのルートに入れてある (`bun add hucre`)。未導入の環境ではスクリプトが導入手順を出して終了する。node は script の親を辿って `node_modules` を探すので、プラグイン導入先なら `~/.claude` で入れれば解決する。

Python へ移さないのは、`hucre` が xlsx、ods、csv を 1 パッケージで持つため。openpyxl は ods を読まず odfpy が別に要り、このリポジトリの Python は全て標準ライブラリのみで依存マニフェストを持たない。標準ライブラリで書き直すと、日付セルが素の数値で `styles.xml` の `numFmtId` を辿らないと判別できない部分を自前で抱える。

CLI (`hucre convert`) は使わない。理由は 3 つある。

| 理由                   | 根拠                                                                          |
| ---------------------- | ----------------------------------------------------------------------------- |
| セル結合を落とす       | CLI の説明文が `cell values only — styles, merges, formulas` と明記している   |
| 先頭シート以外を落とす | 3 シートのファイルで `Read 3 sheet(s)` と出しながら 1 シートしか書き出さない  |
| Markdown を出せない    | `convert <INPUT> <OUTPUT>` の形式変換のみで、シートを選ぶオプションも持たない |