NSFC Ref Alignment

Collaboration Agreement with bensz-collect-bugs

When a bug caused by the design flaw of this skill occurs in the user's environment, prioritize using
```
bensz-collect-bugs
```
to record it in
```
~/.bensz-skills/bugs/
```
according to specifications. It is strictly forbidden to directly modify the source code of the skill installed in the user's local Claude Code / Codex.
If the AI can still complete the user's task through a workaround, it should first record the bug, then continue to complete the current task.
When the user explicitly requests actions such as "report bensz skills bugs", call the local
```
gh
```
and
```
bensz-collect-bugs
```
to upload only new bugs to
```
huangwb8/bensz-bugs
```
; do not pull / clone the entire bug repository.

Applicable Scenarios

You have an NSFC proposal (LaTeX project) and want to check:
- Whether all bibkeys cited in
```
.tex
```
  files via
```
\cite{...}
```
  /
```
\citep{...}
```
  /
```
\citet{...}
```
  etc. exist in
```
.bib
```
  files
- Whether the basic fields of
```
.bib
```
  entries are complete and the format is obviously incorrect (such as invalid DOI, missing year)
- Whether the "semantic claim" of the sentence where the citation is located matches the literature (at least from metadata such as title/author/year/venue/DOI), and whether there are risks of incorrect citation/overclaiming/misattribution
You want to only get a report for manual review first (modifying
```
.bib
```
/ revising the text is a major matter).

Inapplicable Scenarios

You want to "automatically replace bibkeys / automatically rewrite the text" — this skill prohibits direct modification by default (unless you explicitly request it).
You just want to complete BibTeX entries: prioritize using
```
nsfc-bib-manager
```
.

Input

```
project_root
```
: Root directory of the proposal project (e.g.,
```
projects/NSFC_General
```
)
Optional:
```
main_tex
```
: Main entry tex file (default
```
main.tex
```
)
Optional:
```
report_dir
```
: Report output directory (default
```
./references
```
, relative to the current directory where you run the skill)
Optional:
```
verify_online
```
: Whether to perform online verification (default false; only deterministic queries are performed, and it degrades on failure)

Output (Read-only + Reproducible)

Intermediate Products (Mandatory)

All intermediate files must be hosted in:

{project_root}/.nsfc-ref-alignment/run_{YYYYMMDDHHMMSS}/

Where

run_{YYYYMMDDHHMMSS}

is a timestamp; if the skill is run repeatedly in the same second, the script will append

-2/-3/...

to ensure multiple analyses do not conflict.

This directory must contain at least:

```
ai_ref_alignment_input.json
```
: Structured input (citation location + sentence context + literature metadata + verification results) for the host AI to make semantic judgments
```
ref_integrity_report.md
```
: Deterministic report (missing bibkey, duplicate entries, missing fields, DOI format issues, etc.)
```
citations.csv
```
: Itemized citation list (file/line/bibkey/sentence)
```
bib_inventory.json
```
: BibTeX inventory (cited entries and issue annotations)

Final Delivery (Default)

Only output a report for user review (default written to

./references/

; users can specify other directories):

```
NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md
```
(if run repeatedly in the same second, the script will append
```
-2/-3/...
```
to avoid overwriting)

This report must be a "read-only review report" and must not directly modify the proposal text or

.bib

files.

Workflow (Recommended)

Step 1: Pre-check and Localization

Confirm that
```
project_root
```
exists and contains
```
main_tex
```
.
Automatically parse the
```
\input{}
```
/
```
\include{}
```
dependency tree of
```
main_tex
```
and collect all involved
```
.tex
```
files.
Automatically discover
```
.bib
```
files pointed to by
```
\bibliography{...}
```
/
```
\addbibresource{...}
```
; if 0
```
.bib
```
files are found, fall back to searching for
```
*.bib
```
under
```
project_root
```
and issue a warning.

Step 2: Deterministic Extraction (Script Execution)

Run the script to generate structured input and deterministic reports:

bash

cd /path/to/ChineseResearchLaTeX
python3 skills/nsfc-ref-alignment/scripts/run_ref_alignment.py \
  --project-root "projects/NSFC_General" \
  --main-tex "main.tex" \
  --report-dir "references" \
  --prepare

For online verification (recommended only for final drafts/key entries):

bash

python3 skills/nsfc-ref-alignment/scripts/run_ref_alignment.py \
  --project-root "projects/NSFC_General" \
  --main-tex "main.tex" \
  --report-dir "references" \
  --prepare \
  --verify-online

Step 3: Host AI Semantic Verification (Core of This Skill)

After reading

{run_dir}/ai_ref_alignment_input.json

, the host AI verifies item-by-item:

Authenticity/Existence (P0)
- Missing bibkey: The text cites a non-existent entry
- DOI/URL is obviously invalid or online verification fails with severely inconsistent metadata
Semantic Mismatch Risk (P0/P1)
- P0: The sentence makes a "strong assertion" about the literature, but it is highly unlikely based on metadata (e.g., year contradiction, completely unrelated field, obvious misattribution)
- P1: Suspicious but insufficient evidence (insufficient metadata, missing DOI/missing title/incomplete author information)
Overclaiming/Weak Support (P1)
- For example, "first/only/best/significantly better than" but lacks sufficient support or seems to require stronger citations

Evidence Priority (Mandatory): Online verification results (if enabled) > BibTeX title/abstract > Inference only from sentences (lowest priority).

Step 4: Generate Final Report (Read-only)

Write the final report

NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md

report_dir

, which must include:

Summary: Total number of citations, number of unique bibkeys, number of missing entries, number of duplicate entries, number of P0/P1 issues
P0 (Must be handled): Missing bibkey, obviously forged/incorrect metadata, serious semantic mismatch
P1 (Recommended to be handled): Incomplete fields (missing DOI/missing year), weak support/overclaiming, need manual review
Appendix: Itemized citation details (at least including file/line, original sentence, key fields of the bib entry, risk judgment and reasons)

Modification Boundaries (Mandatory)

By default, do not modify any proposal content or configuration:
- Prohibited modifications:
```
**/*.tex
```
  ,
```
**/*.bib
```
  ,
```
**/*.cls
```
  ,
```
**/*.sty
```
Allowed writes:
- ```
{project_root}/.nsfc-ref-alignment/**
```
  (intermediate products)
- ```
./references/**
```
  (final report; can be changed to other locations by the user)
If the user explicitly requests "fix citations/fix bib", a modification plan and impact scope must be provided in the report first, then minimal modifications are performed (not done by default).

Relationship with check-review-alignment (Experience Reuse)

Common points: The script only performs deterministic extraction; the judgment of "whether semantics match" is completed by the host AI; outputs traceable structured input and reports.
Differences: This skill targets proposal projects (multi-file
```
\input{}
```
structure) and defaults to no automatic rewriting (only outputs review reports).

Verification Checklist (Static Self-check)

```
{project_root}/.nsfc-ref-alignment/run_{timestamp}/
```
exists and contains 4 core products (json/md/csv/json).
The final report is written to
```
report_dir
```
, and no
```
.tex/.bib
```
files are modified.
The report provides for each P0/P1 issue: location (file/line) + original sentence + basis + recommended action.

nsfc-ref-alignment

NPX Install

Tags

SKILL.md Content (Chinese)