confusion-tracker

Name: confusion-tracker
Author: ZeKaiNie

258stars14forks

How to install confusion-tracker?

zekainie/universal-examprep-skill/confusion-tracker

$npx -y skills add ZeKaiNie/universal-examprep-skill --skill confusion-tracker

Installs into the current project.

Summary

教学过程中自动捕获和记录学习者的概念疑难点（"为什么/是什么/怎么推/什么意思"类型的问题），保存到进度文件的"概念疑难点记录"区，形成考前回顾清单。

Files · 1

View on GitHub

SKILL.md

1	# confusion-tracker — concept-confusion tracking
2
3	## Purpose
4	Capture the learner's concept-level confusions (why / what / how-derived questions — not quiz answers) during tutoring and record them into the 「概念疑难点记录」 section of `study_progress.md`, building a pre-exam review list. Used by `exam-tutor` (while teaching) and `exam-review` (during the final sweep).
5
6	## Activation
7	- During tutoring, when the learner asks a concept question matching: 「为什么…？」/「…是什么、什么意思？」/「这个公式怎么推、怎么来的？」/「…的重点是什么？」/「讲一下…」, or any clarification follow-up that is not a quiz answer.
8	- Skip for: pure quiz answering (right or wrong), and chit-chat that needs no concept explanation.
9
10	## Inputs
11	- The progress-file path (e.g. `study_progress.md`), read at session start.
12	- The current chapter/phase name being taught.
13
14	## Workflow
15	1. Detect — decide whether the follow-up is a concept question (not a quiz item or its answer).
16	2. Answer — give a concise, clear explanation grounded in the current wiki chapter. Label the source: 🟢 来自资料 for material-sourced content, 🟡 AI补充，可能与你老师讲的不完全一致 for AI-supplied background. Never present AI-added content as the teacher's.
17	3. Record — persist the confusion: `关联章节` / `疑难点` (one line) / `解答要点` (≤2 sentences) / `状态` (default 待回顾). If `study_state.json` is absent and Python works, first run `python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> init`. The normal and ONLY state-backed write path is then `python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> add-confusion --chapter <ch> --note <疑难点/解答要点>` — the md table is a generated view and a hand-appended row is lost on the next render. Only when Python truly cannot run may the no-Python fallback append directly to the 「## 💡 概念疑难点记录」 table in `study_progress.md`, auto-incrementing the `序号` column. A nonzero state command while Python runs is a fail-loud write failure, not permission to hand-edit.
18	- Persist-first (notebook CLI) — the state row stays exactly as above; ADDITIONALLY persist the full explanation itself (step 2's answer, provenance labels included) so it survives outside chat: `echo <explanation body> \| python "${CLAUDE_SKILL_DIR}/scripts/notebook.py" --workspace <ws> add-entry --chapter <ch> --type confusion --id <slug> --title <confusion gist>` (body via STDIN; same `--id` replaces in place; `notebook/index.md` rebuilds; the script resolves from the skill package root). The receipt line then carries the pack-provided link line (zh 「完整解答：`notebook/chNN.md#<anchor>`｜目录：`notebook/index.md`」, en `Full explanation: notebook/chNN.md#<anchor> \| Index: notebook/index.md`). On a failed notebook write, TELL the student (the chat explanation already delivered stands as the copy); file-less clients keep chat-only output per `exam-cram`'s capability dispatch.
19	4. Confirm — tell the learner it was logged (e.g. 「已记录到疑难点」) in one short line, without breaking the teaching flow.
20
21	## Output Contract
22	- Persist one confusion record (`关联章节` / `疑难点` / `解答要点` / `状态`) through `update_progress.py add-confusion`; initialize state first when Python works. Only a true no-Python fallback appends one row to the 「## 💡 概念疑难点记录」 table in `study_progress.md` (`序号` auto-increments).
23	- Persist-first default: the full confusion explanation is ALSO written into `notebook/chNN.md` via the notebook CLI (`--type confusion`, Workflow step 3) — the state row records that the confusion exists, the notebook entry preserves the explanation itself; the receipt carries the pack-provided link line. File-less clients keep chat-only output.
24	- During the final sweep, read the confusion records and have the learner restate each: update `状态` in place — 待回顾 → 已回顾 when explained correctly; keep 待回顾 and re-explain otherwise. Never overwrite other skills' writes.
25	- Student-facing output defaults to English (Simplified Chinese if the student opened in Chinese); the persisted `study_state.json.language` code (`zh`/`en`/`bilingual`) switches it per exam-cram's dispatch rule with single-language purity.
26
27	## Language packs
28	Student-visible wording for this skill lives in per-language packs — load the one matching `study_state.json.language` BEFORE emitting any student-visible output:
29	- `中文` → [`../../locales/zh/skills/confusion-tracker.md`](../../locales/zh/skills/confusion-tracker.md)
30	- `English` → [`../../locales/en/skills/confusion-tracker.md`](../../locales/en/skills/confusion-tracker.md)
31	- `双语` → compose the zh and en packs block by block, zh first with a `> EN:` mirror (rules in [`../../docs/language-policy.md`](../../docs/language-policy.md))
32	Display aliases such as `中文`, `English`, and `双语` are normalized by `update_progress.py`; route persisted state on `zh`, `en`, or `bilingual`. Unset language → the merged first-ask decides it; default English unless the student opened in Chinese.
33
34	## Boundaries
35	-

People who liked this also viewed

6 picks

Type

confusion-tracker

258stars14forks

View on GitHub

How to install confusion-tracker?

zekainie/universal-examprep-skill/confusion-tracker

$npx -y skills add ZeKaiNie/universal-examprep-skill --skill confusion-tracker

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# confusion-tracker — concept-confusion tracking
2
3	## Purpose
4	Capture the learner's concept-level confusions (why / what / how-derived questions — not quiz answers) during tutoring and record them into the 「概念疑难点记录」 section of `study_progress.md`, building a pre-exam review list. Used by `exam-tutor` (while teaching) and `exam-review` (during the final sweep).
5
6	## Activation
7	- During tutoring, when the learner asks a concept question matching: 「为什么…？」/「…是什么、什么意思？」/「这个公式怎么推、怎么来的？」/「…的重点是什么？」/「讲一下…」, or any clarification follow-up that is not a quiz answer.
8	- Skip for: pure quiz answering (right or wrong), and chit-chat that needs no concept explanation.
9
10	## Inputs
11	- The progress-file path (e.g. `study_progress.md`), read at session start.
12	- The current chapter/phase name being taught.
13
14	## Workflow
15	1. Detect — decide whether the follow-up is a concept question (not a quiz item or its answer).
16	2. Answer — give a concise, clear explanation grounded in the current wiki chapter. Label the source: 🟢 来自资料 for material-sourced content, 🟡 AI补充，可能与你老师讲的不完全一致 for AI-supplied background. Never present AI-added content as the teacher's.
17	3. Record — persist the confusion: `关联章节` / `疑难点` (one line) / `解答要点` (≤2 sentences) / `状态` (default 待回顾). If `study_state.json` is absent and Python works, first run `python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> init`. The normal and ONLY state-backed write path is then `python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> add-confusion --chapter <ch> --note <疑难点/解答要点>` — the md table is a generated view and a hand-appended row is lost on the next render. Only when Python truly cannot run may the no-Python fallback append directly to the 「## 💡 概念疑难点记录」 table in `study_progress.md`, auto-incrementing the `序号` column. A nonzero state command while Python runs is a fail-loud write failure, not permission to hand-edit.
18	- Persist-first (notebook CLI) — the state row stays exactly as above; ADDITIONALLY persist the full explanation itself (step 2's answer, provenance labels included) so it survives outside chat: `echo <explanation body> \| python "${CLAUDE_SKILL_DIR}/scripts/notebook.py" --workspace <ws> add-entry --chapter <ch> --type confusion --id <slug> --title <confusion gist>` (body via STDIN; same `--id` replaces in place; `notebook/index.md` rebuilds; the script resolves from the skill package root). The receipt line then carries the pack-provided link line (zh 「完整解答：`notebook/chNN.md#<anchor>`｜目录：`notebook/index.md`」, en `Full explanation: notebook/chNN.md#<anchor> \| Index: notebook/index.md`). On a failed notebook write, TELL the student (the chat explanation already delivered stands as the copy); file-less clients keep chat-only output per `exam-cram`'s capability dispatch.
19	4. Confirm — tell the learner it was logged (e.g. 「已记录到疑难点」) in one short line, without breaking the teaching flow.
20
21	## Output Contract
22	- Persist one confusion record (`关联章节` / `疑难点` / `解答要点` / `状态`) through `update_progress.py add-confusion`; initialize state first when Python works. Only a true no-Python fallback appends one row to the 「## 💡 概念疑难点记录」 table in `study_progress.md` (`序号` auto-increments).
23	- Persist-first default: the full confusion explanation is ALSO written into `notebook/chNN.md` via the notebook CLI (`--type confusion`, Workflow step 3) — the state row records that the confusion exists, the notebook entry preserves the explanation itself; the receipt carries the pack-provided link line. File-less clients keep chat-only output.
24	- During the final sweep, read the confusion records and have the learner restate each: update `状态` in place — 待回顾 → 已回顾 when explained correctly; keep 待回顾 and re-explain otherwise. Never overwrite other skills' writes.
25	- Student-facing output defaults to English (Simplified Chinese if the student opened in Chinese); the persisted `study_state.json.language` code (`zh`/`en`/`bilingual`) switches it per exam-cram's dispatch rule with single-language purity.
26
27	## Language packs
28	Student-visible wording for this skill lives in per-language packs — load the one matching `study_state.json.language` BEFORE emitting any student-visible output:
29	- `中文` → [`../../locales/zh/skills/confusion-tracker.md`](../../locales/zh/skills/confusion-tracker.md)
30	- `English` → [`../../locales/en/skills/confusion-tracker.md`](../../locales/en/skills/confusion-tracker.md)
31	- `双语` → compose the zh and en packs block by block, zh first with a `> EN:` mirror (rules in [`../../docs/language-policy.md`](../../docs/language-policy.md))
32	Display aliases such as `中文`, `English`, and `双语` are normalized by `update_progress.py`; route persisted state on `zh`, `en`, or `bilingual`. Unset language → the merged first-ask decides it; default English unless the student opened in Chinese.
33
34	## Boundaries
35	-

People who liked this also viewed

6 picks

Type