generate-speaking-prompt

name	generate-speaking-prompt
description	Deliver a structured speaking task from data/speaking.json, with hint scaffolding, target patterns, and a timer target — revealing the sample answer only after the learner attempts.

generate-speaking-prompt

When to Use

Invoke this skill when the learner runs /jp-speak or when generate-daily-tasks assigns a speaking task. During speaking+review weeks (17–24), this is the primary skill.

Inputs

Parameter	Type	Required	Description
level	string	yes	Learner's JLPT level: "N5", "N4", "N3"
topic	string	no	Topic preference. If omitted, auto-selected by recent focus.
duration_target	integer	no	Target speaking duration in seconds. Used to filter items.
item_id	string	no	Specific speaking item ID. If omitted, auto-selected.
show_sample	boolean	no	If true, reveal sample_answer_jp immediately. Default: false.

Outputs

A speaking session object:

Field	Type	Description
item_id	string	The speaking item used
prompt_zh	string	Task description in Chinese
duration_target_seconds	integer	Target duration
hints	string[]	Scaffolding sentence starters (always shown)
target_patterns	string[]	Grammar patterns the learner should try to use
timer_guidance	string	Human-readable timer instruction
sample_answer_jp	string	Model answer (withheld until learner submits, unless show_sample: true)
follow_up_prompt	string	Optional follow-up question to extend the conversation

Logic

Item Selection

1. Filter data/speaking.json by level and topic (if provided).
2. Filter by duration_target_seconds <= duration_target (if provided).
3. Prefer items not used in the last 7 days (check storage/daily_state.json).
4. Return the best match.

Hint Presentation

Always show hints[] before the learner starts. Hints are sentence starters, not complete answers. Present them as a numbered list labeled "可以用這些句型開始：".

Sample Answer Gate

The sample_answer_jp is withheld by default. After the learner indicates they have finished (e.g., types their answer or says "done"), reveal the sample and recommend running /jp-review for personalized correction.

Follow-Up Prompt

After the learner completes the task, generate one natural follow-up question in Japanese to extend the conversation (e.g., if they described their weekend plans, ask: 「それは楽しそうですね。どんな食べ物が好きですか？」).

Timer Guidance

Convert duration_target_seconds to a human-friendly instruction:

• 30s → "Try to speak for about 30 seconds — roughly 3–5 sentences."
• 45s → "Aim for 45 seconds — about 5–7 sentences."
• 60s+ → "Aim for [N] seconds — build on each point with one detail."

Example

Output (abbreviated):

{
  "item_id": "speak_001",
  "prompt_zh": "用日語做一段30秒的自我介紹。包含：你的名字、你來自哪裡、你的職業或身份、你學日語的理由。",
  "duration_target_seconds": 30,
  "hints": [
    "はじめまして、〜と申します。",
    "〜から来ました。",
    "〜をしています。",
    "日本語を勉強している理由は〜です。"
  ],
  "target_patterns": ["〜と申します", "〜から来ました", "〜をしています"],
  "timer_guidance": "Try to speak for about 30 seconds — roughly 3–5 sentences.",
  "follow_up_prompt": "どうして日本語を勉強し始めましたか？",
  "sample_answer_jp": "[withheld until submitted]"
}