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: default to lightweight in-place repair that overwrites the source Markdown without sidecar files; use audit mode only when the caller asks for preserved originals, fixed copies, heading maps, JSON plans, or 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`: `quick` or `audit`. Default to `quick`.
- `execution`: `auto`, `subagent`, `thread`, or `inline`. Default to `inline` for quick single-file work and `auto` for audit or large batches.
- `output_dir`: audit output folder. Ignore in quick mode unless the caller also asks for backup or reports.
- `backup`: `never`, `always`, or `auto`. Default to `never`; rely on git unless the caller asks for backups or the file is outside version control.

Example user-facing request:

```text
Use $fix-title with mode=artifact on C:\path\one.md
```

This defaults to quick mode and overwrites `C:\path\one.md` directly.

Audit example:

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

## Output Modes

### Quick

Use quick mode by default.

- Overwrite each source Markdown file in place.
- Do not write `heading-map.json`, `heading-plan.json`, `.fixed.md`, heading reports, or batch reports.
- Use in-memory edits and `scripts/semantic_heading_repair.py` helpers when practical.
- Return a concise summary with changed heading counts and skipped files.
- If a file is ambiguous, skip it and tell the caller why instead of creating audit artifacts by default.

Quick mode is for routine cleanup where the caller wants the document fixed, not a review package.

### Audit

Use audit mode only when the caller asks for auditability, preserved originals, fixed copies, maps, plans, reports, review evidence, batch reports, or no overwrite.

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."
}
```

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

## Execution Isolation

Quick single-file repairs should usually run inline. Prefer isolation only when semantic repair consumes significant context or the caller asks for it.

- `inline`: Use for quick mode and small files.
- `subagent`: Use when the host supports delegated agents and the batch is large or audit mode is requested.
- `thread`: Use when the host supports child/background threads and the user explicitly asks for Thread/sub-session execution.
- `auto`: Choose `thread` when explicitly requested, otherwise choose `subagent` for audit or large batches when available, otherwise `inline`.

## Delegation Prompt

For quick mode, send this shape to the isolated worker only when isolation is warranted:

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

Mode: <discussion|artifact>
Output: quick
Files:
- <absolute-path-1>
- <absolute-path-2>

Rules:
- Read and write source files as UTF-8.
- Overwrite each source Markdown file in place.
- Do not write heading-map, heading-plan, fixed-copy, heading-report, or batch-report files.
- Preserve non-heading content.
- Apply only deliberate heading-level edits.
- Flag ambiguous appended artifacts or uncertain heading relationships instead of silently making creative decisions.
- Return changed heading counts and skipped files.
```

For audit mode, send this shape:

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

Mode: <discussion|artifact>
Output: audit
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.

## 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_edits(source, edits, output, report=None, mode="quick")`
- `apply_edits_in_place(source, edits, mode="quick", report=None)`
- `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

- Quick mode overwrites the source file by default.
- Audit mode never overwrites the source file unless the caller explicitly asks for replacement after reviewing the fixed copy.
- 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
```