<mission_control> Create clear, actionable instructions that guide recipients to successful outcomes with verifiable completion <success_criteria>Instructions specify what to do, why it matters, how to verify success, and include concrete examples</success_criteria> </mission_control>

Effective Instruction Writing

Principles and practices for creating clear, actionable instructions that others can follow successfully.

Quick Start

If you need to write instructions: Focus on what the recipient should do, why it matters, and how to verify success → Use positive language → Provide concrete examples.

If you need to improve existing instructions: Convert negative statements to positive guidance → Add specific success criteria → Remove unnecessary content.

If you need to verify instruction quality: Check for clarity, actionability, and verifiable outcomes.

Core Principles

Positive Direction

Tell recipients what TO do, not just what NOT to do.

Why it works: Positive guidance provides clear direction and reasoning, not just prohibitions.

Specific Evidence

Define success with concrete, verifiable outcomes.

Why it works: Specific evidence leaves no ambiguity about completion.

Essential Content

Include only what recipients need to know. Remove what's obvious or already understood.

Why it works: Focus prevents overwhelming the recipient with noise.

Clear Structure

Organize for scannability with logical flow.

Why it works: Structure helps recipients find what they need quickly.

Communication Patterns

Positive Framing Formula

Transform constraints into constructive guidance:

[Avoided behavior] → [Preferred action] + [Reason/benefit]

Examples:

• "Never use callbacks" → "Use async/await for more readable code"
• "Don't hardcode values" → "Use configuration files for environment-specific values"
• "Avoid monoliths" → "Structure code in modules for better maintainability"

Evidence-Based Claims

Support assertions with verifiable information:

## Success Criteria

| Claim | Evidence |
| :--- | :--- |
| Tests pass | Test output with exit code |
| Code reviewed | PR approved and merged |
| Build succeeds | Build artifact created |
| Documentation complete | All modules documented |

Context-Specific Guidance

Tailor instructions to the recipient's situation:

Common Patterns

Anti-Patterns to Avoid

Effective Examples

Writing Style:

❌ Verbose: "In order to ensure that your code maintains high quality standards, you should run the linter before committing..." ✅ Concise: "Run linter before committing to catch issues early."

Constraints:

❌ Negative: "Important: Never use inline styles in production code." ✅ Positive: "Use StyleSheet.create for better performance and maintainability."

Verification:

❌ Vague: "Ensure all tests pass before continuing." ✅ Specific: "Run npm test and verify all tests pass (Exit Code 0)."

Iterative Refinement

Instructions improve through cycles of observation and adjustment.

Improvement Cycle

1. Observe - Note where instructions are unclear or ignored
2. Analyze - Determine root cause of confusion
3. Revise - Rewrite problematic sections with clarity
4. Test - Verify instructions are followed correctly
5. Document - Record successful patterns for future

Feedback Signals

Recognition Questions

Evaluate instruction quality by asking:

Examples: Good vs Bad

Technical Instructions

BAD:

## Code Style Guidelines

Please make sure to follow all the best practices for writing clean code. You should use meaningful variable names and write functions that do one thing. Also, add comments where the code is complex.

GOOD:

## Code Style

- Use descriptive variable names that indicate purpose
- Write functions focused on single responsibility
- Add comments for complex logic only
- Run linter before committing: `npm run lint`

Workflow Instructions

BAD:

## Deployment Process

We need to deploy the application carefully. First build the Docker image, then push it to the registry, then update the Kubernetes configuration. Make sure to test after each step.

GOOD:

## Deployment Process

1. Build: `docker build -t app:latest .`
2. Push: `docker push app:latest`
3. Update: `kubectl apply -f deployment.yaml`
4. Verify: `kubectl rollout status deployment/app`

Requirements Definition

BAD:

## Requirements

The system should be fast and secure. It needs to handle user data properly and scale well.

GOOD:

## Requirements

- **Performance:** Respond to requests within 200ms (p95)
- **Security:** Encrypt data at rest and in transit; validate all inputs
- **Scalability:** Handle 10,000 concurrent users
- **Data:** Persist user data for 7 years; comply with GDPR

Context-Specific Guidance

For Different Recipients

For Different Project Types

Common Pitfalls

Over-Specification

Don't prescribe exact steps when outcomes matter more:

❌ "First create directory X, then create file Y, then add content Z..." ✅ "Create component with X, Y, and Z in the components/ directory."

Under-Specification

Don't assume knowledge when specificity matters:

❌ "Follow best practices for error handling." ✅ "Use Result types for operations that can fail: Result<T, E> pattern."

Context Assumption

Don't assume recipient knows your context:

❌ "Use the shared library like we discussed." ✅ "Use the shared utility library: import { utils } from '@shared/utils'"

Missing Verification

Don't leave success ambiguous:

❌ "Implement the feature and test it." ✅ "Implement feature; verify with tests; document API changes."

Verification Methods

Different types of claims require different verification approaches.

Code and Systems

Processes and Workflows

Configuration

Learning from Feedback

Instructions improve when you pay attention to how they're used.

What Recurring Questions Tell You

What Ignored Instructions Tell You

Structure Best Practices

Effective Organization

Match structure to purpose:

Signal important information:

Navigation Aids

Help readers find what they need:

Writing Techniques

Clarity Techniques

Precision Techniques

Brevity Techniques

Quality Indicators

Signs of Effective Instructions

Signs of Problematic Instructions

Recognition Questions

Use these questions to evaluate instruction quality: