nsfc-roadmap

NSFC Technical Roadmap Generator

Collaboration agreement with bensz-collect-bugs

• When a bug caused by a design flaw in this skill occurs in the user's environment, prioritize using bensz-collect-bugs to record it according to the specification in ~/.bensz-skills/bugs/. It is strictly forbidden to directly modify the source code of the skill already 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 completing the current task.
• When the user explicitly requests a public reporting action such as "report bensz skills bugs", call the local gh and bensz-collect-bugs, and only upload newly added bugs to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

Positioning

• Used to convert the research content, technical approach, and risk control in an NSFC proposal into a printable, A4-readable roadmap.
• The default workflow is deterministic drawio rendering; switching to PNG-only is allowed only when the user explicitly requests the Nano Banana image model.
• This skill only serves research writing and visual expression, and does not represent any official review criteria or funding conclusions.

Input

Provide at least one of the following:

• proposal_path: proposal directory, recommended.
• proposal_file: a single input file.
• spec_file: structured diagram specification file, most controllable.

Optional:

• rounds: by default read config.yaml:evaluation.max_rounds
• output_dir: default roadmap_output/
• renderer: default drawio; use only when the user explicitly requests nano_banana
• dotenv: only nano_banana use
• style_ref_images: only nano_banana use, at most the first 4 images
• layout / template_ref: advanced option, not needed by default

Output

Default delivery:

• roadmap.drawio
• roadmap.svg
• roadmap.png
• roadmap.pdf
• roadmap-plan.md

Hidden intermediate artifacts are located at output_dir/.nsfc-roadmap/：

• runs/run_*/round_*
• spec_latest.yaml
• optimization_report.md
• config_used_best.yaml
• evaluation_best.json
• config_local.yaml
• ai/：stop_strategy=ai_critic request/response protocol when

Nano Banana mode delivers only:

• roadmap.png
• roadmap_compacted.png

Hard rules

• First read config.yaml. The following fields are regarded as the single source of truth:renderer、evaluation、layout、color_scheme、planning、output。
• Only process files or directories explicitly provided by the user; by default, treat the proposal as sensitive information.
• By default, do not supplement materials from the internet; if the user requests internet access, first warn about the risks.
• By default, keep the drawio process; do not switch the rendering backend without authorization just because "the image model is faster".
• If the content is crowded, prioritize changing the node copy, grouping, or structure of spec ; do not force it past the threshold by shrinking the font size.

Workflow

1. Planning

• If spec_fileis already provided, this can be skipped.
• By default, use config.yaml:planning.planning_mode=ai：
  1. run plan_roadmap.py to generate plan_request.json/plan_request.md
  2. host AI writes roadmap-plan.md and spec_draft.yaml
  3. run the script again to validate spec_draft.yaml
• The planning stage should consider both the project rationale and the research content, not just 2.1 研究内容。

2. Convert to spec

• Priority: user-provided spec_file > spec_draft.yaml from the planning stage > automatically extracted from the input file.
• The spec should at least clarify the stages, nodes, inputs and outputs, and risks/alternatives.
• Template fields are optional; by default, binding to a specific template_ref。

3. Deterministic rendering

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 5

• At render time, finalize spec_latest.yaml
• generate deliverable files and evidence for each round
• draw.io CLI When missing, decide whether to prompt, degrade, or stop according to the configuration

4. Evaluation and optimization

• By default, at most 5 rounds, subject to config.yaml:evaluation .
• Each round identifies at least three types of issues:
  • P0: missing research content, broken logic, isolated nodes, unreadable
  • P1: cluttered layout, distracting color scheme, font size too small
  • P2: general optimizations such as spacing, margins, arrow clarity, etc.
• The stop strategy only looks at the configuration:early_stop、stop_strategy=plateau or stop_strategy=ai_critic
• Multi-dimensional self-checks by default cover structure / visual / readability

5. Optional: AI autonomous closed loop

• If you want the host AI to decide “whether to continue and what to change,” enable config_local.yaml in evaluation.stop_strategy: ai_critic。
• The script will generate under output_dir/.nsfc-roadmap/ai/ :
  • ai_critic_request.md
  • ai_critic_response.yaml
  • Each round ai_pack_round_XX/

6. Optional: Nano Banana PNG-only (Gemini / OpenAI gpt-image-2）

• Enable only when the user explicitly requests it.
• First perform a connectivity check:

python3 nsfc-roadmap/scripts/nano_banana_check.py

• .env In IMAGE_PROVIDER=openai you can switch to OpenAI via GEMINI_* ; if not explicitly specified, by default preferentially continue using the existing

• Then generate the PNG:

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 1 \
  --renderer nano_banana

Common commands

# 规划
python3 nsfc-roadmap/scripts/plan_roadmap.py --proposal /path/to/proposal --output ./roadmap_output

# 生成
python3 nsfc-roadmap/scripts/generate_roadmap.py --spec-file ./roadmap_output/spec.yaml --output-dir ./roadmap_output --rounds 5

# 图片模型连通性
python3 nsfc-roadmap/scripts/nano_banana_check.py

Reference materials

• config.yaml
• references/models/templates.yaml
• references/models/README.md
• assets/evaluation_rubric.md