Command Best Practices

This document provides quality guidelines, writing style recommendations, common pitfalls, and a detailed template structure for creating effective slash commands.

Command Writing Style

Commands are executed by AI agents, so optimize for autonomous execution.

Writing Form

ALWAYS use imperative/infinitive form (verb-first instructions), not second person.

✅ CORRECT:

- "Run git status to check current branch"
- "Check if .PLAN.md exists before proceeding"
- "Use the Task tool with Bash tool"

❌ WRONG:

- "You should run git status"
- "You need to check if .PLAN.md exists"
- "You'll want to use the Task tool"

Specificity

Be explicit and specific, not vague.

✅ CORRECT:

- "Run make lint to check for linting errors"
- "Read src/config.py lines 45-67 to understand the config structure"
- "Use Edit tool to replace 'List[str]' with 'list[str]'"

❌ WRONG:

- "Check for errors"
- "Look at the config file"
- "Fix the type annotation"

Expected Outcomes

Include what should happen after each action.

✅ CORRECT:

- "Run git status - this should show modified files in src/ directory"
- "After running make format, all Python files should be formatted"
- "The output should contain PR URLs for each submitted branch"

❌ WRONG:

- "Run git status"
- "Run make format"
- "Submit the PRs"

Concrete Examples

Provide realistic examples, not placeholders like foo/bar.

✅ CORRECT:

- "Example: `git commit -m 'Add user authentication with OAuth2'`"
- "Example: `/submit-stack 'Implement caching for API responses'`"
- "If error shows: `src/erk/cli/commands/init.py:45: Type error`"

❌ WRONG:

- "Example: `git commit -m 'foo bar'`"
- "Example: `/submit-stack 'something'`"
- "If error shows: `file.py:123: Error message`"

Template Structure

Use this template structure for comprehensive commands:

---
description: [One-line description for /help output]
argument