sams-genai-spells

Sam's Spells

Real-world concepts from programming, education, and design — packaged as AI commands.

These aren't prompt engineering techniques I invented. They're established concepts from real fields — idiomatic code (programming), the Socratic method (education), Diataxis + progressive disclosure (documentation theory), task graphs (operations research), systematic debugging (reliability engineering), program comprehension (software engineering). I just got tired of re-explaining them every session and made commands to use them.

What It Looks Like

Modifier -- you invoke it once, and it changes the whole session:

> /spell:idiomatic Python 3.12

IDIOMATIC MODE: PYTHON 3.12
══════════════════════════════════════════════════════════════

Version: 3.12
Source: https://docs.python.org/3.12/

SESSION CONSTRAINTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
USE (canonical patterns):
• pathlib.Path over os.path — modern path handling
• match/case for structural pattern matching — added in 3.10
• f-strings over .format() — cleaner, faster
• type hints with built-in generics (list[int] not List[int]) — PEP 585

AVOID (deprecated or non-idiomatic):
• os.path.join() → Use pathlib.Path / operator instead
• typing.List, typing.Dict → Use built-in list[], dict[] generics
• implicit string concatenation → Use f-strings or explicit +

These constraints are active for the rest of this session.

Workflow -- does research and gives you something concrete:

> /spell:bpap Git commit messages

BEST PRACTICES & ANTIPATTERNS: GIT COMMIT MESSAGES
══════════════════════════════════════════════════════════════

Source: Built-in knowledge + https://cbea.ms/git-commit/

DO ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Use imperative mood in subject line — "Add feature" not "Added feature"
2. Keep subject to 50 characters — forces concise summary
3. Separate subject from body with blank line — tools depend on this
4. Wrap body at 72 characters — readable in terminal and git log

DON'T ✗
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Don't end subject with period — it's a title, not a sentence
2. Don't use "fix bug" or "update code" — say what and why
3. Don't put everything in the subject — use the body for detail

ANTIPATTERNS ⚠
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. THE KITCHEN SINK — Unrelated changes lumped into one commit
   Why it's tempting: You're "almost done" and don't want to split work
   Consequences: Impossible to revert one change without losing others
   Instead: One logical change per commit, use interactive staging

The Spells

Modifiers change how the AI behaves for the rest of the session. You invoke one, then keep working. The constraints stick.

Spell	What it does
idiomatic	AI keeps hallucinating APIs that don't exist? Sets session constraints based on real docs and canonical patterns, not guesswork.
socratic	Want to actually learn, not just get an answer? Flips the AI into question-mode so you reason through problems yourself.

Workflows do research and produce actual output. They'll ask you questions first, then go do the work.