wantsong
/
skills-vault
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
skills-vault/docs/superpowers/plans/2026-06-16-repair-markdown-...

2.6 KiB
Raw Blame History

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.