transcription-corrector

Transcription Corrector

For the first-use flow, see references/first_use.md. For the judgment criteria in the workflow, see references/correction_patterns.md。

Overview

Uniformly correct the homophone/near-form/spelling errors in the raw transcript that "sound right but are written wrong" according to the user dictionary, and do light polishing as needed.Do not do: rewriting, summarizing, cutting, changing facts, generating course chapters.

Mode	Trigger	Output
Correction mode (default)	When given a raw transcript, first do "proofreading"	archive/.../{原文件}_corrected.md + proofreading comparison log
Correction + light polishing	Also merge speakers/organize punctuation along the way	Polish on top of correction, output to archive/.../{原文件}_polished.md

Boundaries with downstream processing work：

• This skill does not output course outlines, does not reorganize chapters, and does not rewrite into written course material; it only does the "reads correctly, no longer embarrassing" step.
• The user dictionary YAML format (version + terms list) has become the public interface convention of this skill; other downstream processing work can read the same dictionary file as needed.

Workflow

The workflow is organized by 5 Phases , each Phase containing 1-3 Steps. Phases 1-3 are enabled by default, Phase 4 is disabled by default (requires explicit user enablement).

Phase 1 准备
  Step 1.1  读取配置（词典）
  Step 1.2  TXT → MD 转换（如需要）

Phase 2 识别
  Step 2.1  识别文件结构
  Step 2.2  通读识别高置信误转写

Phase 3 修正（默认开启）
  Step 3.1  词典统一替换（改字）
  Step 3.2  基础空白清理（改空白）
  Step 3.3  口语词精简（删字）

Phase 4 润色（默认关闭）
  Step 4.1  发言人合并
  Step 4.2  标点规范
  Step 4.3  段落切分

Phase 5 输出
  Step 5.1  主归档（必出）
  Step 5.2  源文件目录镜像（必出）

Why group it this way：

• Phase 1 Preparation vs Phase 2 Recognition vs Phase 3 Correction: Preparation does not touch text content; Recognition is "looking"; Correction is "changing". The three are distinct in nature
• Three Steps inside Phase 3 change three different types of objects: 3.1 changes characters (semantics), 3.2 changes whitespace (format), 3.3 deletes characters (language characters). The three types of operations are each independent and can be audited separately
• Phase 3 vs Phase 4: Phase 3 is "reads correctly" (lossless / lightly lossy), enabled by default; Phase 4 is "looks professional" (structural adjustment), disabled by default. The two are clearly distinct
• Phase 5 Output is decoupled from the first 4 Phases: regardless of what the first 4 steps did, the output stage dual-writes according to the same strategy

---

Working mechanism

The essence of transcript correction is "making an independent judgment for each mis-transcription". The input to this judgment is the context, the output is one Edit, and the three must be completed by the same agent in the same context.

Why expand by "each Edit"

• Whether each mis-transcription holds depends on what it refers to in context. For example, "style" may be a skill name, or it may be the actual "style"—batch replacement cannot distinguish.
• ASR errors are endless(case drift, space drift, word-break rejoining, syllable swallowing, near-form characters...), any static rule will miss some.
• The dictionary is a "target-value reference table", not a "wrong word → correct word" mapping.terms: ["WorkBuddy"] tells the agent "the correct spelling is WorkBuddy", but does not tell the agent "whether this occurrence in the source text needs to be changed".

From this followsthe natural execution flow：

1. the agent uses Read Read the source file into context (must read the full text)
2. For each candidate mistranscription, the agent independently decides "replace / don't replace" in context
3. Use Edit to persist each decision to disk
4. Use Write to write out the correction_log.md / meta.json / source directory mirror

Why this flow is self-consistent

• Context is only complete after Read; judgment must happen after Read
• Edit is a "local change" tool, which naturally corresponds to "each decision"
• Write writes the whole file, corresponding to "one-shot output" like logs/metadata
• These three steps form the minimal executable closed loop. Any other approach (batch scripts, delegation to a sub-agent, regex lists) lacks the semantic guarantee of at least one of these steps

---

Phase 1: Preparation

Step 1.0: Load skill configuration (switch defaults)

The skill's various polishing switches are controlled by config/config.env . Load order:

1. The key=value passed via command line/invocation parameters overrides
2. config/config.env(bundled with this skill)
3. config/config.env.example(the "master copy" of defaults, used when step 2 is missing)
4. If neither step 2 nor step 3 exists, all Steps in Phase 4 are disabled, and only Phase 1-3 run

Configuration example（config/config.env.example）：

# Phase 4 润色开关（默认全开，按需关闭）
POLISH_MERGE_SPEAKERS=true     # Step 4.1
POLISH_PUNCTUATION=true        # Step 4.2
POLISH_PARAGRAPH_SPLIT=true    # Step 4.3
POLISH_TOPIC_SECTION=true      # Step 4.4
POLISH_SUMMARY=true            # Step 4.5

# 输出策略
SOURCE_MIRROR=true             # 源文件目录镜像
SOURCE_MIRROR_CONFLICT=timestamp  # 冲突加时间戳

# 日志详细度
LOG_VERBOSITY=verbose          # verbose | compact

Missing keys uniformly take the values from the "default" column of this section's table (not hardcoded in the file; each Step's own § section notes its default value).

Step 1.1: Read the dictionary

1. Dictionary file lookup order (use the first one that exists):

   • The dictionary path passed via command line/invocation parameters
   • config/user_dictionary.yaml(bundled with this skill)
   • If none exist, prompt the user to copy config/user_dictionary.example.yaml as config/user_dictionary.yaml

2. Dictionary YAML format:

version: 1
terms:
  - "WorkBuddy"
  - "Claude Code"
  - "Codex"

1. The dictionary's role:target values + confidence weights, not triggers
   • Dictionary entries are the "correct spelling"—telling the AI what the target value is
   • Dictionary entriesdo not directly trigger replacement: the AI must still first make a contextual judgment (whether this word in the current context points to the object represented by the dictionary entry)
   • Dictionary entriesincrease the winning weight of candidate replacements: when the AI chooses between multiple candidate spellings, the spelling registered in the dictionary has higher priority
   • In other words: the dictionary makes "workbody / work body / Workbuddy" more likely to be rewritten as "WorkBuddy" in competition, but the premise is still that the context clearly points to the WorkBuddy product; homographs out of context will not be "forcibly pulled" over by the dictionary
   • Do notuse the dictionary as an "incorrect word → correct word" mapping table
   • Do notforce replacement of ordinary words just to use the dictionary
   • In ambiguous or low-confidence scenarios, always keep the original text

Step 1.2: TXT → Markdown conversion (if needed)

When the input is a .txt file, do format conversion first before entering Phase 2.

Trigger condition: the input file extension is .txt。

Conversion rules(conservative—only format wrapping, no content changes):

1. Speaker + timestamp line(e.g. 发言人 1 00:33:09）：
   • Recognition regex:^(发言人|说话人|Speaker|S)\s*[\d一二三四五六七八九十]+[\.、]?\s*(\d{1,2}:\d{2}(?::\d{2})?)$
   • Convert to Markdown bold line:**发言人 1 00:33:09**
2. Blank line between paragraphs: consecutive non-empty lines are treated as the same paragraph (original line breaks preserved), with one blank line added between paragraphs
3. Do not delete any text: blank lines, whitespace, ASCII decorative lines (---、===), etc. are all preserved
4. Do not recognize H3 / H4 heading levels: only up to the H2 level—H2 headings are inserted in Phase 4 Step 4.4 according to the "topic-based chaptering" principle; do not proactively upgrade any paragraph to ###/####
5. Do not recognize lists: do not convert - xxx into a markdown list—keep it as is

Output：

• Intermediate artifact:{原文件 basename}_converted.md, kept in the archive subdirectory
• Subsequent Steps 2.1~5.2 are performed on the converted copy
• The original .txt file remains untouched

Example：

Input (raw.txt）：

发言人 1  00:33:09
我先说一下比较好的部分，就是整个最终的报告篇幅是比较充分的。
然后大家在一开始不知道怎么样一个报告是比较完善的，也知道怎么样去借鉴他山之石。
从这个阿尔法 gpt里面的这报告相当于蒸馏他的一个一个想法啊。
这个这个在前期一开始搭基建的时候确实是很有必要的一个措施。

发言人 1  00:33:57
呃然后。我注意到咱们在最终生成法律服务意见书的时候...

Output (raw_converted.md）：

**发言人 1  00:33:09**
我先说一下比较好的部分，就是整个最终的报告篇幅是比较充分的。
然后大家在一开始不知道怎么样一个报告是比较完善的，也知道怎么样去借鉴他山之石。
从这个阿尔法 gpt里面的这报告相当于蒸馏他的一个一个想法啊。
这个这个在前期一开始搭基建的时候确实是很有必要的一个措施。

**发言人 1  00:33:57**
呃然后。我注意到咱们在最终生成法律服务意见书的时候...

Unrecognized formats(keep the original text):

• "Speaker 1:" without a timestamp → keep as body text
• "Speaker A:" → keep as body text
• Plain text with no speaker markers → treat the entire passage as body text

---

Phase 2: Recognition

Step 2.1: Recognize the file structure

Read through the raw transcript and identify the organizational method:

• Chunked by speaker + timestamp(e.g. **发言人 1 00:33:09**) — most ASR output
• Free-form paragraphs(no explicit chunking)
• Mixed(headings + paragraphs + quotes)

Purpose of recognition: to decide whether to merge consecutive utterances by the same speaker during Phase 4 polishing.Do not rewrite the chunk structure, keep it as is.

Step 2.2: Read through to identify high-confidence mistranscriptions

Must read the full text completely, scanning from the Agent's perspective.Do not list a static error table—ASR errors are endless (case drift, spacing, missing words, misalignment, homophones, similar-looking characters, word-break reconnection, syllable merging…), and any preset list will miss cases.

Core principle：

Only when the context clearly points to a certain dictionary term, replace the approximate mistranscription with that term. In ambiguous or low-confidence scenarios, keep the original text and do not make speculative replacements.

High-frequency error-prone categories to start scanning(not an error table, but starting points for judgment):

1. Personal names: whether the names of lawyers, parties, and witnesses appear for the first time + whether subsequent references are consistent
2. English product/tool/platform names: whether they appear in scenarios such as tool usage, command line, platform introduction, etc.
3. Institution/event/brand names: bar association, youth training camp, training camp, competition problem
4. Legal terms with homophones/similar forms: 代理 vs 带理, 抵押 vs 抵压, 知情 vs 至清
5. Numbers/units/timestamps: 1/7, 0/6, mixed use of Chinese and English commas;conservative principle

Form drift recognition(reference but not exhaustive):

• Case drift (WorkBuddy vs workbuddy vs WORKBUDDY)
• Spacing drift (work body / Work Buddy)
• Hyphens (Claude-code / Claude-Code)
• Split recognized as Chinese ("克劳德 code")
• Missing/leftover characters ("body" left in "让，如果 body帮我们")
• Homophones/similar-looking characters (analogous to "张律师 / 张老师 / 章律师")
• Word-break reconnection ("然后让" split into "让，如果")

Prohibited：

• Matching the list only with grep/regex (inevitably misses) — see §"Working Mechanism" for why it is expanded by judging each occurrence
• "Stylistic" rewrites with no clear correspondence, such as changing "我" to "我们"
• Replacing terms outside the dictionary
• Forcibly completing sentences that "look like they are missing characters" — unless it can be determined to be a combination error

---

Phase 3: Correction (enabled by default)

The three Steps of Phase 3 modifythree different types of objects— Step 3.1 changes characters (semantics), Step 3.2 changes whitespace (format), Step 3.3 deletes characters (language characters). The three types of operations are each independent, can be audited separately, and can be logged separately.

Step 3.1: Dictionary-based unified replacement

For the high-confidence mistranscriptions identified in Step 2.2:

1. Triple confirmation：
   • There is a corresponding target value in the dictionary
   • The context clearly points to the object represented by that target value
   • Evidence of formal drift holds (case/space/hyphen/missing character/homophone/similar-looking/word-break)
2. If any of the three is not satisfied → do not replace, keep the original text
3. After replacement is complete, record in correction_log.md:{原文} → {改后}, and annotate the line number and context fragment
4. Never modify the original file, all output is written to a new file under archive/

Step 3.2: Basic whitespace cleanup (enabled by default, lossless)

Why it is independent of Phase 4 polishing: Basic whitespace cleanup is "format standardization"; it does not change the semantics of the original text and does not delete any information; it is different in nature from the "style adjustment" of Phase 4 speaker merging / punctuation normalization / paragraph splitting, so it is enabled by default (the user does not need to make a switch decision for this).

Cleanup action list(only the following five categories are done, and nothing beyond this scope is done):

Category	Action	Trigger condition
Leading/trailing whitespace	Delete	Any line
Consecutive blank lines	Compress to a single blank line	Any position
Full-width/half-width spaces	Unify to half-width spaces	Appearing between English words or beside English punctuation
Broken spaces inside proper names	Merge	The context clearly points to a proper name in the dictionary (e.g. "Work Buddy" → "WorkBuddy")
Chinese numeral + space + 级/章/节	Merge	Pattern:[一二三四五六七八九十百千]+ +级/章/节 merged into [一二...]+级/章/节(e.g. "二 级" → "二级")

Whitespace rules around punctuation：

• Chinese punctuation ，。、；：？！""''「」（） no spaces before or after (delete if present)
• English punctuation , . ; : ? ! " ' ( ) one space after (retained in Chinese paragraphs)
• Half-width spaces sandwiched between Chinese → delete

Safe execution (avoid cross-segment swallowing): This step's cleanup of "extra spaces around Chinese punctuation" has a structural trap—the boundary of a speaker block (**说话人 N HH:MM:SS** + content + blank line + next block heading) depends on the sequence "content-ending punctuation → line break → blank line". If the cleanup regex uses \s+ to also consume the line break + blank line after the punctuation into a single space, it will swallow across blocks, and speaker headings, H2 headings, and speaker blocks will all be merged into a single line. During execution,process line by line, prohibit cross-line matching \s+, and only perform "in-line" actions (trailing spaces, within the same sentence X， Y → X，Y). If cross-paragraph cleanup must be done, diagnose it separately first before deciding.

Strictly do not(avoid going out of bounds):

• Do not delete any text, punctuation, letters, or numbers
• Do not change paragraph structure (do not merge paragraphs, do not split paragraphs—this is the scope of Phase 4)
• Do not modify numbers, timestamps, amounts, or dates
• Do not change speaker block markers (such as **发言人 1 00:33:09**）
• Do not reorder, reorganize, or summarize

Relationship with Step 3.1: Basic whitespace cleanup is performed after the Step 3.1 dictionary replacement; when encountering proper-name merges like "Work Buddy" → "WorkBuddy", prioritize the Step 3.1 (dictionary replacement) path, and Step 3.2 only performs "pure formatting" cleanup that has no dictionary target and is not covered by Step 3.1.

Proofreading log recording: All cleanup actions of Step 3.2 are also written to correction_log.md, recorded together in the "Basic Whitespace Cleanup" subsection (distinguished from Step 3.1 high-confidence replacements) for auditability.

Step 3.3: Spoken-word trimming (enabled by default, AI contextual judgment)

Why it is independent of Phase 4 polishing: It is the same in nature as Step 3.2 basic whitespace cleanup—it belongs to the category of "reads correctly" and does not change the original meaning (spoken words carry no information); it differs in nature from the "style adjustment" of Phase 4 speaker merging / punctuation normalization / paragraph splitting, so it is enabled by default (the user does not need to make a toggle decision for this).

Whitelist (pure filler words that can be deleted)—When the AI reads through, it identifies "as a filler word vs. as substantive"; only delete those that appear independently and carry no semantic burden:

Word	Typical position	Deletion condition
呃	Standalone in the middle of a paragraph / at the start of a sentence	Cognitive pause, does not constitute an answer
啊	Standalone in the middle of a paragraph / at the end of a sentence	Exclamatory pause
哦	Standalone in the middle of a paragraph	Transitional pause (not as a "got it" response)
哎	Standalone in the middle of a paragraph	Transitional pause
那个	Used standalone	Pure referential filler (does not refer to a specific noun)
就是说	Used standalone	Pure connective filler
然后呢	End of paragraph	Pure transitional filler
对吧	End of paragraph	Pure rhetorical-question filler
你知道吗	Middle of paragraph	Pure lead-in filler
怎么说呢	Middle of paragraph	Pure thinking filler
Like this	used independently	Pure summary filler
Actually	paragraph start	Pure transition filler
But	paragraph start	Pure transition filler

Retention rules(do not delete):

• Stance markers: "mm"/"right"/"yes"/"no"/"okay"/"is" used as affirmation / negation / response → retain (deleting would lose the speaker's stance)
• Logical connectors: "then" used as a logical connector ("first A then B") → retain (deleting would break the temporal sequence)
• Cognitive pause followed by complete content: "uh... how should I explain this" — retain the whole passage; although "uh" is on the whitelist, "cognitive pause + complete content" is a true record of the speaker's thought process, and retaining the whole passage respects the original more than deleting word by word
• Tone pause at the end of a paragraph("mm"/"ah"/"uh" appearing at the end of a paragraph) — retain (marks the closing of the speaking rhythm)
• Immediately adjacent to a key noun / verb— retain (may be speaker emphasis)
• Content words(nouns / verbs / adjectives / adverbs) — never delete

Paragraph start vs paragraph end vs mid-paragraph decision tree：

Position	Judgment criterion	Handling (from v2 aggressive version onward)
Paragraph start	Immediately following **发言人 X HH:MM:SS** the first word of the first non-empty line after it	Delete(aggressive from v2 onward)
Mid-paragraph standalone	Mid-sentence position, not immediately adjacent to a key noun/verb	Delete
Mid-paragraph parallel pause ah	Between two nouns/gerunds + enumeration comma/comma	Retain(deleting would break the parallel structure)
Paragraph end	The last word at the end of a passage of content	Retain(marks the closing of the rhythm)

See references/correction_patterns.md §11 for the recognition pattern of mid-paragraph parallel pause ah.

Judgment principles：

• Follow the same "read the full text + triple confirmation" approach as Step 3.1
• Triple confirmation: ① whether the word in the current context belongs to a whitelisted word class; ② whether it is used independently at the current position and carries substantive meaning; ③ whether deleting it would not break the speaker's stance / temporal sequence / emphasis
• If any is not satisfied → do not delete, retain the original text
• In ambiguous or low-confidence scenarios, always retain the original text

Strictly do not(to avoid overstepping):

• Do not delete whole sentences or paragraphs
• Do not delete content words (even if repeated)
• Do not delete key information (numbers, names, proper nouns, terminology)
• Do not rewrite into written language, do not complete, do not change the tone
• Do not delete versions where "uh / ah" serves as a cognitive pause followed by complete content
• Do not delete key rhythm markers at "paragraph end" (from v2 aggressive version onward, paragraph-start rhythm markers are deleted by default)

Proofreading log record: write all Step 3.3 simplification actions to correction_log.md 's "Colloquial Word Reduction" subsection, format:

| 行号 | 原文片段 | 被删词 | 理由 |
|------|----------|--------|------|
| L207 | "呃 这个怎么说呢，我们今天来" | "呃" | 段首认知停顿，后接"怎么说呢"+完整内容，整段保留——本行不删（认知停顿后接完整内容的"呃"按 §3.3 保留规则例外）|
| L312 | "对，所以呢，我们" | "所以呢" | "所以呢" 不在白名单，保留 |
| L451 | "然后呢我们看一下" | "然后呢" | 段首过渡填充，可删 |

Relationship with Step 3.2: Step 3.2 modifies whitespace characters, Step 3.3 modifies language characters. Both are "reads correctly" operations, both are enabled by default, and both are recorded together in a separate subsection of correction_log.md.

Mandatory check (to prevent skipping an entire section): After running, a grep self-check is mandatory (see references/correction_patterns.md §12）：

• correction_log.md must include the ## 口语词精简 subsection
• correction_log.md must include the ## 高置信替换 / ## 基础空白清理 / ## 口语词精简 / ## 未处理 four subsections
• meta.json must contain the summary / process_time / dictionary_source / polish_enabled field
• v1.0.2 skipped the entire Step 3.3 section with no log—this mandatory check item is the retrospective product of that bug

---

Phase 4: Polishing (optional, determined by config switches)

All Steps under Phase 4 are determined by switches in the config/config.env configuration file. Source of each Step's default value:

• Missing config.env: use the value of config.env.example (i.e., the default value)
• Missing config.env.example: use the default value from this section's quick reference table

Step	Category	Action	Boundary	Config switch	Default value
Step 4.1	Speaker merging	When the same speaker has multiple consecutive paragraphs that can be merged into one, merge them	Only deduplicate chunks,do not delete any original words	POLISH_MERGE_SPEAKERS	true
Step 4.2	Punctuation normalization	Unify Chinese and English punctuation, complete sentence endings	Do not change modal particles, do not delete natural speech flow markers such as "uh/ah"	POLISH_PUNCTUATION	true
Step 4.3	Paragraph splitting	Split extremely long paragraphs (>500 characters) at semantic boundaries	Do not reorganize, do not reorder, do not summarize	POLISH_PARAGRAPH_SPLIT	true
Step 4.4	Topic-based chaptering + H2 headings	Insert at clear topic switch points ## 一、标题 lines (with Chinese uppercase numbering)	Insert only at switch points,do not reorganize content, do not rewrite, do not summarize	POLISH_TOPIC_SECTION	true
Step 4.5	Meeting minutes / summary	"Chapter summary" + "Key insights" for each chapterEmbedded in place under the corresponding H2 heading; one line each for the main title at the beginning and keywords at the end	Do not introduce new facts, do not re-split H2, do not evaluate, do not create a separate top aggregation block	POLISH_SUMMARY	true

Step 4.4: Topic-based chaptering + H2 heading insertion (enabled by default)

Trigger condition: When the topic clearly switches (different discussion object / different agenda / different subject focus), insert ## 一、标题 lines; sub-switches within the same topicdo notinsert.

Identification principles：

• Hard switch signal: Both parties repeatedly return to the same object → suddenly discuss another object (e.g., "tools → law firm management", "product → customer relationships", "code → knowledge base") → insert H2
• Soft switch signal: It is merely a follow-up question or deepening (e.g., "Tool A → details of Tool A") → do not insert
• Do not force coverage of the entire text: Opening pleasantries / transitional small talk in the middle / closing wrap-up → do not force H2 insertion; let them fall under the first/last H2

Anchor positioning process (to avoid line number drift): H2 anchors must be based on structural markers in converted.md (**说话人 N HH:MM:SS** or Yang Weixin's line) actual line number,Do not guess line numbers from an earlier reading impression of the upstream raw file—there is a metadata block offset between raw and converted (the first few lines wrapped in Phase 1.2), and the line numbers counted by eye from raw often differ by a few lines from the real line numbers scanned by the script, causing H2 to be inserted into the wrong section.First write a 5-line scan script to print the real line numbers of all speaker lines in converted.md, then use that to fill in the H2 anchor table; after insertion, spot-check by "## heading line + the following 5 lines" to confirm it lands in the correct section.

Where does the heading text come from：

• Do notfabricate headings—the agent extracts a 3-10 character topic term from the context of that passage (e.g., "tool selection and daily use", "local deployment and anonymization", "knowledge base maintenance")
• The heading text shouldnot duplicate speaker names, timestamps, or proper nouns—to avoid confusion with the original text
• When the same topic term is used for multiple H2s within the same passage, deduplicate

Numbering rules：

• All H2 headings in the document are numbered in order of appearance with Chinese uppercase numerals:一、、二、、三、...
• Between the number and the heading text use 、 an enumeration comma as separator (standard Chinese formal typesetting convention):## 一、工具选择与日常使用
• Numbers are sequential, with no skipped numbers; if an insertion is later found necessary, the agent renumbers sequentially (leaving no gaps)
• Within the same corrected.md , numbers are unique and not repeated

Strictly do not：

• Do not reorganize the order of content
• Do not rewrite any body text
• Do not summarize or distill (the heading text is only an extraction of what that passage already says, introducing no new information)
• Do not add H3 / H4 (this skill only goes to the H2 level)
• Do not split a single topic to add an H2 (even if that topic spans 1000 characters)

Proofreading log record: all Step 4.4 insertions are written to correction_log.md 's "topic chaptering" subsection (distinct from Step 4.1/4.2/4.3), format:

| 行号 | 标题文本 | 上下文锚点（前后 50 字）| 切换类型 |
|------|----------|------------------------|----------|
| L487 | ## 律所管理与本地部署 | "...他就不会愿意去做这个事事情。" | 硬切换 |

Relationship to other Steps in Phase 4: Step 4.1-4.3 are "style adjustment", Step 4.4 is "structural annotation"—the former changes the chunk form, the latter only inserts anchors,does not reorder。

Why this skill does this rather than the downstream: the early version of original §1.2 said "handle it later when the downstream does chapter reorganization", but downstream skills (such as course-generator) do "generate a course based on the transcript", which is a different task from "faithfully annotating the structure of the original words". H2 topic chaptering is "faithful annotation", so it fits better in this skill.

Step 4.5: Meeting minutes / summary generation (per POLISH_SUMMARY switch)

Trigger conditions：

• Configuration switch POLISH_SUMMARY=true, or the user explicitly declares it at invocation ("generate minutes" / "summary" / "AI insights")
• Step 4.4 must have already run first—without H2 boundaries there is no "by chapter" granularity

Core principle (v1.4 revision: summaries embedded in place, not aggregated at the top)：

• Each chapter's "chapter summary + key insights"is written directly under the corresponding H2 heading and before that chapter's original body text—no separate top aggregation block
• Do not use <!-- AI-SUMMARY --> markers, and do not produce a standalone block where "all chapter summaries are gathered together"
• Document-level meta-information (main title, keywords) each occupy only one line, placed lightly at the beginning / end of the document, and not mixed and aggregated with the per-chapter summaries

Output Location：

• Modify corrected.md: ① Add a one-line main title under the H1 at the beginning; ② Embed a chapter summary + key insights in place under each H2 heading; ③ Add a one-line keyword list at the end
• Do not create a separate _summary.md, do not write markers
• The source file directory mirror is kept in sync with corrected.md

In-place Embedding Format(under each H2):

## 一、章节名（Step 4.4 标题，原样）

**本章摘要**：50-100 字概括本章节核心内容（引用原话中的具体事实/数字/专有名，不引入新事实，不评价）

**关键洞察**：
- 洞察 1（15-30 字，横向观察本章节）
- 洞察 2

**发言人 1  00:02:09**
（该章原话正文，全部保留，紧跟在摘要 / 洞察之后）
...

Main Title at the Beginning / Keywords at the End：

• Beginning: Under the H1 title, before the first H2, write the main title on a single line:**主标题**：5-15 字概括全文核心议题
• End: After the last H2 chapter's original text, write the keywords on a single line:**关键词**：词1, 词2, ...（5-8 个，逗号分隔）
• Each occupies one line, is not expanded into a block, and is not aggregated with the per-chapter summaries

Why Change to In-place Embedding (v1.4)：

• The top aggregation block piles all chapter summaries in one place, so when readers want to see an overview while reading a chapter in the body they have to scroll back to the top to compare—summaries are separated from the body text
• In-place embedding keeps "summary / insights" right next to the original text it summarizes, making each chapter self-contained and smoother for reading and later reuse (such as extracting course chapters)
• The main title / keywords are retained as single-line document-wide metadata, not lost, but no longer aggregated into a block

Generation Principles：

1. Main Title(single line at the beginning): Extract 5-15 characters of subject terms from the most core topic of the full text
2. Per-chapter Summary: One-to-one correspondence with the H2 of Step 4.4（Do not re-split topics）
   • Length: 50-100 characters
   • Cite specific facts/numbers/proper nouns from the original text (do not abstract them)
   • Do not introduce facts outside the original text
   • Do not evaluate (unless supported by the original text)
   • Summarize closely based on this chapter's original text, do not cross chapters
3. Per-chapter Key Insights: 2-3 per chapter (2 if the passage is short)
   • Length: 15-30 characters each
   • Derived from a horizontal synthesis of this chapter, not from a single paragraph
   • Do not use evaluative tones such as "should" "must" "recommend"
   • In forms such as "Group X shows trend Y", "A gap Z exists between X and Y"
4. Keywords(single line at the end):
   • Quantity: 5-8
   • Source: Nouns/product names/concept words that appear repeatedly or are distinctive in the original text
   • Format: One line separated by commas

Strictly Do Not：

• Do not introduce facts outside the original text
• Do not re-split H2 boundaries (per-chapter summaries must correspond one-to-one with the original H2s)
• Do not evaluate (unless clearly supported by the original text)
• Do not set up an additional top ## AI 摘要 aggregation block, do not write <!-- AI-SUMMARY --> markers
• Do not add H3 / H4 under H2 to wrap summaries (summaries / insights use bold label lines, do not upgrade the heading level)
• Do not write "action items / resolutions / follow-up TODOs" (unless explicitly mentioned in the original text)

Boundary with Step 4.4：

	Step 4.4	Step 4.5
Output File	corrected.md (modify)	corrected.md (modify, in-place embedding)
Operation	Insert H2 markers before the original text chapters	Embed summaries / insights under each H2 heading and before the original text; one line each for the main title at the beginning and keywords at the end
Retain Original Text	Retain all	Keep all original wording + quoted fragments in the summary
Introduce new information	Not allowed	Not allowed

Idempotency and Verification：

• On a re-run, replace in place each "Chapter Summary / Key Insights" block under H2, the main title line at the beginning of the document, and the keyword line at the end of the document
• After the run, verify: ① under each ^## second-level heading, there is immediately a **本章摘要** line; ② the full text contains no <!-- AI-SUMMARY wording; ③ the main title / keywords each exist as one line
• Verify that the total byte count of the summary is > 200 (to prevent empty summaries)

Proofreading Log Recording: The output of Step 4.5 is written to correction_log.md the "Meeting Minutes" subsection, format:

| 字段 | 值 |
|------|-----|
| 主标题（文首单行）| 主标题文本 |
| 章节数 | 8（与 Step 4.4 H2 一致）|
| 总洞察数 | X 条 |
| 摘要字数总计 | Y 字 |
| 关键词（文末单行）| 词1, 词2, ... |
| 嵌入方式 | 就地嵌入每个 H2 之下；无顶部聚合块；无 markers |

---

Phase 4 Overall Boundaries(applies to Step 4.1-4.4):

• Rewrite into written language
• Summarize, distill, and delete "verbose" content (Step 4.5 is the only exception—it explicitly does "summary + insights")
• Complete or infer the speaker's intent
• Change facts, change numbers, change timestamps

---

Phase 5: Output

Output adopts a dual-write strategy: the main archive is inside the skill, and an easily accessible copy is synchronized in the source file directory. The original file remains untouched.

Step 5.1: Main Archive (required)

Output location:{skill 目录}/archive/{YYYYMMDD_HHMMSS}_{原文件 basename}/

Files:

• {原文件}_corrected.md — the complete corrected text (retaining the original chunk structure)
• {原文件}_polished.md — generated only when the user enables polishing
• correction_log.md — the proofreading comparison log
• meta.json — processing time, dictionary source, whether polished, original file path

Step 5.2: Source File Directory Mirror (required)

Output location: the directory where the original file is located (same directory as the original file).

Files:

• {原文件 basename}_corrected.md — exactly the same content as 5.1, only an easily accessible copy
• Naming rule: append _corrected suffix after the original file name, and change the extension to .md(when the original file is .md , the output is still .md; when the original file is .txt , the output is .md）

Why Dual-Write：

• The main archive bears the complete archival responsibility of "traceability + proofreading log + metadata"
• The source file directory copy lets users directly see the "proofread version" in their everyday file manager, eliminating the need to dig through the skill's internal directory every time
• The content of the dual write is byte-level identical _corrected.md(the polished copy and log are not mirrored—their main archive location is inside the skill)

Conflict Handling：

• A file with the same name already exists in the source file directory _corrected.md → distinguish with a timestamp suffix (_corrected_20260608_153022.md), to avoid overwriting historical proofreading results
• Source file directory is read-only / not writable → silently skip the source file directory mirror, output only the main archive; in meta.json record source_mirror: "skipped"
• The source file path cannot be resolved (such as stdin input) → likewise silently skip the source file directory mirror

The original file remains untouched—the dual-write strategy only generates "new files" and never modifies the original file in place.

Step 5.3: Stable Version Marking (optional)

When a certain run's _corrected.md has been confirmed by the user to be problem-free and is regarded as the "stable version" of that transcript, add under that archive subdirectory STABLE.md Marked file:

# Stable Version Marker

**v3 (2026-06-08 12:00) 标记为该转录稿的稳定版本。**

## 为什么 v3 是 stable

- v1.0.0 (2026-06-07 14:30) — 7 处，仅 Step 3
- v1.0.2 (2026-06-08 00:41) — 42 处，Step 3 + 3.5，漏跑 Step 3.6
- v2 (2026-06-08 11:00) — 170 处，补跑 Step 3.6（84 处）
- v3 (2026-06-08 12:00) — 226 处，激进版段首删除（+52 处）

## 锁定本版本

- 后续不再对 `260606_AI技能创新大赛_corrected.md`（v3）做改动
- 源文件目录三个版本并列保留供对比
- 如发现新的误转写需要补判，新建 `archive/<新时间戳>_*` 目录重跑，不就地修改 v3

Why STABLE.md is needed：

• The archive directory accumulates artifacts from multiple rounds of iteration (v1.0.0 / v1.0.2 / v2 / v3 ...), and future agents / users / downstream skills coming in won't know which one is the final version
• Mirror files of the source file directory (_corrected_v3_20260608_120000.md) are named by timestamp, which itself is a "stable" hint, but inside archive, files 260606_AI技能创新大赛_corrected.md without a STABLE marker will be mistaken for the "latest version"
• STABLE.md makes "which one is the final version" explicitly checkable

When not to write STABLE.md：

• One-off trial runs, user hasn't confirmed / small proofreading volume / the transcript itself still needs further processing—no need to force a marker
• A newer version is already stable—avoid adding STABLE to an old version and misleading downstream

Step 5.4: Old version cleanup strategy

The archive directory retains the full artifacts of each run (main archive + correction_log + meta.json) and does not proactively clean up historical versions. But when the number of subdirectories under archive is ≥ 5, it is recommended to note the retention strategy in STABLE.md / DECISIONS.md:

• Keep: each run's _corrected.md / correction_log.md / meta.json(records the complete iteration trajectory)
• Can clean up: when archive accumulates ≥ 5 directories, old analysis_report.md and other intermediate artifacts can be manually archived
• Do not clean up: the _corrected.mdof the stable version directory marked by STABLE.md (the user may need to retrieve the final version from a path other than the source file directory mirror)

Step 5.5: Structural regression mandatory check (must be run before Phase 5 delivery)

The mandatory grep check gating the "missed chapter" type bug is already written at the end of Step 3.3; what is added here is the physical structure regression for "ran but ran wrong"—the two failure modes, Step 3.2 cross-segment swallowing (speaker blocks and H2 headings being glued together by cross-segment regex) and Step 4.4 line number drift (H2 inserted into the wrong chapter), have already been written into the "Safe Execution" section of Step 3.2 and the "Anchor Positioning Workflow" section of Step 4.4 respectively. This step only does on-the-ground spot checks, explicitly locking down "whether these two types of regression actually occurred."

Spot check items(if any fails, this batch is considered incomplete and no completion credential may be issued):

1. Speaker block counts match: In the corrected _corrected.md , the total number of speaker marker lines for ^\*\*说话人 \d+ \d+:\d+(?::\d+)?\*\* and ^杨卫薪 \d+:\d+(?::\d+)? should equal or be approximately the total in converted.md (a difference of ≤ 1 is normal due to merging of the final speaker block). If the total shrinks significantly (e.g., 96 blocks → 60 blocks), it means Step 3.2 cross-segment swallowing consumed content.
2. Each speaker block's first line is non-empty and contains readable content: Extract the first non-empty line of text from each speaker block in _corrected.md ; the length should be ≥ 5 characters; if it becomes shorter (e.g., "可以听到。" is only 4 characters), it means the previous block was swallowed.
3. H2 anchor 5-line lookback: Within the 5 lines immediately following each ^## (一|二|三|四|五|六|七|八|九|十)、 , the first line of a speaker block should appear (**说话人** / 杨卫薪); if not found, the chapter positioning is misaligned.
4. Main title and keyword line exist：_corrected.md Within the last ≤ 5 lines there should be ^\*\*关键词\*\*：...; after the opening metadata block and before the first H2 there should be ^\*\*主标题\*\*：...。

Execution suggestion: write the above as a 5-10 line script (the script file does not need to be persisted), and after running it print four lines of PASS/FAIL; if any FAILs, troubleshoot against the boundary sections of Step 3.2 / Step 4.4, and do not let it pass by visual inspection.

Why this step is independent of the existing mandatory grep check: The grep check at the end of Step 3.3 checks whether "the log sections are complete"—it checks for the existence of logs, not the physical form of the artifacts. This step checks whether the artifacts themselves have structural damage. The two cover orthogonal failure modes, and neither can be omitted.

Patch / write_file input errors must be fixed (Type 1 failure mode): The above spot checks address "ran but ran wrong" at the structural level. There is also a category ofliteral input errors——patch tool's old_string / new_string input typos (such as entering 排障 mistakenly as 排排); the old string may match multiple places or be partially matched in the text, and the diff tool will show "successfully replaced," but a typo was actually written.All patch calls' diff output must be reviewed word by word before being pasted back—especially in scenarios with long files, many characters, or similar words/characters (such as 排排/排障/排序/排除);write_file when overwriting an entire file, perform a "copy 5-line snippet and read it back" check on the finished product to verify the written content matches expectations. Both types of failure are "unverified success."

Proofreading comparison log format (correction_log.md)

# 校对对照日志

- **原始文件**：/path/to/raw.md
- **处理时间**：2026-06-07 14:30:22
- **词典来源**：`config/user_dictionary.yaml`（含 18 项术语）
- **润色开关**：关闭

## 高置信替换

| 原文 | 改后 | 出现次数 | 上下文示例 |
|------|------|----------|------------|
| workbody | WorkBuddy | 3 | "通过第二版呢进行测试..." |
| work body | WorkBuddy | 2 | "我们把这个实践中办案..." |
| claude-code | Claude Code | 1 | "...重新调回那个 claude-code 里面..." |

## 未处理（保留原文）

- "智能件" — 上下文不足以判断是否为"智能体"
- "代理" — 同上

## 润色变更（如开启）

- 合并发言人 1 连续 3 段为 1 段
- ...

Applicable scenarios / Not applicable

See references/scope.md。

Configuration example / Configuration decoupling principles

See references/config-decoupling.md。

Reference documents

• references/scope.md — Overview / Applicable boundaries
• references/config-decoupling.md — Configuration example / Configuration decoupling principles (evaluation-spec related)
• references/first_use.md — One-time configuration guide (copy example.yaml, run a trial run, multi-user symlink)
• references/correction_patterns.md — Workflow judgment criteria (mis-transcription identification, colloquial word reduction, parallel pauses, mandatory check list, ASR high-frequency patterns)
• config/user_dictionary.example.yaml — Dictionary public template