---
name: shama-add-context
description: Add terms, context, or instructions to Shama voice-to-text files
  for clipboard mode (Ctrl+Opt+Space) or shell-command mode (Ctrl+Opt+S), at
  project or global level.
---

# Add Shama Context

Add new entries to Shama's vocabulary, context, or instructions files when the transcriber misrecognizes words, the cleanup step formats text incorrectly, or shell-mode generates the wrong command.

Shama is the resident macOS voice-to-text app. It reads a per-project `voice.json` plus an optional global `voice.json`; the file keys below point at the markdown files that feed its pipelines.

Two context levels: **project-level** (default) — files specific to the current project, stored alongside the project's `voice.json` — and **global-level** — files shared across all projects, stored alongside `~/.voice/voice.json`. For each file key, Shama takes the union of global then project values: global file-list entries come first, project entries are appended (duplicates by resolved path removed). A project-level entry adds to — it does not replace — the global one.

Two modes, each with its own trio of files:

- **Clipboard mode** (Control+Option+Space) — `contextFile`, `vocabularyFile`, `instructionsFile`
- **Shell-command mode** (Control+Option+S) — `shellContextFile`, `shellVocabularyFile`, `shellInstructionsFile`

Each pipeline consumes different files:

- **Transcription step (OpenAI)** — the relevant vocabulary file: a flat list of terms sent as hints for accurate word recognition. Affects what words the transcriber produces.
- **Cleanup step (Claude, clipboard mode)** — `contextFile` (project knowledge) and `instructionsFile` (how-to formatting rules). Affects how transcribed text is corrected and structured.
- **Shell-command generation (Claude, shell mode)** — `shellContextFile` (background for command generation) and `shellInstructionsFile` (rules for command output). Affects what shell command is produced.

Identify which stage is failing:

- Wrong word recognized → vocabulary (or shell-vocabulary)
- Right word, wrong formatting / structure → context or instructions
- Shell command wrong style, tool choice, or OS flags → shell-context or shell-instructions

## Step 1: Determine the target level and locate the files

Use global-level if the user explicitly mentions "global", "global context", "global config", "global Shama context", or `~/.voice/`. Otherwise default to project-level.

### Global-level resolution

1. Read `~/.voice/voice.json` to find any of the six file keys above
2. Resolve all configured paths relative to `~/.voice/`
3. If `~/.voice/voice.json` does not exist or has none of these keys configured, inform the user that global Shama config has no context files yet and offer to create one — see "Creating a missing file" in Step 3
4. Read the contents of any files that exist

### Project-level resolution (default)

1. Read `voice.json` in the current directory to find any of the six file keys
2. If `voice.json` does not exist, check for the conventional filenames in the current directory:
   - `voice-context.md`, `voice-vocabulary.md`, `voice-instructions.md`
   - `voice-shell-context.md`, `voice-shell-vocabulary.md`, `voice-shell-instructions.md`
3. If no project files exist at all, inform the user that Shama is not configured for this project and suggest running `/shama-init-config` first. Stop here.
4. Read the contents of any files that exist

## Step 2: Determine the mode and target file(s)

Default to clipboard mode. Use shell-command mode when the user mentions "shell", "shell mode", "shell command", "terminal", "Control+Option+S", or shell-mode dictation.

If the user's request is too vague to act on, ask for:

- The word or phrase as it was incorrectly transcribed (or the wrong shell command)
- The correct form it should produce
- Optionally, a brief definition or context note

Then pick the file(s) for the scenario:

### Clipboard mode (Control+Option+Space)

| Scenario | Vocabulary file | Context file | Instructions file |
|---|---|---|---|
| **Misheard term** | Add correct term | Add term with description and common mishearings | — |
| **New terminology** | Add correct term | Add term with description | — |
| **Naming convention** | — | Add to Naming Conventions section | — |
| **Project context** | — | Add to appropriate section | — |
| **Cleanup formatting / style rule** | — | — | Add rule |

### Shell-command mode (Control+Option+S)

| Scenario | Shell vocabulary file | Shell context file | Shell instructions file |
|---|---|---|---|
| **Misheard term in shell request** | Add correct term | Add term with description | — |
| **Tool or binary name** | Add correct term | Add binary description if non-obvious | — |
| **Preferred tool / style** (e.g., "prefer `rg` over `grep`") | — | — | Add rule |
| **OS-specific behavior** | — | — | Add rule |
| **Project shell context** (paths, common workflows) | — | Add to appropriate section | — |

## Step 3: Add the entries

### Vocabulary file entries (clipboard or shell)

One term per line — no markdown formatting, no descriptions, just the bare term with correct spelling and capitalization:

```
Zod
CLAUDE.md
ResolvedFileRef
```

### Context file entries (clipboard mode)

Add to the appropriate section, following the existing format:

- **Technologies**: `- {Name} ({brief description})`
- **Terminology**: `- **{Term}** - {brief definition or correction note}`
- **Naming Conventions**: `- {convention description}`

When adding a misheard word correction, include the common misheard form in the definition to help Claude recognize and correct it:

```markdown
- **Zod** - Runtime validation library (not "god", "sod", or "zawed")
- **lgit** - Git wrapper for .local directory (not "legit" or "l-git")
```

### Instructions file entries (clipboard mode)

The instructions file controls *how* cleanup is performed. Add formatting rules, style preferences, or behavioral overrides — not project knowledge:

```markdown
- Always preserve fenced code blocks verbatim — do not edit, reformat, or summarize their contents
- Prefer hyphen-style bullet points (`-`) over asterisks (`*`)
- When listing steps, use numbered lists; when listing options, use bullets
```

### Shell-context file entries (shell mode)

Background information for the shell-command generator: project paths, repo layout, preferred tools, common workflows. Same structural format as the clipboard-mode context file but oriented toward shell usage.

### Shell-instructions file entries (shell mode)

Rules for shell-command output:

```markdown
- Prefer `rg` (ripgrep) over `grep` for content searches
- Prefer `fd` over `find` when available
- Quote paths that may contain spaces using double quotes
```

### Creating a missing file

If the target file does not yet exist:

1. Pick a conventional filename relative to the project root (or `~/.voice/` for global): `voice-instructions.md`, `voice-shell-context.md`, `voice-shell-vocabulary.md`, `voice-shell-instructions.md`
2. Create the file with a minimal scaffold (top-level heading appropriate to the file's role, then the first entry)
3. Register the new file path under the corresponding key in the relevant `voice.json` — the project's for project-level, `~/.voice/voice.json` for global (create the `voice.json` if it does not exist)

### Guidelines

- Keep each context / instructions file concise — every relevant file is injected into the prompt for its pipeline. For project-level files, aim for under ~80 lines; if a file is approaching that, suggest removing less relevant entries before adding new ones
- Match the formatting style of existing entries, with exact capitalization for each term
- For acronyms, include the expansion in the context file
- Omit widely known terms (JavaScript, React, Git) unless they are specifically being misheard

## Step 4: Confirm

After editing, display:

- Whether the project-level or global-level files were updated (and their paths)
- Which mode the change targets (clipboard or shell)
- Which file(s) were modified (vocabulary, context, instructions, or their shell-mode equivalents)
- The specific entries that were added
- If a `voice.json` (`~/.voice/voice.json` for global) was updated to register a new file, mention that
- A brief reminder: changes take effect on the next Shama recording (Shama captures file contents per recording — no app restart needed)