Prompt Engineering Reference
June 1, 2026 · View on GitHub
This document contains lexical salience patterns for writing effective AI agent instructions. The key principle: selective emphasis creates focus - when too many words are capitalized, none stand out.
Lexical Salience Principle
| Approach | Effectiveness | Why |
|---|---|---|
| Few CAPS words at sentence START | HIGH | AI attention focuses on critical instructions |
| Many CAPS words scattered throughout | LOW | Salience dilution - everything emphasized = nothing emphasized |
Rule: Place enforcement words at the BEGINNING of instructions, not in the middle or end.
Enforcement Words (Use Sparingly, at Beginning)
| Word | Purpose | Correct Usage |
|---|---|---|
| MUST | Primary requirement | "MUST verify before proceeding" |
| REQUIRED | Mandatory action | "REQUIRED: Load standards first" |
| MANDATORY | Section marker | "MANDATORY: Initialize todo list" |
| STOP | Halt execution | "STOP and report blocker" |
| HARD GATE | Critical checkpoint | "HARD GATE: Cannot proceed without..." |
| CANNOT | Prohibition | "CANNOT skip this gate" |
| FORBIDDEN | Explicitly banned | "FORBIDDEN: Direct code editing" |
Words to Keep Lowercase (Context Words)
These provide context but dilute emphasis when capitalized:
| Avoid | Use Instead |
|---|---|
| all | |
| any | |
| only | |
| each | |
| every | |
| not (except in "MUST NOT") | |
| no | |
| and | |
| or | |
| if | |
| use "MUST NOT" instead | |
| use "MUST" instead |
Positioning Examples
| Position | Effectiveness | Example |
|---|---|---|
| Beginning | HIGH | "MUST verify all sections before proceeding" |
| Middle | LOW | "You should verify all sections, this is MUST" |
| End | LOW | "Verify all sections before proceeding, MUST" |
Transformation Examples
| Before (Diluted) | After (Focused) |
|---|---|
| "You MUST check ALL sections" | "MUST check all sections" |
| "NEVER skip ANY gate" | "MUST NOT skip any gate" |
| "This is MANDATORY for EVERY task" | "MANDATORY: This applies to every task" |
| "ALWAYS verify BEFORE proceeding" | "MUST verify before proceeding" |
| "Check IF this CONDITION is met" | "MUST check if this condition is met" |
| "ALL agents MUST have this" | "MANDATORY: All agents must have this" |
Sentence Structure Pattern
[ENFORCEMENT WORD]: [Action/Instruction] [Context]
Examples:
- MUST dispatch agent before proceeding to next gate
- STOP and report if PROJECT_RULES.md is missing
- HARD GATE: All 9 default reviewers and any triggered conditional specialists must pass before Gate 8 completion
- FORBIDDEN: Reading source code directly as orchestrator
- REQUIRED: WebFetch Ring standards before implementation
- MANDATORY: Save state after every gate transition
Strategic Spacing (Attention Reset)
Spacing matters for AI attention. When multiple critical rules appear in sequence, add blank lines between sections to allow "attention reset" - each section gets its own salient word.
| Pattern | Effectiveness | Why |
|---|---|---|
| Blank line between rule groups | HIGH | Attention "resets" between sections |
| Dense continuous text | LOW | Critical words blur together |
Example - Strategic Spacing
## Authentication
Handle auth tokens according to existing patterns.
Validate JWT signatures on every request.
NEVER log sensitive credentials.
## Data Access
Use repository pattern for all queries.
Implement pagination for list endpoints.
CRITICAL: All mutations must be idempotent.
## Error Handling
Wrap errors with context.
Map internal errors to HTTP codes.
NEVER expose stack traces to clients.
Why this works:
- Each section has ONE salient word (NEVER, CRITICAL, NEVER)
- Blank lines create visual and semantic boundaries
- AI attention focuses on one rule group at a time
- The enforcement word in each section stands out
Anti-Pattern - Dense Text
## Rules
Handle auth tokens. Validate JWT. NEVER log credentials. Use repository pattern. CRITICAL: mutations idempotent. Wrap errors. NEVER expose stacks.
Why this fails: Three CAPS words in one dense block - none stands out.
Rule: When writing multiple critical rules, space them into logical groups with blank lines between.
Consequence Phrases
| Phrase | When to Use | Example |
|---|---|---|
| → STOP | Define halt condition | "If PROJECT_RULES.md missing → STOP" |
| = FAIL | Define failure | "Missing verification = FAIL" |
| is incomplete | Define completeness | "Agent is incomplete if missing sections" |
Consequence Phrases
| Phrase | When to Use | Example |
|---|---|---|
| If X → STOP | Define halt condition | "If PROJECT_RULES.md missing → STOP" |
| FAILURE TO X = Y | Define consequences | "Failure to verify = incomplete work" |
| WITHOUT X, CANNOT Y | Define dependencies | "Without standards, cannot proceed" |
| X IS INCOMPLETE IF | Define completeness | "Agent is INCOMPLETE if missing sections" |
Verification Phrases
| Phrase | When to Use | Example |
|---|---|---|
| VERIFY | Confirm something is true | "VERIFY all categories are checked" |
| CONFIRM | Get explicit confirmation | "CONFIRM compliance before proceeding" |
| CHECK | Inspect/examine | "CHECK for FORBIDDEN patterns" |
| VALIDATE | Ensure correctness | "VALIDATE output format" |
| PROVE | Provide evidence | "PROVE compliance with evidence, not assumptions" |
Anti-Rationalization Phrases
| Phrase | Purpose | Example |
|---|---|---|
| Assumption ≠ Verification | Prevent assuming | "Assuming compliance ≠ verifying compliance" |
| Looking correct ≠ Being correct | Prevent superficial checks | "Code looking correct ≠ code being correct" |
| Partial ≠ Complete | Prevent incomplete work | "Partial compliance ≠ full compliance" |
| You don't decide X | Remove AI autonomy | "You don't decide relevance. The checklist does." |
| Your job is to X, not Y | Define role boundaries | "Your job is to VERIFY, not to ASSUME" |
Escalation Phrases
| Phrase | When to Use | Example |
|---|---|---|
| ESCALATE TO | Define escalation path | "ESCALATE TO orchestrator if blocked" |
| REPORT BLOCKER | Communicate impediment | "REPORT BLOCKER and await user decision" |
| AWAIT USER DECISION | Pause for human input | "STOP. AWAIT USER DECISION on architecture" |
| ASK, DO NOT GUESS | Prevent assumptions | "When uncertain, ASK. Do not GUESS." |
Template Patterns
For Mandatory Sections
## Section Name (MANDATORY)
**This section is REQUIRED. It is NOT optional. You MUST include this.**
For Blocker Conditions
**If [condition] → STOP. DO NOT proceed.**
Action: STOP immediately. Report blocker. AWAIT user decision.
For Non-Negotiable Rules
| Requirement | Cannot Override Because |
|-------------|------------------------|
| **[Rule]** | [Reason]. This is NON-NEGOTIABLE. |
For Anti-Rationalization Tables
| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "[Excuse]" | [Why incorrect]. | **[MANDATORY action]** |
Task Tool Invocation (Agent Dispatch)
When a skill or workflow needs to dispatch an agent, the Task tool MUST be used explicitly. Agent dispatch is NOT implicit - if the Task tool is not called, no agent is dispatched.
Why Explicit Invocation Is Required
| Implicit (WRONG) | Explicit (CORRECT) |
|---|---|
| Describing what agent should do | Using Task tool to dispatch agent |
| YAML-like templates without tool call | Task tool with exact parameters |
| "The agent will analyze..." | "Use Task tool to dispatch agent" |
| Agent runs automatically | Agent runs ONLY when Task tool called |
If Task tool NOT used → Agent NOT dispatched → SKILL FAILURE
Template Structure
When documenting agent dispatch in skills, use this explicit format:
### Explicit Tool Invocation (MANDATORY)
**⛔ You MUST use the Task tool to dispatch [agent-name]. This is NOT implicit.**
```text
Action: Use Task tool with EXACTLY these parameters:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Task tool parameters: │
│ │
│ subagent_type: "[fully-qualified-agent-name]" │
│ description: "[short description]" │
│ prompt: [See prompt template below] │
│ │
│ ⛔ If Task tool NOT used → [artifact] does NOT exist → SKILL FAILURE │
└─────────────────────────────────────────────────────────────────────────────────┘
VERIFICATION: After Task completes, confirm agent returned output before proceeding
If Task Tool NOT Used → SKILL FAILURE
Agent is NOT dispatched → No output generated → All subsequent steps produce INVALID output.
### Required Elements
| Element | Required? | Purpose |
|---------|-----------|---------|
| **"Use Task tool"** | ✅ YES | Explicit tool instruction |
| **subagent_type** | ✅ YES | Fully qualified agent name |
| **description** | ✅ YES | Short task description |
| **prompt** | ✅ YES | Instructions for the agent |
| **SKILL FAILURE warning** | ✅ YES | Consequence of not using tool |
| **VERIFICATION step** | ✅ YES | Confirm output before proceeding |
### Anti-Rationalization
| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "Template implies Task tool" | Implication ≠ instruction. Be explicit. | **Write "Use Task tool"** |
| "Agent dispatch is obvious" | Obvious to you ≠ obvious to executor | **Add explicit parameters** |
| "I described what agent does" | Description ≠ invocation | **Call Task tool explicitly** |
| "Previous steps used Task tool" | Each dispatch is independent | **Explicit for EACH agent** |
---
## Code Transformation Context (CTC) Format
When documenting refactoring issues, agents MUST provide a Code Transformation Context block for EACH non-compliant issue. This gives execution agents exact before/after code context.
### Required Elements Checklist
For EACH issue, output MUST include:
- [ ] **Before (Current Code)** - Actual code extracted from the project with `file:line` reference
- [ ] **After (Ring Standards)** - Transformed code following Ring/Lerian standards
- [ ] **Standard References table** - Pattern, Source file, Section name, Line range
- [ ] **Why This Transformation Matters** - Problem, Standard violated, Impact
### Template Structure
```markdown
## Code Transformation Context: ISSUE-XXX
### Before (Current Code)
```{language}
// file: {path}:{start_line}-{end_line}
{actual code from project}
After (Ring Standards)
// file: {path}:{start_line}-{new_end_line}
// ✅ Ring Standard: {Pattern Name} ({standards_file}:{section})
{transformed code using lib-observability patterns}
Standard References
| Pattern Applied | Source | Section | Line Range |
|---|---|---|---|
| {pattern} | {file}.md | {Section Title} | :{derive_at_runtime} |
Why This Transformation Matters
- Problem: {current issue}
- Ring Standard: {which standard violated}
- Impact: {business/technical impact}
### Line Range Derivation (MANDATORY)
**⛔ DO NOT hardcode line numbers.** Standards files change over time.
**REQUIRED:** Derive exact `:{line_range}` values at runtime by:
1. Reading the current standards file (e.g., `golang.md`, `typescript.md`)
2. Searching for the relevant section header
3. Citing the actual line numbers from the live file
**Example derivation:**
Agent reads golang.md → Finds "## Configuration Loading" at line 99 Agent cites: "Configuration Loading (golang.md:99-230)"
### Anti-Rationalization
| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "Comparison table is enough" | Table = WHAT. Context = HOW. Both REQUIRED. | **Add CTC block** |
| "I'll describe the change" | Description ≠ executable context | **Show actual code** |
| "Standards are obvious" | Obvious to you ≠ obvious to executor | **Include Standard References** |
| "One example is enough" | Each issue needs its OWN context | **Add CTC for EACH issue** |
---
## Key Principle
The more assertive and explicit the language, the less room for AI to rationalize, assume, or make autonomous decisions. Strong language creates clear boundaries.
---
## Semantic Block Tags (Recognition Patterns)
**Use XML-like tags to create recognizable blocks for critical instructions.** Tags create semantic boundaries that AI models recognize as structured blocks requiring special attention.
| Tag | Purpose | AI Behavior |
|-----|---------|-------------|
| `<fetch_required>` | URLs to load before task | WebFetch all URLs first |
| `<block_condition>` | Blocker triggers | STOP if any condition true |
| `<forbidden>` | Prohibited actions | Reject if detected |
| `<dispatch_required>` | Single agent invocation | Use Task tool with specified agent |
| `<parallel_dispatch>` | Multiple agents in parallel | Dispatch all listed agents simultaneously |
| `<verify_before_proceed>` | Pre-conditions | Check all before continuing |
| `<output_required>` | Mandatory output sections | Include in response |
| `<cannot_skip>` | Non-negotiable steps | No exceptions allowed |
| `<user_decision>` | Requires user input | Wait for explicit response |
### Example Usage
```markdown
## Required Resources
<fetch_required>
https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md
https://raw.githubusercontent.com/LerianStudio/ring/main/CLAUDE.md
</fetch_required>
MUST fetch all URLs above before starting the task.
---
<block_condition>
- PROJECT_RULES.md not found
- Coverage below 85%
- Any reviewer returns FAIL
</block_condition>
If any condition is true, STOP immediately and report blocker.
---
<forbidden>
- fmt.Println() in Go code
- console.log() in TypeScript
- Direct source code editing by orchestrator
</forbidden>
Any occurrence = IMMEDIATE REJECTION.
---
<dispatch_required agent="ring:backend-engineer-golang">
Implement user authentication endpoint with JWT validation.
</dispatch_required>
MUST use Task tool with specified agent.
---
<parallel_dispatch agents="ring:backend-engineer-golang, ring:backend-engineer-typescript, ring:code-reviewer">
Analyze codebase against Ring standards. Backend engineers own implementation quality, coverage, local runtime, and health/observability checks in the active dev-cycle. All agents receive same context:
- Codebase Report: docs/ring:dev-refactor/{timestamp}/codebase-report.md
- Project Rules: docs/PROJECT_RULES.md
</parallel_dispatch>
MUST dispatch all listed agents simultaneously in one message.
Why Tags Work
- Clear boundaries - AI recognizes start/end of critical blocks
- Semantic meaning - Tag name conveys intent
- Parseable - Can be programmatically validated
- Consistent pattern - Same tag = same behavior across all prompts
Related Documents
- CLAUDE.md - Main project instructions (references this document)
- AGENT_DESIGN.md - Agent output schemas and requirements
- WORKFLOWS.md - Workflows (skills, pre-dev, lean dev-cycle, code review)