skills-vault/skills/fix-title/SKILL.md

name

description

fix-title

Use when copied ChatGPT/LLM Markdown has semantically wrong heading hierarchy, especially discussion records with round headings and GPT reply blocks, or intake/artifact drafts with repeated accidental top-level headings. Agentic Markdown heading repair for one or more files: accept a file path array plus mode discussion or artifact, prefer subagent/thread isolation for large repairs, preserve originals, and produce fixed copies, heading plans, and reports.

Fix Title

Agentic Input

Use this skill from an agent prompt, not as a Python CLI.

Required inputs:

• files: one or more Markdown file paths.
• mode: discussion or artifact.

Optional inputs:

• output_dir: output folder. If omitted, use repo-local tmp/fix-title-output when available; otherwise use fix-title-output beside the first source file.
• execution: auto, subagent, thread, or inline. Default to auto.

Example user-facing request:

Use $fix-title with mode=artifact on:
- C:\path\one.md
- C:\path\two.md
Output to C:\path\tmp\fix-title-output

Execution Isolation

Prefer isolation because semantic repair consumes context and does not depend on the caller's broader conversation.

• subagent: Use when the host supports delegated agents. Pass only the skill path, input files, mode, output directory, and output contract.
• thread: Use when the host supports child/background threads and the user explicitly asks for Thread/sub-session isolation or the batch is large enough to risk bloating the main context.
• inline: Use only when no subagent/thread mechanism is available or the file is small.
• auto: Choose thread when explicitly requested, otherwise choose subagent when available, otherwise inline.

The caller must verify returned files and reports. Do not treat a subagent/thread message alone as proof of repair.

Delegation Prompt

Send this shape to the isolated worker:

Use $fix-title at <skill-path> to repair Markdown heading hierarchy.

Mode: <discussion|artifact>
Output directory: <output-dir>
Files:
- <absolute-path-1>
- <absolute-path-2>

Rules:
- Read source files as UTF-8.
- Do not overwrite originals.
- Preserve non-heading content.
- Build heading maps, write explicit JSON heading plans, apply only planned heading edits, and write reports.
- Return the fixed file, heading-map, heading-plan, and report paths for every input file.
- Flag ambiguous appended artifacts or uncertain heading relationships instead of silently making creative decisions.

For Codex specifically, use spawn_agent for subagent isolation. Use a Codex Thread only when the user requests thread/sub-session execution or host policy permits it for the current task.

Modes

Discussion

Use when a file records conversation rounds, such as # 1, # 2, ## 任务, ## 指令, ## GPT, or ## GPT的回复.

• Preserve outer record structure.
• Treat each GPT reply block as a child of its marker heading.
• Repair headings inside the GPT reply so top-level GPT content starts one level deeper than the GPT marker, usually ###.
• Repair descendants recursively by semantic relationship, not by raw hash count.

Example: under ## GPT, raw # 1.xxxx, raw # 2.xxx, and raw ## 3.xxx may all become ### when they are peer sections in the GPT reply.

Artifact

Use when copied GPT output is stored as a standalone planning/intake/artifact document.

• Treat the first visible # heading as the document title by default.
• Repair later accidental top-level headings under that root.
• Preserve one clear document title.
• If a later heading is actually an appended second artifact, do not silently merge it; mark it in the report for human review.

Example: after a root title, raw sibling headings # 1.xxxx, # 2.xxx, and ## 3.xxx may all become ## when they are peer sections.

Output Contract

For each source file, write:

<stem>.heading-map.json
<stem>.heading-plan.json
<stem>.fixed.md
<stem>.heading-report.md

For batch runs, also write:

fix-title-batch-report.md

The plan JSON is the audit boundary. Every changed heading must include:

{
  "line": 25,
  "from_level": 1,
  "to_level": 3,
  "reason": "This is a top-level section inside the GPT reply block under ## GPT."
}

Internal Helper

Use scripts/semantic_heading_repair.py only as an internal importable helper. It is not a user-facing CLI.

Useful helper API:

• inspect_payload(path)
• write_inspection(source, output, output_format="json")
• prepare_batch_scaffold(files, mode, output_dir)
• apply_plan(source, plan, output, report)

The helper protects fenced code blocks, quoted headings, and indented code. It does not make semantic decisions.

Repair Rules

• Never overwrite the source file unless the user explicitly asks for replacement.
• Do not mechanically add or subtract the same number of heading levels across a whole file.
• Do not change non-heading content.
• Do not change headings inside fenced code blocks, block quotes, or indented code.
• Do not treat Markdown numbering as decisive. ## 3.xxx can be a sibling of # 1.xxx when context shows they are peers.
• When a parent heading is repaired, re-evaluate descendants recursively.
• If unsure, preserve content and record the ambiguity in the report.

Validation

Run after editing this skill:

conda run -n skills-vault python -B -m unittest discover -s skills\fix-title\tests -v
conda run -n skills-vault python -B scripts\quick_validate.py skills\fix-title