agenticnotetaking/skills/true-name

/eidos:true-name

Establish ubiquitous language — replace vague references with precise, canonical domain names and propagate everywhere.

See [[c - ubiquitous language - shared vocabulary across specs code and conversation]]. When the same concept has three names, nobody is sure they're talking about the same thing. When it has one true name, communication becomes precise and specs become navigable.

Usage

/eidos:true-name <vague reference or concept>

Examples:

• /eidos:true-name "the thing that tracks plan progress"
• /eidos:true-name "that config toggle mechanism"
• /eidos:true-name rename phase-gate → phase-checkpoint

Instructions

1. Understand the Target

Parse the input:

• Discovery mode — a vague description or concept that needs naming (e.g., "the thing that X")
• Rename mode — an existing name that should be replaced (e.g., "rename X → Y" or "X should be called Y")

If the input is ambiguous, ask: "What are you pointing at?"

2. Survey Current Usage (Discovery Mode)

Search for how the concept is currently referenced:

# In specs — filenames and content
grep -ri '<related terms>' eidos/
grep -ri '<related terms>' memory/

# In code
grep -ri '<related terms>' src/ skills/ scripts/ hooks/

# In recent conversations (session exports)
grep -ri '<related terms>' memory/session\ -\ *.md

Collect:

• Every name, description, or reference used for this concept
• Where each appears (file + line)
• Which representations are most common

3. Propose a True Name

A true name should be:

• Domain-native — uses the language of the problem, not the implementation ("phase" not "step-container")
• Precise — names what it is, not what it's near or what it does sometimes
• Stable — won't need renaming as the concept evolves
• Self-evident — someone unfamiliar can guess the meaning
• Consistent — fits the existing naming patterns in the project

Present the proposal:

## Current references
- "progress tracker" in spec - planning (3×)
- "status section" in plan template (1×)
- `updateProgress()` in code (2×)

## Proposed true name: `progress-log`

Rationale: It's a log (append-only, timestamped entries), not a tracker
(which implies computed state). "Progress log" matches how it's actually
used in plan files.

Alternatives considered:
- `activity-log` — too generic, doesn't convey plan-specific scope
- `progress-tracker` — implies computed state, but it's just entries

Apply this name? (y / suggest alternative)

If the user suggests an alternative, evaluate it against the same criteria and confirm.

4. Propagate the Name

Once confirmed, propagate systematically:

Spec filenames (if the concept is a spec or claim):

git mv "eidos/old - name.md" "eidos/new - name.md"

Then update all [[wiki links]] referencing the old name.

Spec content:

• Replace the old term in prose, headings, and TL;DRs
• Check that the claim in the filename still matches content

Code identifiers (if applicable and the user confirms):

• Variable names, function names, class names
• Comments referencing the old term

Plan and memory files:

• Update references in active plans
• Don't rewrite historical files (sessions, solved) — they're records of what was

Commit after each logical unit (filenames, then content, then code).

5. Rename Mode

When the input is explicitly "rename X → Y":

• Skip discovery — the user already knows the true name
• Go straight to surveying where X appears
• Show the propagation plan (which files, which references)
• Confirm, then propagate

6. Report

## True name applied: `progress-log`

Renamed:
- [spec - progress log - ...](<eidos/spec - progress log - ...md>)
  - was: spec - progress tracker - ...

Updated references:
- [plan template](<eidos/template - plan - ...md>) — 2 occurrences
- [planning spec](<eidos/spec - planning - ...md>) — 3 occurrences
- [scripts/progress.py](<scripts/progress.py>) — 1 occurrence

No changes (historical):
- memory/session - ... (3 files reference old name, preserved as-is)

Output

• Renames: spec/claim files via git mv
• Updates: wiki links, prose, and optionally code identifiers
• Does not modify: historical memory files (sessions, solved items)