translate-book

Files (200)

• icon.png · .claude-plugin/
• fast-finder.md · .claude/agents/
• old-man.md · .claude/agents/
• question-monster.md · .claude/agents/
• referee.md · .claude/agents/
• translator.md · .claude/agents/
• release.md · .claude/commands/
• .gitattributes
• ci.yml · .github/workflows/
• .gitignore
• AGENTS.md
• CLAUDE.md
• INSTALL.md
• KNOWHOW.md
• KNOWLEDGE.md
• LICENSE
• PUBLISHING.md
• README.md
• REFEREE.md
• SKILL.md
• 01-title.png · assets/demo/
• 02-math.png · assets/demo/
• 03-table.png · assets/demo/
• README.md · assets/demo/
• shapes.json · corpus/
• sample_de.png · docs/samples/
• sample_en.png · docs/samples/
• sample_es.png · docs/samples/
• sample_fr.png · docs/samples/
• sample_ja.png · docs/samples/
• sample_ko.png · docs/samples/
• sample_zh.png · docs/samples/
• finish_fork.py
• runs.json · referee/
• advisors.py · scripts/
• algorithm_float.py · scripts/
• arxiv_backend.py · scripts/
• backends.py · scripts/
• build_common.py · scripts/
• calibre_html_publish.py · scripts/
• chromium_pdf.py · scripts/
• chunk_context.py · scripts/
• convert.py · scripts/
• corpus_census.py · scripts/
• doctor.py · scripts/
• drawn_figures.py · scripts/
• equation_fit.py · scripts/
• glossary.py · scripts/
• halign_tables.py · scripts/
• install_advisors.py · scripts/
• kb.py · scripts/
• latex_cleanup.py · scripts/
• latex_rows.py · scripts/
• latex_tables.py · scripts/
• layout.py · scripts/
• manifest.py · scripts/
• math_guard.py · scripts/
• math_tabulars.py · scripts/
• merge_and_build.py · scripts/
• merge_meta.py · scripts/
• …and 140 more

SKILL.md (first lines)

# Book Translation Skill

You are a book translation assistant. You translate entire books from one language to another by orchestrating a multi-step pipeline.

## Before you start

`KNOWLEDGE.md` in this directory is the findings log: things that went wrong
in real runs, why, and how they were proved. **Read it the moment output looks
wrong**: its symptom index maps what you are seeing to the cause, and its
diagnostic chain shows which intermediate artifact to check first. This
pipeline's characteristic failure is the *silent drop*: content that is simply
not there, with no error and no garbage on the page.

`KNOWHOW.md` is its counterpart, and the split is worth knowing before you
start: KNOWLEDGE holds facts about how the tools behave, KNOWHOW holds how to
go about the work. *Why did this break?* against *how should I proceed?* Its
"Which document, for which task" table says what to read before what, and its
task index covers the steps that are easy to do the expensive way.

You are expected to add to both, see Step 9.

**Do not read either file whole.** They passed 110 KB across 130-odd entries
and they only grow; reading both to answer one question costs more than the
answer. Look things up instead:

```bash
python {baseDir}/scripts/kb.py find "<symptom, file, function or LaTeX command>"
python {baseDir}/scripts/kb.py list          # id + title for everything, to browse
python {baseDir}/scripts/kb.py show K102 H26 # named entries, in full
```

`kb.py` parses both files fresh on every call, so it is never out of date with
them, and there is no index file to drift. When the answer needs judgment
rather than a match, which of six candidates actually bears on your case,
call `fast-finder` (below). When nothing matches, that is a real answer: this
is new, and you will be writing an entry rather than finding one.

## Four advisors, and when to call them

KNOWLEDGE and KNOWHOW record what has already happened. These two do not: they
work on the decision in front of you, and each exists because of a failure the
logs could not have prevented.

Both are cheap, one read-only sub-agent, one question, one answer. Neither
writes code, and neither has a veto. **If an advisor cannot name something
specific, proceed with what you had.** An advisor that only says "think more
broadly" or "try harder" has told you nothing, and stalling on it is worse than
never asking.

### `old-man`: call it BEFORE you conclude something is absent

The failure it is for: a check is written for the shape the corpus has shown,
meets a paper shaped differently, and reports *absent* rather than *unfamiliar*.
This happened four times in one afternoon on the fourth paper, a reference
beginning `images/` was assumed to be one we had already extracted, the first
`\end{tabular}` was assumed to end the table, a `\caption` inside a `%` comment
was counted as a caption, and a caption written `\captionof` was not counted at
all. Every one is the same mistake: the pattern was read as the definition.

**Trigger it when you are about to:**
- conclude the source does not contain something, because a search found none;
- write a pattern whose match decides that something is present or absent;
- generalise a rule from the papers you have already translated.

**Ask it:** what you are about to conclude, the pattern you used, and the file
you searched. **Expect back:** named alternative spellings and layouts that
would defeat that pattern (`\captionof` beside `\caption`, `wrapfigure`
beside `figure`, an inlined `.bbl` beside `\bibitem`) each one specific enough
to grep for. Then grep for them. The advice is worth the call only if a search
it named finds something; note in your report when it does.

### `question-monster`: call it AFTER you conclude something is impossible

The failure it is for: conceding on the first attempt. Seven of DeeR-VLA's
eight equations were refused over `\setlength`, a spacing directive with
nothing in it to read, and the eighth over `\sideset`: for which an exact
equivalent existed, `\sum\nolimits_{X}`, and the same equation already used it
further along. The concession was written before the alternative was looked
for, and only a reader who kept asking "really, no way at all?" turned it up.

**Trigger it when you are about to write** *unsupported*, *cannot be
expressed*, *no way to*, *has to be dropped*, or *we lose this* (in a report,
a commit message, or a comment).

**Ask it:** what you declared impossible, what you tried, and the exact error
or refusal. **Expect back:** concrete candidates to test, not encouragement.
It stops when the answer is genuinely no, and the test for that is K100: the
boundary is not where a command is unimplemented, it is where the supported
subset has no way to say the same thing. An unimplemented command with an
equivalent is a rewrite you have not done yet.

### `fast-finder`: call it INSTEAD of reading the two logs

The failure it is for: the logs are only useful if the right entry is found in
seconds, and at 130 entries that stopped being true by reading. It runs
`kb.py`, judges which of the matches actually bear on your question, and hands
them back **verbatim**: a status line saying an approach was already tried and
reverted is the whole value of an entry, and a summary loses it.

**Trigger it when you would otherwise open `KNOWLEDGE.md` or `KNOWHOW.md`,**
and whenever you are about to change a function and want to know what is
already known about it. `kb.py find` alone is enough for an exact symbol; the
agent earns its keep on the fuzzy ones.

It also keeps the logs findable: `kb.py check` catches an entry no index row
reaches (invisible, so writing it was wasted), and `kb.py stale` catches an
entry naming a function the repo no longer has. Run both after Step 9.

### `referee`: call it ONCE the whole run has been gated, not per chunk

The failure it is for: `verify_chunk` rejects a chunk and tells you nothing
about the run. A defect that fires once is an accident; the same defect on a
third of the chunks is the BRIEF, because every instance of a role read the
same prompt; the same defect in a third book is something nobody has fixed.
None of that is visible from inside a chunk.

```bash
python {baseDir}/scripts/referee.py tally  <temp_dir> --lang <lang>   # judge this run
python {baseDir}/scripts/referee.py record <temp_dir> --lang <lang>   # and remember it

From kcy4334-lgtm/translate-book-arxiv, MIT.