feat(naming): add name-it-better plugin#250
Conversation
New single-skill plugin. /naming:name-it-better generates fresh name candidates by fanning out ~3 blind, fresh-context generators from distinct lenses (responsibility-literal, moment-of-use, domain-lore), scores a collision-checked shortlist against the consuming org's naming criteria, and recommends — the human always picks, never an auto-locked name. Optional tournament action adds elimination rounds with independent judges for high-stakes, hard-to-refactor names, framed honestly as an adaptation rather than a documented technique. Repo-agnostic: scores against the consuming project's declared naming conventions when present, degrading to the general criteria grounded in the skill's context/sources.md when none is declared. Ships warranted evals and the method-grounding sources file. Co-authored-by: Claude Fable 5 <noreply@anthropic.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ea5d0076e0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
sources.md cites three authoritative naming references whose hosts refuse automated link-checking — arlobelshee.com (DNS-unreachable, flagged in the file and corroborated via digdeeproots) and science.org / oreilly.com (403 to non-browser clients). Add them to the online-lane exclude list, matching the existing bot-blocked-URL entries; the Tversky-Kahneman open-PDF mirror stays checked. Verified with lychee: 12 OK, 0 errors, 3 excluded. Co-authored-by: Claude Fable 5 <noreply@anthropic.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5790430b42
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 5m 54s —— View job PR Review —
|
| Surface | Status |
|---|---|
| Code execution (hooks/scripts) | ✅ None — skill only |
| MCP servers | ✅ None |
Consumer config (userConfig) |
✅ None; documented in README |
| Cache isolation (no reach-outs) | ✅ Sources file uses relative context/sources.md references, not runtime fetches |
| Data egress / telemetry | ✅ None; fan-out generators are Claude subagents, not external endpoints |
| Provenance | ✅ Author matches org; MIT license; first-party |
Architecture alignment
| Check | Status |
|---|---|
| Repo-agnostic (no hardcoded paths/names) | ✅ |
| Configurable without fork (consumer CLAUDE.md / rules) | ✅ |
Plugin-form-safe (${CLAUDE_PLUGIN_ROOT} scope) |
✅ |
Versioned (0.1.0) |
✅ |
Namespace noun naming, skill verb name-it-better (no stutter) |
✅ |
tournament as argument (depth variant, not structural fork) |
✅ Defensible — the execution difference is prose-level, not a context: fork frontmatter change |
$schema in plugin.json and marketplace.json |
✅ |
Marketplace entry category/tags appropriate (design) |
✅ |
| lychee excludes justified with rationale | ✅ |
Two Codex review findings on the reactive-retry naming workflow:
- SKILL.md advertised natural-language trigger phrases ('name it
better', 'better name', ...) in "Use when:" form while
disable-model-invocation: true kept its description out of context,
so those phrases could never load the skill. Per the Skills docs
(https://code.claude.com/docs/en/skills#control-who-invokes-a-skill),
that flag hides the description entirely rather than merely
requiring a slash command. Remove it so the advertised triggers work,
matching other action skills in this repo (debugging/diagnose,
discovery/explore).
- The merge step deduped and collision-checked against existing
vocabulary but never excluded the rejected incumbent itself, so a
blind generator that independently re-derived a common name (e.g.
DataManager, Manager, Context) could still land in the shortlist and
defeat the anti-anchoring purpose. Carry the rejected name as an
explicit main-thread reject list — never shared with the blind
generators — and disqualify it at merge time. Extend eval case 1 to
assert the rejected incumbent cannot reappear in the shortlist.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9c4eb2b099
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
## What Adds a fifth skill to **`session-flow`**: `/session-flow:keep-going` — recover and continue after any interruption (rate limit, crash, disconnect, gap). It is the resume counterpart to `handoff`: handoff deliberately pauses a session, keep-going picks it back up. Flow: **inventory** off-thread work → **inspect** each item's real state from its own artifact (never assume "probably done" / "probably died") → **recover** (resume the resumable, restart the dead, surface the unrecoverable) → **reconcile** the main thread from a fresh read of its backing plan or handoff file → **report** recovered / restarted / still-running / lost. **Autonomy policy:** safe, idempotent, read-only work auto-resumes; re-running anything with external side effects (a push, a PR comment, a deploy) is gated when inspection cannot prove it did not already land — double-firing a side effect is worse than pausing. ## Design decisions - **Cause not diagnosed.** Short-limit vs weekly-limit vs crash does not change the recovery, so it is deliberately not classified. - **No capability enumeration.** Harness mechanisms (background tasks, shells, monitors, scheduled tasks, workflows, subagents) are named only as marked examples of the *kinds* of off-thread work — the duty is to inventory whatever the current harness exposes, so the skill survives tool evolution. - **Follows the plugin's conventions.** Version bump 0.6.0 → 0.7.0, `## X.Y.Z — DATE` changelog format, README skill-table + section, keywords, and root catalog entry all updated in the plugin's existing style. ## Coordination note This PR bumps `session-flow` to **0.7.0** and edits the shared plugin files (plugin.json version/description, README, CHANGELOG, root marketplace + catalog row). If a concurrent `session-flow` PR (e.g. a further orchestrate change) lands first, these shared-file edits are the expected conflict resolved by serializing the merge — this branch rebases onto the new base and re-bumps the version. The `keep-going/` skill files themselves are conflict-free. ## Gates - markdownlint-cli2 (MD013=80): clean. - `/skill-quality:check`: PASS, 0 errors / 0 warnings. - Evals present and schema-valid (4 warranted cases: real-state inspection, side-effect re-fire gating, nothing-off-thread, does-not-diagnose-cause). - `claude plugin validate` (plugin) and `--strict` (catalog): pass. Part of the round-2 personal-skill graduation, alongside `re-anchor` (#249) and `naming` (#250). Raw `~/.claude/skills/` copies are removed only after these merge and verify. ## Related - Sibling round-2 graduation PRs: #249 (re-anchor), #250 (naming), #251 (keep-going session-flow skill). - Upstream issues filed from this work: #252 (extract-ssot threshold), #253 (docs-hygiene proactive detection). No linked issue — round-2 personal-skill graduation is driven by the planning brief, not a tracked GitHub issue.
The tournament action runs in place of the default pass but never carried over the default pass's reject-list and collision disqualification. A tournament triggered after a rejection (or with a collision constraint) could present an already-rejected or colliding name as the winner. Gate bracket entry on the same disqualification: pool the widened candidates and drop reject-list/collision matches before the elimination rounds begin, so a rejected or colliding name can never reach the finalist. Add an eval locking this behavior.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b2bd63c040
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The name-it-better description advertised a bare 'rename this' trigger.
Because Claude uses the description to auto-load skills, a prompt like
"rename Foo to Bar" — where the target name is already chosen — could
load this name generator, which then stops to ask for candidate
selection instead of applying/sweeping the decided rename. That prompt
belongs to docs-hygiene:rename-references, whose description explicitly
handles 'rename X to Y'.
Narrow the trigger to the undecided-name case: drop bare 'rename this',
scope the phrase list to "name is still UNDECIDED", and add an explicit
skip clause routing already-decided renames ('rename X to Y', 'I renamed
X') to the rename-references sweep. Preserve the help-me-pick affordance
with 'help me rename this to something better'.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c6f2bb156
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 2m 38s —— View job Claude finished @kyle-sexton's task —— Follow-up Review —
|
| Surface | Status |
|---|---|
| Code execution (hooks/scripts) | ✅ None |
| MCP servers | ✅ None |
Consumer config (userConfig) |
✅ None |
| Cache isolation | ✅ No runtime fetches; context/sources.md is reference-only |
| Data egress | ✅ None |
Verdict: All blocking and important issues resolved. Items 5 and 6 are low-priority nits. ✅ Ready to merge once the lychee.toml sync question is confirmed.
## What
New plugin **`re-anchor`** — **five discipline correctors plus a
deep-verification sibling, sharing one re-anchor / audit /
correct-forward
engine doc**. Each corrector re-anchors a standing rule mid-session,
audits
the work in flight against it, and corrects what has drifted.
| Skill | Discipline it re-anchors |
|---|---|
| `/re-anchor:do-your-research` | Research / no-assumptions before
assertion |
| `/re-anchor:do-your-research-deep` | Verification-fan-out tier of
do-your-research — subagents verify every load-bearing claim so far |
| `/re-anchor:follow-our-standards` | Alignment to the consuming org's
engineering conventions |
| `/re-anchor:point-dont-copy` | Pointer over copy — cite the living
source, don't duplicate it |
| `/re-anchor:reason-dont-recite` | Interrogate inherited content —
precedent describes, it doesn't justify |
| `/re-anchor:tighten-your-output` | Terseness — fewer words or lines
with no loss of meaning or correctness |
The shared **re-anchor → audit → correct-forward** method lives once at
plugin scope (`context/re-anchor-audit-correct.md`); each skill carries
only
its own delta and cites the method doc (mirrors the `prototype`
precedent).
## Design decisions
- **Corrector tone.** Firing a corrector is a re-anchor, not an
accusation;
gentle-reminder use is first-class; the audit may honestly return clean.
- **Repo-/machine-agnostic (portability).** The source personal skills
hardcoded `~/.claude/CLAUDE.md`, `melodic-software/standards`, ghq, and
a
sync-manifest path — all removed. Each corrector resolves its
discipline's
source of truth from the **consumer's own** instruction layer via the
convention-resolution ladder, degrading to a **plugin-authored portable
baseline**. No `userConfig`, so no setup skill.
- **Model-invocable correctors (`disable-model-invocation: false`).**
Each
corrector advertises natural-language trigger phrases in its
`description`
("you're guessing", "too verbose", …). Those phrases only reach the
model's
invocation path when model invocation is enabled, so the flag is `false`
on
every corrector — the same choice the sibling `keep-going` skill (#251)
made, and consistent with the repo's convention that `true` is reserved
for
setup / destructive / mode-entry skills (`architecture:improve` even
re-enabled it). This makes the "Use when:" phrasing accurate rather than
inert, resolving both bot findings on this flag in one move.
- **`deep` is a sibling skill, not an argument.** The deep verification
pass
fans forked subagents out over every load-bearing claim — a change in
execution *topology*, not a depth knob on one path.
`MIGRATION-PLAYBOOK.md`
fixes execution-tier variants in frontmatter as siblings (the
`/discovery:research-deep` precedent), so `deep` graduated to
`/re-anchor:do-your-research-deep`. That sibling points at the parent's
discipline + the shared method doc (no duplication) and carries only the
fan-out delta, including a wave-cap / retry throttle so a claim-heavy
session cannot fire an unthrottled burst (mirrors `codebase-health`'s
per-file fan-out throttle and the guardrails burst-529 guidance).
- **`point-dont-copy` SSOT.** Its re-anchor routes through the org
standards'
`reference-don't-duplicate` (in-repo facts) and
`documentation-and-citations`
(external facts) conventions rather than restating that doctrine; the
skill
keeps only its own pins — threshold **two** (tighter than the
convention's
three-or-more smell signal), point-at-public-contracts, no-capability-
enumeration — plus the not-a-copy carve-outs.
- **`reason-dont-recite`.** Incumbency discipline, a distinct axis from
do-your-research (external evidence you lack vs internal evidence you
inherited). A standards disagreement it surfaces routes upstream via
`follow-our-standards` (routing-only delta; that skill owns "never
silent
deviation, never silent conformance" — no doctrine duplicated).
- **`tighten-your-output`.** Terseness. Code side re-anchors the org's
`simpler-code` convention (named failure modes; constraints never traded
for
line count); prose terseness has **no standards doc** (verified against
the
standards engineering conventions), so the skill flags that gap rather
than
inventing a rubric — a standards-repo issue proposes the prose sibling
of
`simpler-code.md`. Batch work routes to a compress capability (prose)
and a
simplify capability (code).
- **Plugin name `re-anchor`** reads verb-ish rather than the noun/gerund
the
repo's namespace guidance prefers — kept as owner-locked
(blind-generator
protocol). No `name:name` stutter.
- **Dogfooded `point-dont-copy`** on the plugin's own correctors:
trimmed
gotchas that restated the shared method doc.
## Gates
- markdownlint-cli2: clean on all 9 markdown files.
- `claude plugin validate` (re-anchor) + `--strict` (catalog): both
pass.
- `validate-plugin-contracts.mjs`: pass.
- Evals present + schema-valid against
`skill-quality/reference/evals.schema.json`
(4 warranted cases each across all 6 eval sets).
- Root catalog regenerated via `scripts/generate-catalog.mjs` (in sync).
## Related
- Sibling round-2 graduation PRs: #249 (re-anchor), #250 (naming), #251
(keep-going session-flow skill).
- Upstream issues filed from this work: #252 (extract-ssot threshold),
#253 (docs-hygiene proactive detection), plus a
melodic-software/standards issue proposing a markdown/prose-terseness
convention (linked in the PR thread).
No linked issue — round-2 personal-skill graduation is driven by the
planning brief, not a tracked GitHub issue.
…ludes The prior commit added three exclude patterns (arlobelshee.com, science.org, oreilly.com) to root lychee.toml so the online link-check would skip method-source URLs whose hosts are DNS-dead or 403 non-browser clients. But lychee.toml is a standards-synced, upstream-managed config (see AGENTS.md and standards/distribution/sync-manifest.yml): a local edit is silently overwritten on the next sync, dropping the excludes and re-breaking the check. The fix belongs in the branch-owned source file. Revert lychee.toml to be byte-identical to main, and reformat the three blocked citations in the naming plugin's sources.md from markdown reference links to inline code-span URLs. lychee skips verbatim/code segments by default (include_verbatim is unset; the link-check lane passes only --config lychee.toml, no --include-verbatim), so a code-span URL is not extracted for checking while remaining a readable, useful citation. Verified with lychee 0.24.2 --dump against sources.md: the three blocked URLs no longer appear in extraction, and the reachable cs.tufts open-PDF mirror (tk-1974-pdf, still a reference link) does. Remove the three now-orphaned reference definitions; no dangling labels remain.
|
Claude finished @kyle-sexton's task in 2m 19s —— View job Claude finished @kyle-sexton's task — Follow-up Review —
|
| Area | Status |
|---|---|
SKILL.md — frontmatter, description, trigger routing |
✅ Clean. user-invocable: true, no disable-model-invocation. Already-decided rename exclusion explicit. |
SKILL.md — Default pass logic (steps 1–5) |
✅ Brief-only seeding, reject list at merge time, collision-before-scoring, human-picks stop. |
SKILL.md — Tournament mode |
✅ Reject list + collision disqualification applied before elimination rounds. Honest-framing flag present. |
SKILL.md — Gotchas section |
✅ Covers generator re-derivation of the incumbent; names the mechanism. |
evals/evals.json — 5 cases, schema-valid |
✅ Eval 1 covers blind seeding + merge-time disqualification. Eval 2 covers collision-before-scoring. Eval 3 covers tournament honest framing. Eval 4 covers missing-criterion routing. Eval 5 covers tournament reject+collision end-to-end. |
context/sources.md — tier labels, bot-blocked citations |
✅ Bot-blocked URLs in code spans (resolved by 1162aac). Reference-style links used for checkable URLs. |
plugin.json — schema, version, metadata |
✅ $schema present, 0.1.0, author/license correct. |
marketplace.json — entry, category, tags |
✅ naming registered under design, tags match plugin capability. |
README.md — install, configuration, honest tournament framing |
✅ No userConfig, no persistent state, runtime network claim correct (subagents, not external fetches). |
Security review pass (unchanged — no regressions)
| Surface | Status |
|---|---|
| Code execution (hooks/scripts) | ✅ None |
| MCP servers | ✅ None |
Consumer config (userConfig) |
✅ None |
| Cache isolation | ✅ No runtime fetches; context/sources.md is reference-only |
| Data egress | ✅ None |
Verdict: All blocking issues resolved across two rounds; the lychee durability concern is now also closed. ✅ Ready to merge. The CHANGELOG reference link nit can be addressed in a follow-up.
…coverage table (#1594) ## Summary Closes the loop-lane prompt coverage gap: parked human-gated items, decision-pending items, and deferred-with-trigger decisions belonged to no standing lane and rotted silently (ci-workflows accumulated 13 before an ad-hoc burn-down). - **Template 3b — parked-decision burn-down** (attended, on demand): three scoped populations (parked human-gated via three-way role resolution; live-resolved decision-pending status label; trigger sweep over 3b's own populations plus 90-day closed-item decision comments), wayfind/attention-view/telemetry exclusions, bounded-query discipline, brief-verify-ratify pipeline with fresh-context verifiers before ratification, five outcome verbs (flip / decide-close / retarget / re-home / re-park-with-named-trigger), inlined work-class contract, AI-disclaimer form, and rate-limit floor (the block invokes no skill, so it inherits nothing). - **Intro coverage table**: one row per item state → owner, including the deliberately/currently unowned states (dormant needs-info, external recurring automation, unscheduled lease audit, lane telemetry) so absence is visible instead of silent. - **Filled ready-to-paste instance** for this repository, per the file's convention. An independent fresh-context review of the draft returned SHIP-WITH-FIXES with 16 findings (4 blocking: false completeness claim in the coverage table, trigger-sweep population colliding with the worker lane, wayfind HITL items captured with a mode-destroying Flip, hardcoded status label breaking portability); all 16 are addressed in this revision. ## Test plan - `markdownlint-cli2` on the file: 0 errors. - `git diff --check`: clean. - Template contracts cross-checked against `plugins/work-items` (attend-queue view grammar, triage closing invariant, role-label resolution, wayfind label ownership) and the loop-lane convention's inline-floor rule during the review pass. - Prompt-shaped content — no executable surface changed; the live validation is the next burn-down session run from this template. ## Related - Closes #1582 - Codifies the attended burn-down pattern from the ci-workflows session 2026-07-26 (ci-workflows#148 retarget, #241/#250 decisions) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01X47ju75UpdNcLgfsaEM9tj --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
What
New single-skill plugin
naming—/naming:name-it-bettergeneratesand evaluates fresh name candidates for anything (identifier, file, module,
skill, repo, domain term), then hands the human a scored shortlist. It never
auto-locks a name.
The dominant trigger is a reactive retry: a name was just rejected, and the
same context that produced it will only produce more of the same. So the
generators run blind to the conversation — seeded only with a distilled
context brief — across three distinct lenses (responsibility-literal,
moment-of-use, domain-lore). Diverge widely, converge once, and keep the
first-seen suggestion from anchoring the choice. An optional
tournamentaction widens to ~5 generators with elimination rounds and independent
judges for high-stakes, hard-to-refactor names — framed honestly as an
adaptation of elimination brackets + pairwise scoring, not a documented
naming technique.
Design decisions
melodic-software/standardsnaming docs. Generalized: the skill scoresagainst the consuming org's naming/domain-language conventions when
the project declares them (
CLAUDE.md/.claude/rules/ a standardssource it points to), degrading to the general criteria grounded in the
skill's
context/sources.mdwhen none is declared. A missing criterionflows UP into the org's conventions, never hardcoded into the skill.
context/sources.mdkept as the plugin's own one-shot researchdeliverable (method grounding: Belshee/Deep Roots naming-as-a-process,
Ottinger/Clean Code, DDD ubiquitous language, Double Diamond, anchoring
bias, and the tournament-mode adaptation basis). Only its two references
to "the standards repo" were generalized to "the consuming org's
conventions".
naming(gerund, activity domain) + skillname-it-better(action verb) — noname:namestutter. Plugin namelocked by the owner via the blind-generator naming protocol.
Gates
/skill-quality:check: PASS, 0 errors / 0 warnings.collision-check, tournament honest-framing, missing-criterion-routes-up).
claude plugin validate(plugin) and--strict(catalog): pass.Part of the round-2 personal-skill graduation. Sibling PR #249 adds the
re-anchorcorrector plugin; another sibling addskeep-goingtosession-flow. Raw~/.claude/skills/copies are removed only after thesemerge and verify.
Related
No linked issue — round-2 personal-skill graduation is driven by the planning brief, not a tracked GitHub issue.