video-workbench/requirements/skills-vault/llm-markdown-intake-normalizer.md

LLM Markdown Intake Normalizer Skill Request

Status

Implemented for the first trial through the upgraded installed fix-title Skill on 2026-06-23.

Trial output:

projects/2026-06-23-在路上/intake-repair/fix-title-2026-06-23/

Notes:

• The raw intake/ Markdown files were repaired and then replaced after main-session review.
• Reports, heading maps, heading plans, fixed copies, and original backups were preserved under intake-repair/.
• This request remains as the project-side demand record and as evidence for any later generalization beyond fix-title.

Requesting Project

video-workbench

Needed Capability

Create a reusable Skill in skills-vault for normalizing raw LLM/GPT Markdown intake files before downstream project extraction.

This is not a general Markdown prettifier. The target use case is accepted planning output copied from GPT into a project intake/ folder. These files may contain useful planning content, but their heading hierarchy, conversational wrappers, repeated sections, and pasted multi-part structure can mislead later agents if used directly as execution source material.

Current Example

Project:

C:\Users\wangq\Documents\Codex\video-workbench\projects\2026-06-23-在路上

Raw intake folder:

projects/2026-06-23-在路上/intake/

Representative files:

第一轮策划工作总结.md
阶段三-MV 总纲.md
阶段四-通用表达与视觉系统设计.md
阶段四-人物锚点板策划说明.md
阶段四-人物锚点板页面结构建议稿.md
阶段四-风格锚点板页面结构建议稿.md
阶段五-镜头清单骨架.md
阶段五-核心单镜.md

Observed symptoms:

• Several files contain multiple top-level # headings that are not true document roots.
• Some files begin with conversational answer sections such as "先回答..." before the durable artifact begins.
• Some files include "下一步我可以..." style assistant transition text that should not become project truth.
• 阶段五-镜头清单骨架.md appears to include duplicated or appended material from multiple earlier outputs.
• Phase-level artifacts mix planning conclusions, draft page structures, execution suggestions, and assistant chatter.
• Direct extraction from these files risks treating GPT formatting accidents as canonical project structure.

Boundary

The Skill should normalize or produce a cleaned copy of raw intake material. It should not decide the project's execution plan, generate image prompts, create shot tasks, or rewrite creative decisions.

Expected source of truth relationship:

intake/ raw GPT Markdown
  -> cleaned intake / normalized Markdown
  -> Codex extraction into project.md, execution-plan.md, visual-system/, slides/

The original intake/ files must remain preserved unless the user explicitly asks for in-place rewriting.

Expected Workflow

The Skill should guide Codex to:

1. Treat the raw input file as an archived source, not as a directly executable document.
2. Inspect heading structure and report anomalies before extraction.
3. Produce a normalized output file or batch output in a separate location.
4. Preserve semantic content while demoting or labeling conversational scaffolding.
5. Avoid silently deleting creative decisions.
6. Produce a short cleaning report that records what changed and what remains ambiguous.

Possible output layout for a project:

projects/<project>/intake-clean/
  <same-file-name>.md
  intake-cleaning-report.md

Alternative output locations are acceptable if the Skill documents the convention.

Required Behaviors

Heading Repair

• Ensure each normalized Markdown file has one clear document title.
• Convert accidental top-level section headings into appropriate nested headings.
• Preserve fenced code blocks, tables, block quotes, and list indentation.
• Do not mechanically add the same heading level to every heading when the source contains mixed artifact boundaries.

Conversational Wrapper Handling

Classify assistant chatter instead of letting it masquerade as source truth.

Examples:

• "先回答你的问题"
• "如果你愿意，下一步我可以..."
• "你选一个，我再继续"
• "强哥，你的判断是对的"

The Skill may either remove these from the cleaned artifact or move them into a clearly labeled Non-Canonical Notes / Assistant Chatter section, depending on the selected mode.

Duplicate / Appended Artifact Detection

Detect likely appended outputs inside one file, especially when:

• a new artifact title appears halfway through the file;
• a summary document is pasted after a shot list;
• numbered top-level sections restart unexpectedly;
• the same named artifact appears in another intake file.

The Skill should not merge or deduplicate creatively without reporting the decision.

Canonicality Labels

The cleaned output should make it easy to tell:

• durable project decision;
• planning rationale;
• page or shot skeleton;
• candidate suggestion;
• assistant transition text;
• duplicate or appended material needing human review.

Exact labels can be chosen during implementation, but the distinction must be visible.

Batch Mode

The Skill should support cleaning a folder of Markdown files, because video projects usually import several GPT stage outputs at once.

Batch mode should produce:

• cleaned Markdown files;
• a report listing per-file anomalies;
• a list of files that require manual review before extraction.

Non-Goals

• Do not generate final image prompts.
• Do not extract project.md, execution-plan.md, visual-system.md, or slides.md.
• Do not make creative judgments about which shot, scene, or style rule is better.
• Do not overwrite original intake/ files by default.
• Do not require CCPE or formal participant invocation.

Suggested Skill Name

Preferred:

normalize-llm-markdown-intake

Acceptable alternatives:

clean-llm-markdown-intake
llm-intake-normalizer

The existing fix-title Skill is too narrow for this request. It can remain as a low-level heading-shift utility, but this request needs structure-aware intake normalization.

Suggested Tests

Use the real 在路上 intake files as manual or fixture samples, then add smaller deterministic fixtures for unit tests.

Minimum automated fixture cases:

1. A file with one true title and several accidental # section headings.
2. A file with assistant chatter before and after the durable artifact.
3. A file containing an appended second artifact with a repeated top-level title.
4. A file with headings inside fenced code blocks that must not be changed.
5. A batch folder where one file is clean, one is repairable, and one requires manual review.

Expected validation:

conda run -n skills-vault python -B -m unittest discover -s skills/<skill-name>/tests -v
conda run -n skills-vault python -B scripts/quick_validate.py skills/<skill-name>

After validation, install to:

C:\Users\wangq\.agents\skills\<skill-name>

Acceptance Criteria

The Skill is acceptable when a future Codex session can:

1. Read a raw GPT intake/ folder.
2. Produce normalized intake files without overwriting the originals.
3. Identify heading anomalies and duplicate/appended artifacts.
4. Label or remove assistant chatter according to a documented mode.
5. Produce a cleaning report.
6. Stop before execution extraction until the user confirms the cleaned intake is acceptable.

Why This Comes First

The current intake/ format can cause downstream misunderstanding. Extracting execution documents directly from raw GPT outputs may preserve accidental title hierarchy, duplicated pasted material, or assistant transition text as if it were project truth.

For the 2026-06-23-在路上 trial project, intake normalization should happen before creating the execution-state project skeleton.