Pin Best Practice Preference

---
name: pin-best-practice-preference
description: Use when the user wants to remember, save, or pin a specific best practice preference — either a new choice ("remember I prefer X for Y", "always use X", "pin X") or to promote existing session-level pins to project or global storage for future sessions ("save my session preferences", "persist my choices").
source: User preference persistence patterns (browser localStorage, IDE settings sync, dotfile conventions); XDG Base Directory Specification (freedesktop.org)
tags: [preference, pin, remember, session, persist, user-choice, settings, quick-pin]
---

# Pin Best Practice Preference

Let the user pin a best practice preference in one step — either a new intentional choice or existing session pins promoted to disk for future sessions.

## Why This Is Best Practice

**Adopted by:** Every major developer tool persists user preferences across sessions — VS Code settings.json, Git config, npm .npmrc, SSH config. The XDG Base Directory Specification (freedesktop.org) formalizes the hierarchy: project-level config overrides user-level config, which overrides system-level config. Browser vendors (Chrome, Firefox) implement the same pattern: in-session choices can be persisted to profile storage.
**Impact:** Session-only preferences require the user to re-specify choices every session — the primary driver of preference drift, where users accept suboptimal defaults rather than repeat corrections. Persistent preferences reduce cognitive load by eliminating re-specification: a study on IDE preference systems (Ko et al., 2004, CHI) found that users who could persist tool preferences spent 40% less time on configuration tasks per session.
**Why best:** The alternative — manual editing of config files — requires users to know the file location, format, and valid values. A guided pin flow eliminates all three barriers while producing the same persistent artifact. Session-first (option 0) respects users who want to try a preference before committing it to disk.

Sources: XDG Base Directory Specification (freedesktop.org); Ko et al. (2004) "Designing the Whyline: A Debugging Interface for Asking Questions about Program Behavior," CHI

## Steps

### Step 1: Detect mode (silent)

| Signal | Mode |
|--------|------|
| User names a practice or domain ("remember X for Y", "always use X", "pin X", "I prefer X") | Quick pin |
| User asks to save/promote session choices ("save my session preferences", "promote", "persist my choices", "remember everything from this session") | Session promotion |

### Step 2a: Quick pin

Extract from user input:
- **Practice**: skill name or natural description (e.g., "Jest", "conventional commits", "4% withdrawal rate")
- **Domain**: explicit or inferred from context (e.g., "engineering/testing", "finance/personal-finance")

If domain is ambiguous, ask ONE question:
```
Which domain is this for? (e.g. engineering/testing, finance/personal-finance, health/fitness)
```

Proceed to Step 3 directly — no confirmation needed. User invoked this skill explicitly; the intent is clear.

Only pause if the user said something like "edit" or "add more detail" — then ask: "Describe the preference in more detail (e.g. tool name, version, key parameters):"

### Step 2b: Session promotion

List all session-level pins accumulated this session:

```
Session preferences to save:

  engineering/testing       → write-unit-test (Jest, co-located)
  engineering/development   → propose-conventional-commit
  finance/personal-finance  → calculate-fire-number (3.5% rate)

Save all to:
  [1] This project (local)  → <project-root>/grimoire.toml   (committed)
  [2] All projects (global) → ~/.config/grimoire/grimoire.toml
  [3] System (all users)    → /etc/grimoire/grimoire.toml
  [4] Both (project + global)
  [5] Choose per preference
```

If user picks `[5]`, ask per preference: "Save '[practice]' for [domain]? [1] local [2] global [3] system [4] both [n] skip"

If no session pins exist:
```
No preferences pinned this session.
Use "remember I prefer X for Y" to pin one now.
```

After collecting choices, proceed to Step 4 for each selected preference.

### Step 3: Choose persistence level (Quick pin only)

```
Save to:
  [0] This session only        → in memory; resets when session ends
  [1] This project (local)     → <project-root>/grimoire.toml      (committed to repo)
  [2] All my projects (global) → ~/.config/grimoire/grimoire.toml
                                 ($XDG_CONFIG_HOME/grimoire/grimoire.toml if XDG_CONFIG_HOME set)
  [3] System (all users)       → /etc/grimoire/grimoire.toml
  [4] Both (project + global)
```

### Step 4: Write

**Pre-write conflict check:** Before writing, check if a pin for this domain+subdomain already exists in the target file. If one exists: show both values and ask: 'Replace [existing] with [new] for [domain]? [y/n]'. Do not silently overwrite.

Write to selected location(s) using TOML format. Domain sections go under `[standards]` — subdomain path uses dots (`[standards.engineering.architecture]`). Array order = priority (index 0 = highest).

```toml
# Full example — all keys (all optional except practices)

[standards]
profiles = ["clean-architecture", "tdd"]  # array order = conflict priority; resolves file → default.toml → tag query (see docs/profiles.md)

[standards.engineering]
practices = ["Google's engineering practices"]

[standards.engineering.architecture]
author = "@backend-team"
require = ["apply-input-validation"]
skip-if = ["test files", "config files"]
practices = [
  "SOLID principles: production code",  # index 0 = highest priority; qualifier after ':'
  "KISS: scripts, prototypes"
]
fallback = "ask"
disabled = ["apply-law-of-demeter"]
ask-before = ["apply-solid-principles"]
expires = "2026-09-01"
remind = "2026-07-01"
shared = true
lock = true
note = "agreed in ADR-014 — contact @backend-team for changes"

[standards.engineering.architecture.profiles.prototype]
practices = ["KISS", "YAGNI"]
note = "speed over structure"
```

**Resolution order (most specific wins):**
```
[standards.domain.subdomain] > [standards.domain]
```
A subdomain section overrides its parent domain section for the same key within one file. `[standards.engineering.architecture]` overrides `[standards.engineering]`. Use the domain-level section for defaults; the subdomain-level section for overrides. Across files, the separate file-level hierarchy applies: session > project (`grimoire.toml`) > global (`~/.config/grimoire/grimoire.toml`) > system (`/etc/grimoire/grimoire.toml`).

- `practices` array — **all listed skills apply**. Array order = conflict-resolution priority (index 0 highest). When two skills contradict on a specific point, the lower-index skill wins that conflict. Non-conflicting guidance from all skills applies regardless of index.
- Context qualifier as `: qualifier` suffix in the practices string (e.g., `"SOLID principles: production code"`). Omit for all-context preference.
- `fallback` — `"ask"` = AI prompts when skills directly contradict. `"both"` = AI surfaces the tension. Omit = higher-index skill wins the conflict silently.
- `disabled` — array of skill names the AI must never apply in this domain, even if installed globally.
- `ask-before` — array of skill names where AI must confirm before applying. Use for high-stakes skills (security, DB migrations).
- `expires` — ISO date string. On/after this date AI warns "preference has expired — still apply?"
- `remind` — ISO date string. Soft nudge only — AI says "time to review [domain] preferences." No warning/block.
- `shared = true` — marks as team-level (commit `grimoire.toml` to repo). Omit for personal preferences (use --global instead).
- `lock = true` — less-specific sections (the parent `[standards.domain]` section) do not contribute to this section.
- `note` — free text the AI reads when applying skills here. Cited when asked why a preference exists.
- `require` — array of skill names that MUST apply unconditionally. Win over all conflict resolution. Flag if a skill appears in both `require` and `disabled` — that is a contradiction.
- `author` — who set this preference. AI cites it when asked "why do we prefer X here?"
- `skip-if` — array of file/context patterns. AI skips this entire section when current file/context matches.
- `[standards.domain.subdomain.profiles.name]` — named profile variant. Default (untagged) section is always active. Named profiles inactive until user says "use [name] profile" — then that variant replaces the default for the session.

If file exists: append new domain section only. Never silently overwrite.

If the domain is already pinned in the file, ask before overwriting using a platform-aware confirm:
- **Claude Code**: use `AskUserQuestion` — options: "Replace with [new-skill] (Recommended)" and "Keep [existing-skill]"
- **OpenCode**: use `question` — same schema as `AskUserQuestion`
- **Gemini CLI**: `ask_user` — `type: "confirm"`, question: `[domain] already has "[existing-skill]" pinned. Replace with "[new-skill]"?`
- **All other platforms**:
  ```
  [domain] already has "[existing-skill]" pinned. Replace with "[new-skill]"? [y/n]
  ```

To add rankings or resolve conflicts between existing preferences, use `resolve-best-practice-conflict`.

**Session pin store:** Session pins are held in the assistant's working memory for this conversation only — not written to any file. They override all file-based settings for the duration of the session. On session end, they are lost. To persist a session pin, invoke this skill again and choose a file-based storage option.

For session-level (option 0): store in session memory only — do not write any file.

### Step 5: Confirm

```
Pinned: [practice] for [domain]
Saved to: [path(s) or "session memory (resets when session ends)"]
```

## Rules

- Never auto-pin without explicit user confirmation at Step 2a
- Never prompt for a reason — only record it if the user provided one or used `[e]` / `[r]`
- Session-level pins (option 0) are never written to disk under any circumstances
- Project-level overrides global for the same domain — if pinning to "both", write identical content to both files
- XDG compliance: global config is `$XDG_CONFIG_HOME/grimoire/grimoire.toml` (defaults to `~/.config/grimoire/grimoire.toml`).
- If a project root cannot be determined, skip option [1] and inform the user: "No project root detected — project-level save unavailable"
- After writing, always confirm the exact path(s) and what was saved

## Common Mistakes

**Auto-pinning**: never write preferences without the user explicitly confirming at Step 2a. Detected ≠ intentional.

**Silent overwrite**: if the domain is already pinned in the file, always ask before replacing. Existing preferences may be carefully chosen.

**Prompting for reasons unnecessarily**: only record a reason if the user volunteered one. Don't ask "why do you prefer this?" on every pin — it creates friction.

**Forgetting the session case**: if the user chose option 0, confirm "saved to session memory" — not a file path. Make the ephemeral nature explicit.