The Grimoire of Software Magic Words

Operative Vocabulary, Prompt-Spells, and Stackcraft for AI-Assisted Software Engineering

AI coding gets better when the request names the artifact, the invariant, the output shape, the verification step, and what to do when the task is underspecified.

The Software Grimoire is a public field manual for turning vague AI requests into bounded, reviewable software work. Its core unit is a spell: a structured prompt template. A stack is a workflow made of spells. A rune is a high-force engineering term. A shadow is the failure mode to watch.

0.1 Weak Request

Clean up this Python module and make it nicer.

0.2 Repaired Spell

ROLE: Act as a senior Python engineer performing behavior-preserving refactoring.

OBJECTIVE: Remove duplication in the supplied module without changing public behavior.

CONTEXT: The module is imported by two API handlers and one CLI entry point. Existing tests cover only the happy path.

CONSTRAINTS: Do not change public function names, parameter order, return types, or raised exception classes. Touch only this module and its tests.

OUTPUT CONTRACT: Return a minimal patch plan, the proposed refactor, and tests that prove unchanged behavior.

VERIFICATION: State the invariants first; then show before/after test cases for edge inputs.

FAILURE BEHAVIOR: If the module boundary is too small for a safe refactor, say exactly what adjacent file must also move and why.

Expected delta: The repaired spell narrows blast radius, makes invariants reviewable, and forces proof through tests instead of relying on claims of cleanliness.

Start with First Spell in Five Minutes, copy Spell of Safe Refactoring, browse the Proof by Difference cases, or review Jailbreak Resilience for defensive adversarial promptcraft. Use the guided reader path if you want the full theory.