55 lines
2.6 KiB
Markdown
55 lines
2.6 KiB
Markdown
# 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 `citeturn34view0turn20search2` 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.
|