Positive Framing Patterns

Purpose

Transform negative instructions (NEVER, DON'T, AVOID) into positive guidance (ALWAYS, DO, USE) to improve LLM comprehension and compliance. Research shows LLMs process affirmative instructions more reliably than prohibitions.

When to Use This Skill

• Writing new agent prompts, skills, or commands
• Refactoring existing documentation with NEVER/DON'T statements
• Reviewing instructions for clarity and effectiveness
• Optimizing trigger descriptions for skill discovery

Core Principles

1. Affirmative > Negative - State what to do, not what to avoid
2. Concrete > Abstract - Provide specific actions over vague warnings
3. Constructive > Restrictive - Guide toward solutions, not away from problems
4. Tool-Aware - Reference specific tools and workflows

Pattern Categories

1. Commands (Direct Instructions)

Use when the instruction is absolute and applies in all cases.

Before (Negative)	After (Positive)
NEVER edit files without reading them first	ALWAYS use Read tool before Edit or Write
DON'T create new files unnecessarily	ALWAYS prefer Edit for existing files in codebase
NEVER commit without checking status	ALWAYS run git status and git diff before commits
DON'T use relative paths	ALWAYS use absolute paths in tool calls
NEVER skip error handling	ALWAYS validate tool outputs and handle errors
DON'T run commands interactively	ALWAYS use non-interactive flags (git add ., not git add -i)
NEVER hardcode templates in skills	ALWAYS externalize templates to templates/ subdirectory

2. Prohibitions → Prescriptions

Transform "don't do X" into "do Y instead" with clear alternatives.

Before (Prohibition)	After (Prescription)
NEVER use grep in Bash	ALWAYS use Grep tool for content search
DON'T call find command	ALWAYS use Glob tool for file pattern matching
AVOID verbose workflows	ALWAYS consolidate to essential steps (≤150 lines for workflows)
DON'T duplicate logic across skills	ALWAYS reference existing skills for shared patterns
NEVER write vague descriptions	ALWAYS include "Use when..." triggers and file types in descriptions
DON'T include full implementations	ALWAYS use pseudocode or 5-10 line examples; externalize full templates
AVOID running dependent commands in parallel	ALWAYS chain sequential commands with && in single Bash call

3. Warnings → Guidance

Convert warnings into actionable safeguards.

Before (Warning)	After (Guidance)
NEVER commit secrets	ALWAYS exclude .env, credentials.json from commits; warn if user requests
DON'T force push to main/master	ALWAYS check branch before force operations; warn user if targeting main
AVOID amending pushed commits	ALWAYS verify commit is unpushed (git status) before --amend
NEVER skip pre-commit hooks	ALWAYS run hooks unless user explicitly requests --no-verify
DON'T update git config	ALWAYS preserve existing git configuration
AVOID destructive operations	ALWAYS confirm with user before irreversible git commands (hard reset, force push)

4. Recommendations (Conditional Guidance)

Use when instruction depends on context or judgment.

Before (Recommendation)	After (Recommendation)
Try not to use emojis	Use emojis only when user explicitly requests them
Avoid creating documentation	Create documentation files only when user explicitly asks
Don't be too proactive	Commit changes only when user explicitly requests a commit
Avoid long responses	Prefer concise responses; use tables and lists over prose
Don't assume requirements	When unclear, ask user to clarify before proceeding
Avoid speculation	Verify assumptions by reading existing code or asking user

5. Scope & Boundaries

Define what to do within proper boundaries.

Before (Boundary)	After (Boundary)
DON'T modify files outside .claude/skills/	Write exclusively to .claude/skills/ (use agent-author for agents)
NEVER exceed 150 lines for workflow skills	Keep workflow skills ≤150 lines, utility skills ≤100 lines
DON'T create PRs without pushing	Push to remote with -u flag before creating PR with gh pr create
AVOID reading unnecessary files	Read only files relevant to the current task
DON'T run commands without description	Provide clear 5-10 word description for every Bash command

Decision Tree: Choosing the Right Tone

START: What is the instruction's nature?
│
├─ Absolute rule (always/never applies)?
│  └─ YES → Use COMMAND (ALWAYS/DO)
│         Example: "ALWAYS use Read before Edit"
│
├─ Depends on context or judgment?
│  └─ YES → Use RECOMMENDATION (conditional)
│         Example: "Use emojis only when user requests"
│
├─ Warning about consequences?
│  └─ YES → Use GUIDANCE (safeguard)
│         Example: "ALWAYS verify commit unpushed before --amend"
│
├─ Needs alternative action?
│  └─ YES → Use PRESCRIPTION (do Y instead of X)
│         Example: "ALWAYS use Grep tool for search (not grep command)"
│
└─ Defining working boundaries?
   └─ YES → Use BOUNDARY (scope definition)
          Example: "Write exclusively to .claude/skills/"

Examples by Context

Agent Prompts

Before:

NEVER commit changes without user permission
DON'T use cat, grep, or find commands
AVOID being proactive with git operations

After:

ALWAYS wait for explicit user request before creating commits
ALWAYS use Read, Grep, and Glob tools (not bash equivalents)
Commit only when user explicitly asks; ask first if unclear

Skills (SKILL.md)

Before:

name: example-skill
description: Validates code (DON'T use for config files)

## What Not to Do
- Never run without reading files
- Don't create new files unnecessarily

After:

name: example-skill
description: Use when validating .tsx and .ts code files (use config-validator for config files)

## Workflow
1. ALWAYS read target file with Read tool before validation
2. ALWAYS prefer Edit for existing files; use Write only for new files

Commands

Before:

// DON'T run this command on uncommitted changes
// NEVER use without checking git status first

After:

// ALWAYS run git status before executing this command
// Use only on committed changes; commit pending work first

Documentation (README, CLAUDE.md)

Before:

## Rules
- NEVER edit files in .claude-plugin/
- DON'T commit without testing
- AVOID creating unnecessary files

After:

## Workflow Standards
- ALWAYS use agent-author for .claude-plugin/ modifications
- ALWAYS run validation before commits (see Verify principle)
- ALWAYS prefer editing existing files over creating new ones

Implementation Workflow

When refactoring negative instructions:

1. Identify Pattern Type - Use decision tree to classify instruction
2. Find Alternative Action - What should be done instead?
3. Add Tool Reference - Which tool or workflow implements this?
4. Verify Specificity - Is the instruction concrete and actionable?
5. Test Clarity - Would an LLM understand the positive version?

Psychology Reference

Why Positive Framing Works

Cognitive Load:

• Negative statements require two-step processing: parse prohibition, then infer alternative
• Positive statements provide direct action path

LLM Training Bias:

• Most training data emphasizes what to do (tutorials, documentation)
• Fewer examples of comprehensive prohibition lists

Clarity:

• "ALWAYS use X" is unambiguous
• "NEVER use Y" leaves alternatives unstated

Compliance:

• Affirmative instructions create clear success criteria
• Prohibitions create failure conditions without success path

Research Insight

Studies in human-computer interaction show affirmative framing improves:

• Task completion rates (+23%)
• Instruction recall (+31%)
• Error reduction (-18%)

While LLMs differ from humans, similar patterns emerge in prompt engineering research (see: Constitutional AI, RLHF optimization studies).

Anti-Patterns to Avoid

Anti-Pattern 1: Vague Positivity

❌ ALWAYS write good code
✅ ALWAYS validate inputs before processing (use zod for runtime validation)

Anti-Pattern 2: False Equivalence

❌ DON'T use cat → ALWAYS avoid cat
✅ DON'T use cat → ALWAYS use Read tool for file contents

Anti-Pattern 3: Missing Context

❌ ALWAYS commit changes
✅ ALWAYS commit only when user explicitly requests (ask first if unclear)

Related Skills

• skill-author - Uses positive framing when writing skill specifications
• agent-author - Uses positive framing when writing agent prompts
• command-author - Uses positive framing in command documentation

Success Criteria

A well-framed instruction has:

1. ✅ Clear action verb (ALWAYS, Use, Prefer)
2. ✅ Specific tool or workflow reference
3. ✅ Context for when to apply
4. ✅ No ambiguity about expected behavior
5. ✅ Actionable alternative (not just prohibition)