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

---
name: fix-title
description: "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:

```text
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:

```text
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:

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

For batch runs, also write:

```text
fix-title-batch-report.md
```

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

```json
{
  "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:

```powershell
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
```