build-weekly-review

build-weekly-review

When to Use

Invoke this skill when the learner runs /jp-weekly. It reads from storage/progress.json and storage/reviews.json, and produces a weekly retrospective. During speaking+review weeks (17–24), this summary also feeds back into generate-daily-tasks to inform the next week's plan.

Inputs

Parameter	Type	Required	Description
user_id	string	yes	References users.id
weekly_task_history	object[]	yes	Array of daily_state records for the past 7 days (from storage/daily_state.json)
weak_points	string[]	yes	Aggregated weak_points[] from all daily sessions this week

Outputs

Field	Type	Description
summary	string	2–4 sentence narrative of the week's learning in Chinese
completion_rate	number	Percentage of assigned tasks completed (0.0–1.0)
average_self_rating	number	Mean self-rating across all completed tasks (1.0–5.0)
weak_areas	object[]	Patterns or skills that showed low ratings or repeated mistakes
strong_areas	object[]	Patterns or skills where performance was consistently high
next_week_focus	string	Specific recommended focus for the coming week
items_to_retire	string[]	Vocab/grammar IDs that are mastered and can be removed from rotation
items_to_add	string[]	New vocab/grammar IDs to introduce next week

Weak/Strong Area Object

Field	Type	Description
area	string	Skill area or specific pattern (e.g., "particle usage", "listening comprehension")
evidence	string	Brief summary of what data supports this classification
action	string	Recommended action: "repeat", "drill", "introduce_next_pattern", "celebrate"

Logic

Data Aggregation (per spec §11.6 compression)

1. Read all daily_state records for the past 7 days matching user_id.
2. Aggregate:
   • Total tasks assigned vs. completed → completion_rate
   • All self_ratings[] → average_self_rating
   • All weak_points[] → frequency map
   • All review records from storage/reviews.json for this week → mistake type frequency

Weak Area Detection

A pattern is classified as weak if:

• It appears in weak_points[] 2+ times across the week, OR
• The associated self_rating average is below 3.0, OR
• It appears in recurring_mistakes with occurrence_count >= 2

Strong Area Detection

A pattern is strong if:

• The associated self_rating average is 4.0 or above across 3+ sessions, OR
• The item was promoted to mastered this week

Next Week Focus

Combine signals:

• If completion_rate < 0.6: recommend reducing task count and slowing pace.
• If average_self_rating < 2.5: recommend repeating current content before advancing.
• If weak_areas contain grammar: recommend grammar+shadowing focus next week.
• If weak_areas contain listening: recommend adding one extra listening drill per day.
• If all ratings high (>= 4.0): recommend advancing to the next phase or level.

Summary Narrative

Write 2–4 sentences in Chinese covering:

• What the learner worked on this week
• One highlight (something that went well)
• One area to improve
• Encouragement

Example

Output:

{
  "summary": "這週你完成了5天的學習，重點練習了打招呼詞彙和聽力。すみません的用法已經進步很多！助詞「は」和「が」的區別還需要多練習，下週我們會專門加強這個。繼續保持，你的連續學習已經達到6天了！",
  "completion_rate": 0.8,
  "average_self_rating": 3.2,
  "weak_areas": [
    { "area": "は vs が particle usage", "evidence": "Appeared in weak_points 3 times; review mistake count: 2", "action": "drill" }
  ],
  "strong_areas": [
    { "area": "Greeting vocabulary", "evidence": "Average self-rating 4.5 across 4 sessions", "action": "celebrate" }
  ],
  "next_week_focus": "Focus on grammar+shadowing with emphasis on は vs が distinction. Add one grammar drill per session.",
  "items_to_retire": ["vocab_001", "vocab_002"],
  "items_to_add": ["grammar_003", "grammar_004"]
}