| name | polish-entries |
| description | Systematic review and improvement of dictionary entries. Use when starting a polishing session to review entries for accuracy, completeness, and consistency. |
Dictionary Polishing
This skill describes the polishing system used by je-dict-1. The default ongoing task is comprehensive polish (prompts/comprehensive_polish.md), which walks through entries one at a time and applies a tiered quality checklist. Several targeted polish prompts also exist for special-purpose sweeps.
When a polishing session starts, read this skill, then read the specific prompt file for the task being run.
Comprehensive polish (default)
prompts/comprehensive_polish.md is the standing improvement task. Each session:
- Reads
polishing/tasks/comprehensive/progress.txt for the next entry ID.
- Processes 20–30 entries (target ~70% context use), applying a tiered checklist (tier 1 required-for-every-entry, tier 2 should-do judgment items, tier 3 nice-to-have polish).
- For each entry, ensures full inline link coverage on every Japanese word in both examples AND notes (tier 1 requirement). Words without entries get
noentry markers and are added to candidates.
- For each entry, checks back-link symmetry on direct neighbors — adds a back-link on the linked entry where appropriate, but does not recurse.
- Logs words found in examples/notes that lack entries to
candidate_words.json with "seen in entry XXXXX" notes (these become highest-priority candidates).
- Logs systemic patterns and longer-horizon ideas to
polishing/observations.md.
- Writes a session log to
polishing/sessions/comprehensive_{YYYY-MM-DD}_{NNN}.md.
- Runs
make build, commits, and creates a PR following the end-of-session workflow in CLAUDE.md.
The comprehensive task subsumes the targeted polish prompts listed below. Use it unless you have a specific reason to run a focused sweep.
Targeted polish tasks (special-purpose)
| Prompt file | Focus | Progress file |
|---|
prompts/polish_furigana_completeness.md | Add missing furigana | polishing/tasks/furigana-completeness/progress.txt |
prompts/polish_furigana_correctness.md | Verify reading correctness | polishing/tasks/furigana-correctness/progress.txt |
prompts/polish_example_sentences.md | Example count, tier compliance, length progression | polishing/tasks/example-sentences/progress.txt |
prompts/polish_add_inline_links.md | Add ⟦…⟧ cross-reference links | polishing/tasks/inline-links/progress.txt |
prompts/polish_semantic_labels.md | Verify semantic tags | polishing/tasks/semantic-labels/progress.txt |
prompts/polish_verb_transitivity.md | Add transitivity tags and pair links | polishing/tasks/verb-transitivity/progress.txt |
prompts/polish_aspect_notes.md | Document non-obvious ている behavior | polishing/tasks/aspect-notes/progress.txt |
prompts/expand-short-notes.md | Expand inadequate notes | polishing/tasks/expand-short-notes/progress.txt |
prompts/add_cross-references.md | Add prominent_see_also and cross_references | polishing/tasks/cross-references/ (varies) |
prompts/polish_cross_model_review.md | Apply multi-model review corrections | polishing/tasks/cross-model-review/progress.txt |
Each targeted prompt advances its own progress pointer. They remain available for occasional focused work but are not the default workflow.
Progress files
Per-task progress is a minimal text file:
next: 12345
A last_session: line may also be present as a hint for resumption. The format is the same across all tasks (comprehensive and targeted).
Session logs
After every session, write a markdown log:
polishing/sessions/{task}_{YYYY-MM-DD}_{NNN}.md
Where {task} matches the task type (comprehensive, furigana-completeness, etc.) and NNN is the next zero-padded sequence number for that task. The log records what was processed, what changed, candidates added, observations logged, and the next entry to process.
Quality standards
When polishing entries, the same quality standards used during creation apply:
- All kanji have furigana in all fields including notes (
{漢字|かんじ})
- Readings are hiragana-only (long-vowel
ー allowed)
- Romaji concatenates the full reading (
ketteisuru, not kettei_suru)
- POS tags use the hyphenated names (
verb-suru, adjective-na, etc.)
- All explanatory prose is in English; Japanese only appears in headwords, examples, collocations, and patterns
- Examples have valid
sense_numbers
- See
entry-guidelines skill for the full list, plus the type-specific skills (verb-entry, adjective-entry, particle-entry, other-entries)
Per-entry timestamps (CRITICAL)
When you modify an entry, run python3 build/get_timestamp.py immediately before saving and write that exact timestamp to the modified field. One entry, one timestamp — do not reuse a timestamp across multiple entries.
Cross-reference targets that don't exist
If a cross-reference points at an entry that doesn't exist yet, add the target word to candidates:
python3 build/manage_candidates.py add "headword" "reading" "brief gloss"
The script checks for duplicates and refuses if the word already exists.
Polishing priority files (optional)
build/prioritize_polishing.py produces priority files in polishing/priority/ (currently cross_refs.txt, examples.txt, furigana.txt, notes.txt) that order entries worst-first for the targeted polish tasks. The targeted polish prompts use these when present and fall back to sequential ID order. Comprehensive polish does not use priority files — it walks sequentially through the dictionary so coverage advances predictably.
Long-term tracking
The comprehensive polish workflow logs higher-level observations to polishing/observations.md using tag conventions ([pattern], [wiki], [article], [tooling], [skill], [entry]). The daily wiki-maintenance session (planning/maintain-knowledge-base.md) harvests this file.
Parallel execution
The targeted polish prompts support parallel execution when given an explicit ID range — see the "Parallel Execution Mode" section in any of the polish_* prompts and the "Parallel Execution" section in CLAUDE.md. Comprehensive polish currently runs single-agent; entry-level claim coordination for parallel comprehensive polish is planned but not yet implemented.
Important reminders
- One timestamp per entry — run
get_timestamp.py before saving each entry.
- Don't recurse on neighbors in comprehensive polish — direct neighbors only, no further hops.
- Don't run
make build mid-session for parallel-mode runs; the coordinator handles it.
- Always write a session log before stopping — even short sessions.
- End-of-session workflow (build, commit including
docs/, push, PR, CI watch, squash-merge, branch cleanup) is documented in CLAUDE.md. Follow it exactly.
