review-answer

name	review-answer
description	Analyze a learner's Japanese answer and return a corrected version, a natural native version, a list of mistakes with Chinese explanations, and brief coaching advice.

review-answer

When to Use

Invoke this skill when the learner runs /jp-review. It is also called internally after /jp-speak when the learner submits their spoken answer. The output is saved to storage/reviews.json.

Inputs

Parameter	Type	Required	Description
answer_text	string	yes	The learner's original Japanese text
expected_level	string	yes	The target JLPT level (e.g., "N5") — sets correction standards
target_patterns	string[]	no	Grammar patterns the learner was supposed to use (from the speaking task)
user_id	string	yes	Used to append result to storage/reviews.json
task_id	string	no	The task this answer belongs to

Outputs

A review object matching the reviews schema:

Field	Type	Description
corrected_text	string	Minimally corrected version (fix errors, preserve learner's vocabulary choices)
natural_text	string	A fully natural/native-sounding version of the same meaning
mistakes	object[]	Array of identified errors (see Mistake Object)
advice	string	1–3 sentence coaching summary in Chinese
target_pattern_check	object	Which target patterns were used correctly, missed, or misused

Mistake Object

Field	Type	Description
type	string	"grammar", "vocab", "particle", "conjugation", "naturalness"
original	string	The problematic phrase from the learner's answer
correction	string	The correct form
explanation_zh	string	Brief Chinese explanation of the error

Target Pattern Check Object

Field	Type	Description
pattern	string	The target pattern
status	string	"used_correctly", "used_incorrectly", "missing"
note	string	Specific observation about how the pattern was or wasn't used

Logic

Correction Philosophy

Minimal correction first (corrected_text): Only fix actual errors. Preserve the learner's vocabulary choices, sentence structure, and personal style. Do not "improve" things that are already correct.

Natural version second (natural_text): Rewrite the entire passage as a native speaker would say it — shorter, more idiomatic, natural word order. This shows the learner the gap between correct and natural.

Error Classification

Identify and classify errors:

• Grammar errors: Wrong verb conjugation, incorrect sentence-ending form, missing or extra auxiliaries.
• Particle errors: は vs. が, を vs. に, での vs. で, etc.
• Vocab errors: Wrong word choice that changes meaning or sounds unnatural.
• Conjugation errors: Incorrect tense, negative form, or te-form.
• Naturalness issues: Technically correct but sounds overly literal or foreign. These go in natural_text commentary, not as errors.

Advice Tone

• Encouraging and specific.
• Lead with what the learner did well.
• Limit to the 1–2 most important errors (not an exhaustive list of every issue).
• Use Chinese for the advice text (matches preferred_language_of_explanation).

Recurring Mistake Detection

If a mistake type appears in storage/progress.json under recurring_mistakes, note it in the advice: "這個錯誤已經出現過了，建議特別練習〜の grammar。"

Example

Input:

{
  "answer_text": "私は学生です。日本語を勉強するが好きです。",
  "expected_level": "N5",
  "target_patterns": ["〜が好きです"],
  "user_id": "user_001",
  "task_id": "speak_001_20260413"
}

Output:

{
  "corrected_text": "私は学生です。日本語を勉強するのが好きです。",
  "natural_text": "学生です。日本語の勉強が好きです。",
  "mistakes": [
    {
      "type": "grammar",
      "original": "勉強するが好き",
      "correction": "勉強するのが好き",
      "explanation_zh": "動詞接「が好き」時，需要用「の」將動詞名詞化：〜するのが好きです。"
    }
  ],
  "advice": "整體很好！句子結構清楚。記住「〜するのが好き」這個固定搭配，加了「の」才自然。繼續練習！",
  "target_pattern_check": [
    { "pattern": "〜が好きです", "status": "used_incorrectly", "note": "Used 勉強するが好き instead of 勉強するのが好き — missing の nominalization." }
  ]
}