# Repair Markdown Citations Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a reusable Skill that repairs ChatGPT/Deep Research Markdown citation tokens into Markdown footnotes using metadata keyed by turn IDs.

**Architecture:** Add a self-contained Skill under `skills/repair-markdown-citations`. The core behavior lives in a deterministic Python CLI; `SKILL.md` tells agents when to use it and how to handle exact metadata mapping versus fallback cleanup.

**Tech Stack:** Python standard library, `unittest`, Markdown text processing.

---

### Task 1: Tests First

**Files:**
- Create: `skills/repair-markdown-citations/tests/test_repair_markdown_citations.py`

- [ ] Write tests for token parsing, exact turn-ID replacement, deduplicated footnotes, fallback cleanup without metadata, and fenced code block safety.
- [ ] Run `python -m unittest discover -s skills/repair-markdown-citations/tests -v` and confirm the tests fail because the module does not exist yet.

### Task 2: CLI Implementation

**Files:**
- Create: `skills/repair-markdown-citations/scripts/repair_markdown_citations.py`

- [ ] Implement parsing for `citeturn34view0turn20search2` tokens.
- [ ] Build citation records from metadata keyed by refs such as `turn34view0`.
- [ ] Replace citation tokens outside fenced code blocks with first-use footnote markers.
- [ ] Append a fresh `## 参考资料` section with deduplicated footnote definitions.
- [ ] If metadata is unavailable or incomplete, remove citation tokens and append a warning note instead of fabricating footnotes.
- [ ] Support `--metadata`, `--output`, `--in-place`, and `--dry-run`.

### Task 3: Skill Package

**Files:**
- Create: `skills/repair-markdown-citations/SKILL.md`
- Create: `skills/repair-markdown-citations/README.md`
- Create: `skills/repair-markdown-citations/fixtures/README.md`

- [ ] Document the three capability levels.
- [ ] Make exact turn-ID mapping the required primary strategy.
- [ ] Document fallback behavior and safety rules.
- [ ] Keep the directory self-contained and lowercase kebab-case.

### Task 4: Verification

**Files:**
- Test: `skills/repair-markdown-citations/tests/test_repair_markdown_citations.py`
- Inspect: `skills/repair-markdown-citations/SKILL.md`

- [ ] Run the unit test command.
- [ ] Run a lightweight frontmatter/naming check.
- [ ] Run `git diff --check`.
- [ ] Inspect `git status --short` and summarize changed files.