NAI OS
Settled early, or paid for on every rename after.
A slash command in this repo has no identity separate from its name. The filename
(.claude/commands/option-study.md), the invocation string (what you type,
/option-study), and every place another file mentions it in prose are the exact same
characters. There is no stable ID underneath, quietly absorbing change, with the name as just one
mutable label pointing at it. The name is the identity — which means renaming it
does not touch one row in one table. It touches every string that repeats it.
Take /option-study as it stood before any rename was even proposed. It was the
filename. It was what a person typed. And it was quoted, verbatim, inside roughly fifteen other
files — its own README, the review-pack README that contrasts itself against it, the
issue-to-agent bridge's argument hint, four concept pages under this same tour, five Mermaid
diagram sources, and more. None of those fifteen mentions point at some underlying
option-study thing through an ID. Each one just repeats the string. Change
the string once, and fifteen places are now wrong until each is found and fixed by hand.
The fix for this problem already exists two folders over, on the /nai-issue-to-agent bridge. You type
/nai-issue-to-agent <issue-id-or-url> <option-study|review-pack>, and the very
first thing the orchestrator does is resolve that argument to a stable UUID before
anything else happens. From that point on, every downstream step —
fetch-issue.mjs, the deliverable it writes, post-comment.mjs posting the
write-up back — addresses the issue by that UUID. Someone can rename the issue's title in
nai-analysis tomorrow and nothing here breaks, because nothing here was ever
pointing at the title. Identity and label, cleanly separated, sitting right next to the case where
they were not.
| What other things point at | Rename cost | |
|---|---|---|
| nai-analysis issue | a stable UUID, resolved once | zero — the title is just a label |
| Slash command | the literal name string, repeated everywhere | one edit per occurrence, everywhere it was repeated |
The nai- rename — prefixing all eight of this workspace's commands so they
read as this repo's own at a glance — got a full design doc and an eleven-task implementation
plan, task-by-task, grep-verified before and after each one. It was not abandoned for lack of a
plan. It was deferred anyway, because even a completely planned pass across this many files was
judged too risky to run in one sitting.
| Commands renamed | 8 |
| Files touched | ~40 — commands, READMEs, agent prompts, worked examples, the whole architecture site and its Mermaid sources |
| Cross-reference type | mostly prose mentions, not filenames — a mermaid node label three files deep is just as live a reference as the command's own file |
| Identifiers that had to stay exactly as they were | 2 — option-study
and review-pack, bare, because scripts/issue-bridge/fetch-issue.mjs
and post-comment.mjs consume them as literal argument strings, not display
text |
One surface has no repo file to edit at all. The hourly activity check is
armed as a scheduled cron job whose stored prompt text literally invokes
/check-nink-activity. That string lives inside the scheduler, not in any file this
repo tracks — a grep sweep across the whole workspace cannot find it, let alone fix it. The
only way to update it is to notice, by hand, the next time the job is re-armed. The identity
problem does not stop at the edge of the repo; it follows the name wherever the name was copied.
The honest fix — give every command a stable ID and let the name be a mutable label — is not available here. Claude Code's own convention forces filename to equal invocation for a slash command; there is no indirection layer to retrofit onto that after the fact, only one to design in before the first file exists. Once it doesn't exist, the only lever left is timing.
Settle a system's naming convention before its first cross-reference is written, not after.
Past a certain number of accumulated mentions, even a fully planned, fully verified rename stops
being something you run in one pass — it becomes something you chip away at incrementally,
one command at a time, whenever you're already touching that command for another reason. That is
exactly the plan this repo is working — the nai- mapping is decided and on
record, not executed as a bulk change, applied one command at a time as each is next touched.