All metric definitions and degradation rules are in references/metrics.md—required reading before executing this skill. Design decisions and baseline test records are in DECISIONS.md (local file, not committed to the repo).
Overview
Read through the raw transcript and diagnose the speaker's delivery performance: expression layer (verbal tics/pacing/sentence patterns) + structural signals (time allocation/promise follow-through/interaction) + deck comparison (when a finalized deck is available: the structural gap between design and delivery); accumulate a speaker profile across sessions to form a "review → remind → recheck" improvement loop.Primary use (user calibration 2026-09-11): help speakers discover verbal tics they are unaware of and recheck them across sessions—verbal tics are the main output; time allocation/promises/deck comparison are supporting context; interaction and on-site operations noise are recorded as facts only (Principle 7).
| Mode | Trigger | Output |
|---|---|---|
| Single-session review (default · standard) | One raw transcript | archive/.../report.md Seven-section report + profile append |
| deck comparison (enhanced, optional) | Transcript + finalized courseware HTML | "Courseware comparison" section embedded in the report: page-time mapping, fulfillment classification, min/page overload warning |
| Course structure review (advanced) | UserExplicitly requests"course structure review / review course design / compare courseware with actual delivery to find structural problems" | Zhihe-review-style structural diagnostic report (template see references/structural-review-template.md), saved toproject directory + archive copy |
| Cross-session comparison | Profile already has history + new session | Comparison section embedded in the report + watchlist recheck |
| Degraded operation | No timestamps / corrected transcript / deck parsing failure | Declare the defect and narrow the scope (see degradation table in metrics.md) |
Dependencies
System dependencies
| Dependency | Installation method |
|---|---|
| python3 ≥ 3.9 | Built into macOS / brew install python |
Python packages
No external dependencies (scripts/analyze_stats.py pure standard-library implementation; the vocabulary YAML is read with a built-in parser, falling back to the built-in default table on failure).
Core principles (non-negotiable)
- Full read-through with dynamic discovery takes priority. You must use Read to read the full text completely (if it exceeds the single-pass limit, read it in pages to the end), first write down the "first impression," then do the item-by-item analysis. Preset vocabulary lists and prior-session profiles are only references and comparison anchors—doing the analysis as a checklist against a table is prohibited; patterns not found in prior sessions are often the most important findings of the current session.
- Numbers come from scripts, findings come from the read-through. Any number that enters the report must be produced by
scripts/analyze_stats.py; the agent does not estimate frequencies, do mental math, or invent its own statistics pipeline. Quantify countable new patterns found in the read-through with--count. - Only raw transcripts are used。
_corrected/_polishedThe transcript's verbal-tie evidence has been removed by the transcription error-correction process—warn the user and downgrade; verbal-tie statistics are marked unreliable. - Every finding must include an original-quote example + timestamp, otherwise it does not go into the report.
- Only evaluate expression and structure, not content quality(whether the logic holds, depth, whether opinions are right or wrong). Whether a course is taught well is outside this skill's scope.Courseware comparison likewise only evaluates "the structural gap between design and delivery"(which pages were covered/skipped/moved, density, friction in finding locations)—skipped pages may be deliberate trade-offs (report faithfully, do not deduct points; moved-and-recalled items may be marked as highlights); why the methodology itself cannot be broken down, and whether the structure should be changed, belong to project retrospectives and the speaker, not to this skill.The only exception: in advanced mode, "Course Structure Retrospective" may evaluate the course after explicit user triggering (see Phase 6 and D7), producing revision suggestions; without explicit triggering, never cross this boundary.
- The report's first page must declare blind spots: the ASR engine swallows vocalizations, so counts of "uh/um/ah"-type sounds are unreliable; this report's verbal tics cover only discourse markers and countable language patterns.
- Interaction and on-site operational noise are not treated as problems(user calibration on 2026-09-11): the course type determines the interaction format—for a course that "lectures throughout and does QA at the end," little interaction is normal design; do not force interaction anchors, and do not issue remediation reminders because "interaction drops to zero/no interaction in the second half"; exposed troubleshooting, administrative chatter, and hot-mic leaks are environmental/operational factors—record them faithfully, do not characterize them as problems. The watchlist and "next-time reminders" only output verbal tics, deck structure, and promise-type actionable items.
Workflow
Phase 0: Input check
- Confirm it is a raw transcript (filename contains
_corrected/_polished→ warn and downgrade) - Confirm whether timestamps exist (determines whether speech rate/pauses/three-segment split are available)
- Confirm whether there is a finalized courseware (HTML/PDF/per-page export)—if yes → enable Phase 4.5 courseware comparison for this session; if no → the report declares the default, and the rest of the process is unaffected
- Check the archive: whether a record for this instructor already exists under
profiles/(if yes → this session includes comparison and review)
Phase 1: Instructor isolation + baseline numbers
Run the script (in the skill directory; for first use of the word list, copy it from example first; the real word list is gitignored by the repository, and when missing the script falls back to the built-in default list, so analysis is not blocked):
cp -n config/marker_words.example.yaml config/marker_words.yaml
python3 scripts/analyze_stats.py '<转录稿>' --markers config/marker_words.yaml [--deck '<课件.html>'] --out <archive目录>/stats.json
The JSON contains: main-speaker identification (by default the one with the most characters;--speaker can specify an index/name), exclusion zones, fixed anchor word frequencies (including per-10,000-character frequency and three-segment distribution), speech rate, long pauses (with surrounding context), long sentences, paragraph-opening starters and runs, confirmation-seeking counts, promise candidates, slide anchors (slides_ts frame timestamps), courseware page table (deck: page count + each page's label/title/text—text is an excerpt of the page body, truncated to 600 characters per page, enough to judge content coverage;parse: failed for downgrade handling, see metrics.md).
Isolation verification(ASR makes mistakes; baseline testing shows two kinds of contamination):
- The main speaker accounts for < 50% of the full transcript's characters → the wrong person may have been selected; confirm with the user
- Spot-check attribution boundaries: whether the segments before and after the lecture starts and the closing acknowledgment segment were misattributed by ASR to the wrong speaker (baseline example: the host's acknowledgment was attributed to the instructor); if the contamination magnitude is < 1 minute, record it without blocking
Phase 2: Full read-through and dynamic discovery (main line)
- Complete read-through, start by writing the first impression: the overall feel + the 2-3 most salient things (subjectivity allowed, but each item must have at least one timestamp anchor)
- Dynamically identify patterns specific to this session's instructor.Pattern type reference(these are detection starting points, not exhaustive, and must not be treated as a checklist):
- All-purpose references (this/that/thing/stuff replacing key terms)
- Fixed templates (e.g. the whole string "such a kind of X" reused at high frequency)
- Noun article-ization ("a/one" prefixed indiscriminately)
- Stacked hedging words (maybe/actually/I think/I believe)
- Repetition restarts ("we we" "I I")
- Self-corrections exposed and not recovered (admits a misspeaking then keeps going wrong)
- Circular back-references ("as I said earlier" "back to this page" at high frequency = signal of structural looping)
- Administrative chatter (hold on/never mind/it doesn't matter leaking into the mic) — this is operational noise; record it as-is and do not treat it as an issue (Principle 7)
- Same thing, multiple names (the same tool called different things)
- Sentence-opening starters, long nested sentences
- Filler sounds (uh/um/ah)Out of scope for findings(blind spot, see Principle 6)
- Unclear English term pronunciation suspected → mark "suspected, needs comparison against recording", no attribution of fault (ASR drift and pronunciation issues cannot be distinguished)
Phase 3: Quantitative verification
- For each countable pattern found in Phase 2, use
--count '词1,词2,这样的一个'to supplement the count (can pass full phrases/template strings) - When script numbers conflict with the read-through impression,correct the impression based on the script(an agent's frequency intuition is unreliable; baseline measurement deviation can reach 50%)
Phase 4: Structural signals (read-through primary, script auxiliary)
- Time allocation: divide the whole session into greeting/debugging / operation waiting / main demonstration / interactive Q&A; time anchors use slide anchors + long pauses + exclusion-zone spans. Operation waiting (waiting for scan codes/installing software/troubleshooting)is not penalized but its proportion must be reported truthfully
- Promise recovery：
promise_candidatesremove false positives → for each real promise, find fulfillment evidence later in the text → output "promise → ✓/✗/uncertain + later timestamp" - Interaction density(record form only, not as an issue — Principle 7): true interaction = asking the audience questions and leaving room for responses, asking everyone to do hands-on operations. Report the distribution truthfully by the three segments; the lesson type determines the interaction form (a lesson that teaches first and does Q&A afterward having little in-class interaction is normal design), and do not attribute or flag zero interaction. Self-questioning and self-answering does not count as interaction; mark it separately
Phase 4.5: Deck comparison (when a finalized deck exists; for origins see DECISIONS D6)
The script produces data for both sides,mapping and classification rely on the read-through：
- Page table ↔ frame anchors：
deck.pages(page count, label, title, and text all come from the script) +slides_ts(frame timestamps).Frame ≠ page— keyframes may repeatedly capture the same page, miss pages that appear for only a few seconds, and frames carry no page numbers; mapping must match the spoken content near the frame timestamp against thepage title + bodyand place each page accordingly (when the text excerpt is insufficient for judgment, Read the full text of the corresponding section in the original HTML). - Fulfillment classification(Read-through judgment, each page classified into one category, entered into the report table; the basis for judgment = the oral content'scoverage of the page body's key points, not just whether the title is tangentially related):
- Fully covered(covered thoroughly at the designed position) | Partially covered(content partially covered or no framework established) | Skipped(the entire page was not covered) | Relocated and recovered(covered elsewhere, with timestamp noted—proactive trade-offs may be marked as highlights) | Proactively declared(the speaker explicitly says "no need to note this / skip it directly", quote the original words—the strongest evidence of a mismatch between the designed route and the live route)
- Density accounting: reported by module (use PART/hero pages or the speaker's spoken segmentation to divide modules) as page count × actual speaking time → min/page(rough measure: total module duration; net measure: deduct live demonstrations and waiting—report both measures). For static explanation < 1.5 min/page and skipped + proactively declared ≥ 2 pages → overload warning.
- Find positional friction: read through to find page-turning, position-finding phrases such as "let's look at the order / turn to / which page is it on",
--countquantify—a signal that page order and the speaker's mental order are inconsistent. - Report only the gap facts,do not diagnose whether the methodology should be changed(Principle 5); methodology-level conclusions are left to the project retrospective.
Phase 5: Report + Archive + Filing
report.md seven sections：
- First impression(the overall feeling after a read-through, each item with a timestamp anchor)
- Snapshot (duration / speaker word count / average speaking rate / fixed anchor verbal tics Top 5 table)
- Dynamic findings · expression layer (each item = script number + original quote example + timestamp + one actionable suggestion; including strengths to retain)
- Structural signals (time allocation bar, unredeemed promises list, interaction density)
- Deck comparison (when a deck is available: redemption classification table, module min/page, overload warning, positional friction; declare default when no deck)
- Comparison with previous session (fixed anchors ↑↓ + watchlist item-by-item review "was it changed?"; for the first session write "establish baseline")
- 3 reminders before the next talk (generated from the archive's historical trends, not just from the current session; only verbal tics/deck structure/promise-type improvable items, excluding interaction follow-ups and operational noise improvements—Principle 7)
Archive profiles/{讲师}.yaml(appended for each session; the instructor archive is personal data, already gitignored by the repository, stored locally only):
sessions:
- {date: 2026-03-01, name: 某实务培训班（示例）, minutes: 120, chars: 24000,
rate_per_min: 210.0, anchors: {这个: 95.0, 就是: 40.2, 然后: 33.1, 其实: 25.7},
interaction: 4, promise_fulfilled: "90%", watchlist: [这样的一个X模板, 弱化词堆叠], reminders: [...],
deck: {pages: 64, taught: 45, skipped: 6,半讲: 5, moved: 4, declared_skip: 2, min_per_page: 1.4, flip_hunts: 2}}
watchlist = personal patterns newly discovered in this session,to be reviewed with priority in the next session, but still read through first(Principle 1).
Dual-write filing：archive/{YYYYMMDD_HHMMSS}_{原文件 basename}/report.md(including stats.json) + source directory mirror {原文件 basename}_review.md. The original transcript is never touched.
Product placement conventions(to avoid sediment scattering everywhere):
| Product | Primary placement | Copy placement | Purpose |
|---|---|---|---|
Seven-section regular report report.md |
skill archive/ | — | The minimal set for cross-session comparison |
Structural retrospective with deck review.md |
Project course directory(e.g. 4 - 课程演示/讲课实录/{basename}_review.md） |
skill archive/ save a copy | The main copy is for the speaker to revise the lesson; the duplicate is for cross-session in-depth comparison |
stats.json(mechanical product of the script) |
skill archive/ | — | An objective anchor point for cross-session comparison; the version with a deck uses stats_deck.json to distinguish |
Instructor profile profiles/{讲师}.yaml |
inside the skill | — | Longitudinal record of evaluating people (course reviews do not go into the profile) |
Placement rationale: the form of review.md (deck comparison + cross-version comparison + methodology feedback) is far larger than a regular report and contains methodology-layer content; the main copy must be in the project directory together with the speaker's decision context; the skill archive stores a duplicate to ensure cross-session index accessibility. Original transcriptNever move—all outputs are derivatives.
Do not accumulate cross-project assets within the skill: the reusable teaching experience/insights accumulated (kitchen metaphor, progressive rhetoric, audience differences, etc.) belong to the wiki's "training knowledge accumulation" function and do not go into the skill; the skill only accumulatesthe review methodology itself(caliber, templates, watchlist system).
Phase 6 (advanced mode · explicit trigger): course structure review
Boundary with regular review (D7): regular reviewevaluates people(instructor performance), advanced reviewevaluates the course(course design)—because it breaks the D2 boundary, it must be explicitly requested by the user to start; the output is the basis for the speaker to revise the courseware/methodology and does not go into the instructor profile.
Prerequisite: transcript + final deck, neither can be missing (only a deck → only do Step 1 courseware checkup; only a transcript → fall back to regular mode). Skeleton template:references/structural-review-template.md。
- Automatic courseware checkup (deck only): read
deck.self_check——module_distribution: page-count distribution of each module/step (the agent merges fine-grained label groups into major modules);near_dup_pages: candidates for dual-view/near-duplicate pages on the same topic (filter out benign false positives such as table of contents ↔ hero)—independent content judged the same way and laid out on two pages is a common source of "page overload";title_term_index+ full-text searchdeck.pages[].text: check where the same concept is placed across multiple pages/stepsattribution overlap；- Route hypothesis: whether the deck contains pages for multiple creation routes (handwritten six-part vs generator), and whether they are consistent with the actual demonstration route in this session.
- Bidirectional comparison (deck × actual delivery): building on the classification realized in Phase 4.5, add three directions—
- Designed but not delivered: whether the knowledge points of skipped/half-delivered pages appear elsewhere in oral delivery (relocated) or are truly lost;
- Delivered but not designed: large blocks of oral content with no corresponding page (improvisation)—mark timestamps and duration, and judge "worth adding a page / intentionally discarded";
- Emergent position mismatch: content designed on a certain page for Step A is actually delivered only in the context of Step B (a signal that teaching order ≠ work order).
- Structural diagnosis: integrate 1+2 to find systematic mismatches between the deck's design assumptions and the actual delivery route (not just single-page issues)—each diagnosis must have an evidence chain of page numbers + timestamps, and distinguish "root cause in deck design" from "root cause in on-site improvisation".
- Revision suggestions: Three layers — the deck layer (page-level actions: merge/delete/reorder/add live-action markers), the delivery layer (pacing allocation, demo timing), and the examples layer (how well examples match the method); write actionable items to page numbers.
- Backflow outlet: Methodological findings (problems with the step framework itself) indicate where to route back (book chapter/methodology owner) — this skill only points them out, it does not make decisions on behalf of the book project.
- Artifact persistence: The report is written according to the template into theproject directory(e.g.
3 - 课程内容/YYMMDD 课程结构复盘（主题）.md); the archive stores stats.json + a copy; the instructor profile only appends thedeck:field group, and does not append course evaluations.
Common pitfalls (baseline measured on 2026-08-24, all actually occurred)
| Pitfall | Consequence | Countermeasure |
|---|---|---|
| Slide anchor URL lines mixed into body text with a self-made pipeline count | Word count inflated by 50% (46,652 > full script 36,176), all speaking rates wrong | Do not build your own awk/grep counting pipelines; use only this skill's scripts (URLs/punctuation already excluded) |
| Timestamps switch to HH:MM:SS format after 59:59 | "26:20" is parsed as 26 hours, making the duration negative | The script already handles both formats; think of this pitfall before writing your own time parser |
| Substring overlap ("这个" ⊃ "在这个里面") | Double counting | The script deduplicates by longest-priority;--count pass the complete phrase |
| Self-made speaking-rate denominator ("actual speaking duration" definition drift) | Not comparable across sessions | Use only the script's rate definition (see metrics.md for the definition) |
| Speaker attribution contamination not verified | Host utterances are counted as instructor verbal tics | Phase 1 two-step isolation verification |
| Treating a preset word list as the analysis itself | Missing main verbal tics outside the word list (in the baseline, "一个" appears 477 times and is not in any preset list) | Read-through first; the word list is only an anchor |
| Treating frame anchors as page numbers (frame ≠ page: keyframes may repeat/miss/no page number) | "No frame appears" is misjudged as a skipped page | Frame-page mapping relies on matching spoken content with page titles (Phase 4.5 step 1); no frame is only weak evidence |
| Reporting only one measure for min/page | The coarse measure including live-demo waiting masks static page overload (measured 73min/28 pages looks like 2.6, but after deducting live demos it is actually 1.4) | Report both coarse and net measures (Phase 4.5 step 3) |
Boundaries with adjacent skills
| This skill | transcription-corrector | course-generator | |
|---|---|---|---|
| Input | raw script | raw script | raw/corrected script |
| Action | Delivery diagnosis (read-only on the original text, produces a report) | Error correction and rewriting (Edit persistence) | Generate course |
| For verbal tic evidence | Keep (statistics target) | Delete (cleanup target) | Do not care |
If you want to both review and correct the same raw script: run this skill first (read the original text), then run transcription-corrector.