update-progress

name	update-progress
description	Record task completion, update streak, detect recurring mistakes, and write updated state to storage/progress.json and storage/daily_state.json.

update-progress

When to Use

Invoke this skill when the learner runs /jp-complete. It is the single write-path for all progress data. No other skill should write to storage/progress.json directly.

Inputs

Parameter	Type	Required	Description
user_id	string	yes	References users.id
task_id	string	yes	The task being marked complete (must exist in today's daily_state.assigned_tasks)
completion	boolean	yes	True if completed, false if skipped
self_rating	integer	yes	Learner's self-assessment: 1 (very hard) to 5 (very easy)
note	string	no	Optional free-text note from the learner
mistakes_observed	string[]	no	Error patterns noted during the task (from review-answer or learner input)

Outputs

Field	Type	Description
updated_progress	object	The full updated progress record
streak_value	integer	New streak days count
mastery_changes	object[]	Items promoted to mastered or demoted (see below)
recurring_mistake_alerts	object[]	Mistakes that have now hit the promotion threshold
next_recommendation	string	Suggested focus for the next session

Mastery Change Object

Field	Type	Description
item_id	string	Vocab or grammar item ID
item_type	string	"vocab" or "grammar"
change	string	"promoted_to_mastered" or "added_to_active"

Logic

Completion Counters

When completion: true:

• Increment completed_{type}_count based on task type (vocab, grammar, listening, shadowing, speaking).
• Add task_id to daily_state.completed_tasks[].

Streak Update

• Compare today's date to the date of the last completed task in progress.last_updated_at.
• If last completion was yesterday: streak_days += 1.
• If last completion was today (multiple tasks in one session): no change.
• If last completion was 2+ days ago: streak_days = 1 (streak broken, reset).
• Sync streak to users.streak_days as well.

Self-Rating → Mastery Promotion

Track per-item ratings across sessions in daily state:

• If an item receives self_rating >= 4 for 3 consecutive sessions: move from active_vocab_ids → mastered_vocab_ids (or grammar equivalent).
• If a mastered item later returns with self_rating <= 2: move back to active (demotion).

Recurring Mistake Detection (per spec §11.9)

When mistakes_observed is non-empty:

1. For each observed mistake pattern, search recurring_mistakes[] for an existing entry.
2. If found: increment occurrence_count.
3. If not found: create a new entry with occurrence_count: 1.
4. If occurrence_count reaches 2–3: set promoted_to_drill: true and add the related item ID to active_vocab_ids or active_grammar_ids for targeted review.
5. Include this in recurring_mistake_alerts output.

Carry-Forward Recommendation

After processing, generate carry_forward_recommendation for daily_state:

• If recurring mistakes were promoted: recommend drilling those patterns tomorrow.
• If self_rating was low (1–2) for the task: recommend repeating the same content.
• Otherwise: recommend the next item in sequence.

Write Operations

1. Read storage/progress.json, update the matching user's record, write back.
2. Read storage/daily_state.json, update or create today's session record, write back.

Example

Input:

{
  "user_id": "user_001",
  "task_id": "vocab_003_20260413",
  "completion": true,
  "self_rating": 2,
  "note": "Keep confusing すみません and ごめんなさい",
  "mistakes_observed": ["すみません vs ごめんなさい usage confusion"]
}

Output:

{
  "streak_value": 6,
  "mastery_changes": [],
  "recurring_mistake_alerts": [
    { "pattern": "すみません vs ごめんなさい usage confusion", "occurrence_count": 2, "promoted_to_drill": true }
  ],
  "next_recommendation": "Repeat vocab_003 tomorrow with production drill. Promoted 'すみません vs ごめんなさい' to active review."
}