Safely Deleting Dictionary Entries

Use this skill when you need to remove an entry from the dictionary. This ensures all indexes and cross-references are properly updated.

When to Delete an Entry

Valid reasons for deletion:

• Duplicate entry - Another entry exists for the same word (see resolve-duplicates skill)
• Erroneous entry - Entry contains fundamental errors that cannot be corrected
• Out of scope - Word doesn't belong in a learner's dictionary (too obscure, offensive, etc.)
• Merged into another entry - Content has been incorporated elsewhere

Do NOT delete entries just because they need improvement - use revise-entries skill instead.

Pre-Deletion Checklist

Before deleting any entry:

1. [ ] Confirm deletion is necessary - Can the entry be fixed instead?
2. [ ] Note the entry details for later reference:

- Entry ID (e.g., 00123taberu) - Reading (e.g., たべる) - Headword (e.g., {食べる|たべる}) - File path (e.g., entries/00000/00123taberu.json)

1. [ ] Check for cross-references to this entry from other entries
2. [ ] Decide if word should return to candidates (if it still needs an entry later)

Step 1: Find Cross-References to This Entry

Search for other entries that reference the entry you're deleting:

# Search by reading
grep -r '"reading": "たべる"' entries/ --include="*.json" -l

# Search by headword text (without furigana)
grep -r '食べる' entries/ --include="*.json" -l

# Search in cross_references arrays specifically
grep -r '"cross_references"' entries/ -A 20 | grep -B 5 '"reading": "たべる"'

Step 2: Update Cross-References in Other Entries

For each entry that references the one being deleted:

Option A: Remove the cross-reference

If the reference is no longer relevant:

// Before
"cross_references": [
  {"type": "related", "reading": "たべる", "headword": "{食べる|たべる}", "label": "to eat"}
]

// After (remove the reference)
"cross_references": []

Option B: Update to point to replacement entry

If a better entry exists (e.g., after merging duplicates):

// Update the reading/headword/label to match the kept entry
"cross_references": [
  {"type": "related", "reading": "たべる", "headword": "{食べる|たべる}", "label": "to eat"}
]

Option C: Keep as informational reference

If the cross-reference is still useful even without a target entry, you may keep it. The reference will simply not link to anything.

Step 3: Delete the Entry File

# Remove the entry file
rm entries/{range}/{entry_id}.json

# Example:
rm entries/04500/04567_taberu.json

Verify deletion:

ls entries/04500/04567_taberu.json  # Should return "No such file"

Step 4: Update Indexes

Run the index update script:

python3 build/update_indexes.py

This script automatically:

• Removes the entry from entries_index.json
• Updates entry counts
• Syncs with candidate_words.json

Step 5: Optionally Re-add to Candidates

If the word should eventually have an entry (just not this flawed one):

1. Check if update_indexes.py already re-added it to candidates
2. If not, manually add to candidate_words.json:

{
  "reading": "たべる",
  "headword": "食べる",
  "english": "to eat",
  "notes": "Previous entry deleted due to [reason]. Needs new entry."
}

Step 6: Rebuild the Flat File

make index   # indexes + kanji JSON; the site builds in CI after merge

This updates the website data. Without this step, the deleted entry may still appear on the live site.

Step 7: Validate

python3 build/validate.py

Confirm:

• No errors about missing files
• No broken cross-references (if you updated them)
• Entry count matches expected total

Complete Workflow Example

# 1. Note the entry to delete
# ID: 04567_taberu, Reading: たべる, Path: entries/04500/04567_taberu.json

# 2. Find cross-references
grep -r '"reading": "たべる"' entries/ --include="*.json" -l

# 3. Update any cross-references found (edit those files)

# 4. Delete the entry
rm entries/04500/04567_taberu.json

# 5. Update indexes
python3 build/update_indexes.py

# 6. Rebuild flat file
make index   # indexes + kanji JSON; the site builds in CI after merge

# 7. Validate
python3 build/validate.py

# 8. Commit changes
git add entries/ docs/ *.json PROJECT_STATUS.md
git commit -m "Remove duplicate/erroneous entry: 04567_taberu"
git push

Cross-Reference Format Reference

When updating cross-references, use this format:

{
  "type": "related",       // or: pair, antonym, keigo, synonym, contrast, see_also
  "reading": "よむ",        // hiragana reading
  "headword": "{読む|よむ}", // with furigana (for disambiguation)
  "label": "to read"       // optional human-readable label
}

Cross-reference types:

• pair - Transitive/intransitive verb pairs
• antonym - Opposite meanings
• keigo - Honorific/humble equivalents
• synonym - Similar meanings
• contrast - Often confused words
• related - Semantically related
• see_also - General reference

Troubleshooting

"Entry still appears on website"

• Did you run make index?
• Clear browser cache or check docs/flat_dictionary.json

"Validation shows broken cross-reference"

• Search for the deleted entry's reading in all files
• Update or remove stale references

"Index counts don't match"

• Run update_indexes.py again
• Check for orphaned files in entries directory

Safety Notes

1. Always back up first if deleting multiple entries:

``bash git stash # or commit current state first ``

1. Delete one at a time when learning - run validation after each

1. Never delete without checking cross-references - broken links degrade dictionary quality

1. Document deletions in commit messages for future reference