Intent Resolution Protocol

The Protocol (Run on Every User Message)

Lives in ~/.claude/CLAUDE.md so every session loads it cold. The full text:

1. Hear — what did James literally say? Take it at face value first.
2. Skill match — does any phrase trigger a Skill Auto-Invoke entry? If yes, run that skill, you are done. Otherwise continue.
3. Entity scan — does the message reference a repo, file, app, person, business, dashboard, or other entity? If no → answer the question literally and stop. If yes → continue.
4. Resolve via aliases — check ~/apps/cc/entity-aliases.json (source of truth). The human-readable view is the Entity Aliases table at the bottom of ~/apps/cc/repo-registry.md.
5. Confidence gate:
   • ≥80% (direct alias match): act silently, just do the work
   • 50–80% (fuzzy match or strong context): act, but state the assumption inline
   • <50% (new phrase, unknown target, or genuinely ambiguous): take your best stab and ask ONE confirming question
6. Disambiguation — if multiple repos plausibly match, use most recent context. If still unclear, ask ONE question.
7. Save & learn — every new phrase that resolves to an entity gets appended to entity-aliases.json immediately. Run python3 ~/apps/cc/sync-entity-aliases.py to refresh the markdown view. Next session knows it cold.

The Confidence Gate

Step 5 is the load-bearing part. Without it, Claude either pesters with clarifying questions on every turn, or silently wrong-routes. The three bands:

Confidence	What Claude does
≥80%	Acts silently. James says “the CRM” → Claude works in claude-code-crm without comment.
50–80%	Acts but states the assumption. James says “the booking thing” → Claude says “Working on claude-code-crm” before the first tool call.
<50%	Best stab + one question. James says “the new dashboard” → Claude says “Do you mean the Mission Control dashboard at ~/apps/cc/mission-control.html?”

The 80% threshold is intentional — slight ambiguity gets surfaced so James can correct early, but high-confidence matches do not slow the conversation down.

The JSON Map

~/apps/cc/entity-aliases.json is the source of truth. Structured so it can grow without becoming a tangle.

{
  "id": "claude-code-crm",
  "type": "repo",
  "target": "~/apps/claude-code-crm/",
  "phrases": [
    "the CRM",
    "the booking engine",
    "the prompt",
    "the responder"
  ],
  "ambiguous_with": ["ai-assistant", "ddxweb-crm"],
  "disambiguation_hints": "Topic is messaging/leads/payments → claude-code-crm. Topic is owner alerts → ai-assistant.",
  "added": "2026-04-16"
}

Entry types — what the target IS:

Type	Example phrase	Example target
repo	”the CRM”	~/apps/claude-code-crm/
file	”the super CLAUDE MD”	~/.claude/CLAUDE.md
action	”pop it open”	bash ~/apps/cc/open-html.sh
person	”Wayne”	Wayne Lewis
dashboard	”Mission Control”	~/apps/cc/mission-control.html
url	(future)	(future)
tool	(future)	(future)
concept	(future)	(future)

The phrases[] array makes it many-to-one — multiple ways of saying the same thing all resolve to one target. The ambiguous_with[] array lists known confusions; disambiguation_hints tells Claude how to break ties from context.

How “Save & Learn” Works

The system gets smarter via two loops:

1. In-session learning — When James gives Claude a new phrase (“when I say X I mean Y”), Claude appends to phrases[] for that entry and runs the sync script. Effective immediately for the rest of the session, persisted forever.
2. Confirmation learning — When Claude takes a best stab and James confirms (“yeah, the tms-internal repo”), Claude saves the phrase that triggered the stab.

The Seven Routing Layers (Background)

Beyond the JSON alias map, there are six other routing systems doing related work:

Layer	File	What It Routes
1. Skill Auto-Invoke	~/.claude/CLAUDE.md	Plain-English phrase → slash command
2. Entity Aliases	~/apps/cc/entity-aliases.json	Phrase → repo / action / file / person
3. CRM Context Rules	~/.claude/CLAUDE.md	Disambiguation between claude-code-crm and ai-assistant
4. Log Router Keywords	~/apps/cc/log-router-keywords.json	Keywords → repo (for log distribution)
5. Log Router	~/apps/cc/log-router.py	Slash commands → repo (post-hoc routing)
6. CRM Redirect Hook	~/apps/cc/hooks/crm-redirect.sh	PreToolUse safety net for CRM repo confusion
7. zshrc Aliases	~/apps/zshrc-editor/	Shell command → cd into repo + start Claude

The Intent Resolution Protocol explicitly walks layers 1, 2, and 3 in real time during conversation. Layers 4 and 5 are post-hoc (they run nightly to file logs into the right per-repo dev-log). Layer 6 catches mistakes. Layer 7 is for terminal-launched sessions that bypass conversation entirely.

Adding a New Alias by Hand

Edit ~/apps/cc/entity-aliases.json, add or update an entry, then:

python3 ~/apps/cc/sync-entity-aliases.py

That regenerates the markdown table inside repo-registry.md. Commit both files together.

Adding a New Type

Types are not enforced — they are descriptive. To add a new one (say dashboard), just use it in the type field and document the convention here. Keep types short and singular.

Why JSON, Not Just Markdown

Two reasons:

1. Many-to-one mapping is awkward in markdown — listing five phrases per row in a table is fine for reading, but parsing it back into structured data is brittle.
2. Programmatic updates — the daily reflection job appends new phrases automatically. Editing JSON is straightforward; editing a markdown table reliably is not.

The markdown table still exists for human skimming. The JSON is the source of truth.

Recovery

If entity-aliases.json gets corrupted or wiped, the cc repo is the backup. git log entity-aliases.json shows every change. git checkout HEAD~1 -- entity-aliases.json rolls back one revision.