Publishing a note with an AI assistant

NSDF-Data student guide 5 — with Claude Code or a similar assistant · Version 5 · 20 October 2026

This is guide 5 of 5. It shows how to use an AI coding assistant, such as Claude Code, to do the tedious parts of writing and publishing a note. It does not replace guides 3 and 4. You still own every number and every sentence.

What the assistant is good at here

converting a Word or Google Docs draft to a note (with tools/word_to_note.py), and fixing the formatting it leaves behind;
reading the check’s messages and fixing the file for each one;
checking that every notebook link is pinned to a real commit;
finding numbers in your draft and confirming them against your notebook’s output;
checking the header, the section headings and the outline.

What it must not do

Never let it invent or round a number. Every number in the note must come from your notebook output.
Never let it write your reading or your conclusion. It can tidy your sentences. The conclusion must be yours.
Never let it edit other people’s notes, docs/index.html, or anything under docs/. Those are generated by the publishing step.
Never let it push to master or develop, commit data files, or commit anything under the idx folder.
Never let it run the notebook that overwrites data_analysis/archives/good_noise.h5, unless your lead has said it is fine.

Setting it up

Install the assistant. For Claude Code, follow Anthropic’s setup instructions at docs.claude.com.
Open a terminal in the NSDF-Data folder and start the assistant there. It needs to see the repository.
Make sure you are on your own branch: git checkout student-yourname. Run git status, and check that it shows no changes you do not recognise.

A starting brief

Start with a brief like this, and fill in the brackets:

I am a student writing a note for the NSDF-Data site. My draft is [path to your .docx or .md], my notebook is [path to the notebook], and I committed it at [commit hash]. Please:

If the draft is a .docx, convert it with python tools/word_to_note.py [path to the .docx] [note-name], as in student guide 4, Step 1. That puts the note in notes/src/ and its pictures in notes/src/img/. Keep the header block and set id: "TBD".

Check every number in the text against the notebook output, and list any number that does not match or that I have not shown.

Pin every notebook link to the commit above.

Run python tools/check_note.py notes/src/[note-name].md. Fix each problem it reports (the structure and the pinned links), without changing my sentences except where a fix needs it, and list the numbers it says are not in the notebook output, without changing them.

Show me the diff and stop. Do not commit or push until I say so.

The checks you still do yourself

After the assistant has finished, go through these yourself:

Open the Markdown file and read it from top to bottom. Does every sentence say what you mean?
Pick three numbers at random and find them in your notebook output.
Check that every picture looks the way your caption says.
Look at the diff. Are there changes to any file outside notes/src/? If so, ask why, and revert them unless you understand them.
Run python tools/check_note.py notes/src/your-note-name.md yourself and confirm that its last line says ready for review. Then look at each number it lists as not found.

Committing and opening the pull request

Once you are satisfied, follow guide 4 from Step 2 onward. You can ask the assistant to write the commit message, but read it before you commit.

When the assistant goes wrong

It says it has checked a number, but the number is not in the notebook. Stop, and ask it to show you the line of output it used. If it cannot, the number is wrong.
It changes a sentence you wrote into a different claim. Revert that sentence, and say so in your next message to the assistant.
It wants to change docs/ or index.html. Do not allow it. Those files are generated.
It keeps failing the check. Ask your lead. Paste the check’s message, not a summary of it.

Session Info

Guide version 5, 20 October 2026. Written for every computer. The AI tools change quickly, so if a step here no longer matches what you see, follow the assistant’s own instructions and tell your lead.

Where to get help

Anthony Villano, project lead: anthony.villano@ucdenver.edu

Include the brief you gave the assistant, what it changed, and the check’s last message.

Key links

Guide 3, writing a note; guide 4, publishing a note: https://villano-lab.github.io/NSDF-Data/
Pull requests: https://github.com/villano-lab/NSDF-Data/pulls
Claude Code documentation: https://docs.claude.com