Thesis Citation Extract

Thesis Citation Extract Skill

Tự động extract [N] citation keys từ thesis chapter markdown + verify chéo với canonical bibliography (documents/<thesis-dir>/references/bibliography.md) theo IEEE format. Phát hiện 2 loại orphan: broken refs (cite trong body nhưng không có entry) + dead weight (entry trong bib nhưng không được cite). Output JSON cache vào data/last-run.json để track delta giữa các lần audit.

Khi nào dùng

• Trước khi flip documents/<thesis-dir>/** chapter PR sang DONE
• Audit thesis V1/V2/V3 trước defense GVHD/GVPB
• Thesis closure sub-task — verify cite hygiene
• Phát hiện citation drift sau khi user thêm/sửa bibliography

Quy trình (≈3 phút)

1. Extract — chạy bash scripts/extract-citations.sh <chapter-files...> → output filename:line:cite_key cho mọi [N] / [N, M] / [N]–[M] trong body. Range expand thành cá nhân ([5]–[7] → 5, 6, 7); danh sách [1, 4, 9] tách 1+4+9.
2. Verify — chạy bash scripts/verify-citations.sh <chapter-files...> <bibliography-path> → so sánh tập cite (body) vs tập entry (bib). Output 3 nhóm + báo cáo summary stdout + ghi JSON cache vào data/last-run.json.
3. Interpret — đọc summary:
   • ✅ matched: N — cite có entry, OK
   • ⚠️ orphan-body: N — cite trong body nhưng KHÔNG có entry bib → broken reference (fix bib hoặc xóa cite)
   • ⚠️ orphan-bib: N — entry trong bib nhưng KHÔNG được cite → dead weight (xóa entry hoặc thêm cite trong body)
4. Self-test — bash scripts/self-test.sh validate logic trên 3 fixture (good / bad-orphan-body / bad-orphan-bib).

Skill contents

• reference/ieee-citation-rules.md — quy ước IEEE in-text + bibliography flat list format (project canonical)
• reference/orphan-detection.md — định nghĩa 2 loại orphan + decision tree fix
• scripts/extract-citations.sh — parser regex \[[0-9]+\] với range expansion
• scripts/verify-citations.sh — set-diff body cites vs bibliography entries
• scripts/self-test.sh — synthetic fixtures verify extract + verify logic
• data/last-run.json — cache lần verify gần nhất (delta tracking, generated at runtime)

Gotchas

• Bibliography flat list — recommended convention: bibliography renumbered sang single sequential [1]...[N] flat (NOT per-chapter sections). Section headings ## Chapter N chỉ là grouping cho reader; cite key độc lập section.
• Range expansion — [5]–[7] dùng em-dash – (U+2013), KHÔNG phải hyphen -. Parser support cả 2 (em-dash + hyphen) để phòng typo.
• List separator — [1, 2] dùng comma + space; parser tolerate [1,2] (no space) và [1 ,2] (trailing space).
• Code block exclusion — KHÔNG parse [N] trong code fence ``` (vd array[1] Java code). Parser skip lines giữa code fence markers.
• Markdown link false-positive — [text](url) link syntax có [] nhưng KHÔNG phải cite. Parser yêu cầu content trong [] PHẢI là số nguyên thuần (^[0-9]+$).
• Bibliography entry regex — entry line PHẢI bắt đầu chính xác [N] đầu line (không indent). Indent line bị skip vì có thể là continuation hoặc quote.
• Backup file scope — KHÔNG include chapter-*-backup-YYYY-MM-DD.md trong verify mặc định. Backup là snapshot, không phản ánh current cite state.
• Out of scope: scope của skill này — chỉ extract + verify, KHÔNG sửa source. Người dùng tự fix (sửa bib hoặc body) sau khi nhìn report.
• Adapt to your project's path layout — default documents/<thesis-dir>/references/bibliography.md. Adjust scripts/args nếu layout khác (vd thesis/references/).

Related

• documents/<thesis-dir>/references/bibliography.md — canonical bibliography (flat IEEE list)
• documents/<thesis-dir>/references/CITATION-STYLE.md — IEEE format spec (in-text + entry templates) [recommended companion doc]
• .claude/rules/skill-conventions.md — skill structure mandate
• .claude/rules/thesis-content-standard.md C3 Bibliography category — this skill closes C3 audit gap (100% inline cite utilization + orphan detection)
• Sister skill: quality/thesis-figure-curation/SKILL.md (closes C7 Diagram + figure rendering category)