nsfc-ref-alignment

NSFC Ref Alignment

Applicable scenarios

• You have an NSFC proposal (LaTeX project) and want to check:
  • .tex whether all \cite{...} / \citep{...} / \citet{...} and other citation bibkeys exist in .bib
  • .bib whether the basic fields of the entry are complete and whether the format has obvious errors (such as invalid DOI, missing year)
  • Whether the "semantic claim" of the sentence containing the citation matches the reference (at least based on metadata such as title/author/year/venue/DOI), and whether there is a risk of mis-citation/overclaiming/misattribution
• You wantto receive only a reportto review manually first (changing .bib / changing the text is a major matter).

Not applicable

• You want "automatic replacement of bibkeys / automatic rewriting of the text"—this skill prohibits direct modification by default (unless you explicitly request it).
• You only want to fill in missing BibTeX entries: prefer to use nsfc-bib-manager。

Input

• project_root: the root directory of the proposal project (such as projects/NSFC_General）
• Optional:main_tex: the main entry tex (default main.tex）
• Optional:report_dir: the 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, degrade on failure)

Process

Input

Provide the necessary input according to the user's request and configuration file; missing information should be clearly listed and steps that depend on that input should stop.

Execution steps

• When a bug caused by a design flaw in this skill occurs in the user's environment, prefer to use bensz-collect-bugs to record it according to the specification in ~/.bensz-skills/bugs/, and it is strictly forbidden to directly modify the installed skill source code in the user's local Claude Code / Codex.
• If the AI can still continue to 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 public reporting actions such as "report bensz skills bugs", call the local gh and bensz-collect-bugs, and upload only the newly added bug to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

Step 1: Pre-check and locate

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

Step 2: Deterministic extraction (script execution)

Run the script to generate structured input and a deterministic report:

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

If online verification is needed (it is recommended to enable it only for the final draft/key entries):

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 (the core of this skill)

After the host AI reads {run_dir}/ai_ref_alignment_input.json , check one by one:

1. Authenticity/existence（P0）

   • Missing bibkey: the text cites a non-existent entry
   • DOI/URL is clearly invalid or online verification fails and metadata is severely inconsistent

2. Semantic mismatch risk（P0/P1）

   • P0: The sentence makes a "strong assertion" about the reference, but from the metadata it is highly unlikely (e.g., year contradiction, completely unrelated field, obvious misattribution)
   • P1: Suspicious but insufficient evidence (insufficient metadata, missing DOI/missing title/incomplete author information)

3. Overclaiming/weak support（P1）

   • For example, "first/only/optimal/significantly better than" but lacking sufficient support or seemingly requiring stronger citations

Evidence priority (mandatory): Online verification results (if enabled) > BibTeX title/abstract > Inference from the sentence alone (lowest priority).

Step 4: Generate the final report (read-only)

At report_dir write the final report NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md, which must include:

• Summary: total citation count, number of unique bibkeys, number of missing entries, number of duplicate entries, P0/P1 counts

• P0 (must be handled): missing bibkey, obviously forged/incorrect metadata, severe semantic mismatch

• P1 (recommended to handle): incomplete fields (missing DOI/missing year), weak support/overclaiming, requires manual review

• Appendix: detailed item-by-item citation list (including at least file/line, original sentence, key fields of the bib entry, risk assessment, and reason)

• Common points: the script only performs deterministic extraction; the judgment of "whether the semantics match" is completed by the host AI; it outputs traceable structured input and reports.

• Differences: this skill is aimed atproposal projects(multi-file \input{} structure), and by defaultdoes not perform any automatic rewriting(only outputs a review report).

Output

Intermediate artifacts (mandatory)

All intermediate filesmust be hosted in:

{project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/{yyyy-mm-dd-hh-mm}/

Where run_{YYYYMMDDHHMMSS} is the timestamp; if run repeatedly within the same second, the script will append -2/-3/..., ensuring that multiple analyses do not conflict.

This directory contains at least:

• ai_ref_alignment_input.json: Structured input (citation location + sentence context + reference 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: Item-by-item citation list (file/line/bibkey/sentence)
• bib_inventory.json: BibTeX list (cited entries and issue annotations)

Final delivery (default)

Output only onereport for user review(by default written to ./references/; the user may specify another directory):

• NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md(if run repeatedly within 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 body or .bib。

Output management

Intermediate files for new tasks of this Skill are uniformly written to ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/. The same task reuses one task root directory; only multi-Skill collaboration creates shared/. Formal deliverables are not written to this directory; historical hidden directories only allow explicit compatible reading, migration, or cleanup.

Validation

• {project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/{yyyy-mm-dd-hh-mm}/ exists and contains 4 core artifacts (json/md/csv/json).
• The final report is written to report_dir, and no .tex/.bib files have been modified.
• The report provides, for each P0/P1: location (file/line) + original sentence + basis + recommended action.

Failure and recovery

Preserve error evidence and completed artifacts; retry from the most recent failed step only after the input, environment, or external dependency has recovered.

Constraints

• By defaultdo not modifyany bid content or configuration:
  • Prohibited modifications:**/*.tex、**/*.bib、**/*.cls、**/*.sty
• Allowed writes:
  • {project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/**(intermediate artifacts)
  • ./references/**(final report; may be changed by the user to another location)
• If the user explicitly requests "fix citations/fix bib", the report must first provide amodification planand impact scope, then perform the minimal modification (not done by default).

Common hard constraints

• When a task requires writing to disk, use a unique ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ root directory; place shared materials in shared/, and place Skill-specific materials in that Skill's input/、output/、log/。
• Formal deliverables, source code, and formal plans are saved according to project conventions and are not written into the task workspace; without authorization, do not overwrite, delete, migrate, or write remotely.
• Project maintenance changes check BAC availability and record requirements, AI outputs, tool results, file changes, and verification summaries; BAC performs process auditing only and does not replace attribution, responsibility, or compliance judgment.
• Do not record API Keys, access tokens, passwords, Cookies, environment/credential files, private Prompts, identity information, local usernames, hostnames, or unnecessary large volumes of raw data.
• File paths must be normalized and restricted to the authorized project scope; external URLs, subprocesses, and network access follow least privilege to prevent path traversal, SSRF, and command injection.
• Skill versions are recorded uniquely in their own config.yaml:skill_info.version; changes to public APIs, protocols, directories, or configurations are synchronized with documentation and CHANGELOG.md。
• Only design flaws in the Skill or Bensz infrastructure itself are reported to bensz-collect-bugs; first write a redacted version to ~/.bensz-skills/bugs/, the current task is not interrupted, public reporting occurs only when the user explicitly requests it, and directly modifying the source code of a Skill already installed by the user is prohibited.

Skill-specific constraints

Do not exceed the scope declared in this Skill's description and the process above; do not disguise unverified information as definitive conclusions.