fluent-db-updater

DB Updater

Overview

Every practice skill ends with a DB update. Instead of hand-editing 6 JSON files (error-prone, racy, easy to desync), pipe one JSON report to update-db.py. The script runs pre-write backups, validates the payload, applies all changes atomically via .tmp + fsync + rename, and rebuilds the spaced-repetition queue.

When to Use

Load this skill whenever the tutor:

• Finishes a practice session and needs to persist results.
• Needs to add new vocabulary to the spaced-repetition queue.
• Needs to record new errors, review results, or mastery changes.
• Needs to bump total_sessions, current_streak_days, or total_study_minutes.

Skip this skill for read-only operations (use the fluent-progress skill or read-db.py directly) and during session setup (use fluent-setup skill instead — update-db.py is for session deltas, not bootstrap).

Instructions

1. Call the script

Run from the repo root:

python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks/update-db.py" <<'EOF'
{ ...payload... }
EOF

Exit codes: 0 success, 1 validation error, 2 I/O error.

2. Fill the payload

Required fields

• session_id — string, convention session-NNN. Use computed.next_session_id from read-db.py.
• date — YYYY-MM-DD.

Optional fields — omit to skip. Full canonical example (copy-paste this and fill in):

${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/references/db-updater-payload.example.json

Key blocks the example covers: skill_scores, errors[], new_vocabulary[], review_results[], topics_covered, breakthroughs, focus_next_session, session_notes, achievements_earned, milestones.

3. Field notes

• errors[] — one entry per distinct mistake this session. Collapse duplicates (same pattern_id) before sending; frequency is bumped by the script.
• new_vocabulary[] — items the learner met for the first time. Fill every field; incomplete entries yield incomplete spaced-repetition records.
• review_results[] — items already in the queue that were reviewed. The script runs SM-2 on each. See the fluent-sm2-calculator skill. Mapping: quality = floor(score / 2).
• skill_scores[].correct counts correct exercises, not a percentage. Accuracy is derived.
• confidence in learner-profile.skills is 0–100 integer; accuracy in progress-db is 0.0–1.0 float. The script handles the conversion.
• milestones[] — each entry is a bare string OR an object { "milestone": <required non-empty string>, "date": <optional YYYY-MM-DD, defaults to the session date> }. Don't set a nested session_id; the script stamps the authoritative top-level one. A malformed entry (neither string nor object, or an object missing/empty milestone) exits 1 with no files written. Each milestone becomes both a session-log.milestones[] record and a learner-profile.achievements[] entry.