From e159d01f7a9800812940ecd5016753a023cd3d1a Mon Sep 17 00:00:00 2001 From: michaelzhangwei Date: Mon, 27 Apr 2026 00:43:32 +0800 Subject: [PATCH] feat: add Phase 0 for scope and language confirmation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before analyzing the codebase, the skill now asks the user to confirm scope (full codebase vs. specific area) and course language (English / 中文 / Other). Language affects all user-facing content including module text, code translations, quizzes, and animations. Code syntax, function names, and technical identifiers are preserved as-is — only explanatory text is localized. --- SKILL.md | 20 ++++++++++++++++++++ references/content-philosophy.md | 19 +++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/SKILL.md b/SKILL.md index aedeb5b..7b837ad 100644 --- a/SKILL.md +++ b/SKILL.md @@ -22,6 +22,26 @@ When the skill is first triggered and the user hasn't specified a codebase yet, If the user provides a GitHub link, clone the repo first (`git clone /tmp/`) before starting the analysis. If they say "this codebase" or similar, use the current working directory. +### Phase 0: Scope and Language Confirmation + +Before analyzing the codebase, confirm two things: + +1. **Scope** — Ask if the user wants the full codebase or a specific area. If the user already specified a clear focus (e.g., "just the agent system"), acknowledge it and lock in that scope. If vague, ask one clarifying question. + +2. **Language** — Ask what language the course should be written in. The course content (explanations, code translations, quizzes, animations) should match the learner's preferred language. Do NOT assume English. + +Use `AskUserQuestion` with `multiSelect: false` to confirm language with these options: +- **English** — Course written in English (default if user doesn't specify) +- **中文** — Course content entirely in Chinese, including code translations, quiz questions, chat animations +- **Other** — Ask user to specify + +> **Important:** Language choice affects all user-facing content: module titles, explanations, code↔plain-translation pairs, quiz questions/options, group chat animations, callout boxes, tooltip definitions, and interactive element labels. Code syntax highlighting and technical identifiers (function names, file paths) should NOT be translated — only the explanatory text around them. + +After confirming scope and language, announce clearly: +> "Got it — full-scope course on the agent system, in **中文**. Let me dig into the code..." + +Then proceed to Phase 1. + ## Who This Is For The target learner is a **"vibe coder"** — someone who builds software by instructing AI coding tools in natural language, without a traditional CS education. They may have built this project themselves (without looking at the code), or they may have found an interesting open-source project on GitHub and want to understand how it's built. Either way, they don't yet understand what's happening under the hood. diff --git a/references/content-philosophy.md b/references/content-philosophy.md index 79fae1a..bbcb873 100644 --- a/references/content-philosophy.md +++ b/references/content-philosophy.md @@ -2,6 +2,25 @@ > **When to read this:** During Phase 2.5 (writing module briefs) and Phase 3 (writing module HTML). These principles guide every content decision — what to show, how to explain it, and how to test understanding. +### Language-Aware Content + +All text in the course must be written in the language confirmed in Phase 0. This includes: +- Module titles, subtitles, and headings +- Explanatory paragraphs and screen text +- Code↔plain translation explanations (left panel: code stays as-is; right panel: plain explanation in target language) +- Quiz questions, options, and feedback +- Group chat animation message text and sender labels +- Callout box content +- Glossary tooltip definitions +- Interactive element labels (button text, flow step descriptions) + +**What NOT to translate:** +- Code syntax, function names, variable names, file paths +- CSS class names, HTML attributes, data values +- Technical identifiers that must match the actual codebase + +The "Code ↔ English Translation" element name is a structural convention — when the course is in Chinese, it renders as "代码 ↔ 中文对照". Same element, same structure, different language. + These principles are what separate a great course from a generic tutorial. They should guide every content decision: ### Show, Don't Tell — Aggressively Visual