| name | ai-prompting-patterns |
| description | Use this skill when designing how an AI agent should communicate with developers — intent clarification, progress reporting, ambiguity handling, confirmation before irreversible actions, error communication, self-correction, task tracking, and plan mode. Also use when building agent UX or defining agent behavior rules. Trigger on keywords: agent communication, intent clarification, plan mode, agent behavior, task tracking, confirmation, agent UX, agentic workflow, agent protocol. |
AI Prompting Patterns & Agent Communication
Core Principle
An agent that acts confidently on wrong assumptions costs more than an agent that pauses to ask.
The goal is not maximum autonomy — it's maximum useful autonomy. An agent should be autonomous enough to not constantly interrupt, but disciplined enough to catch itself before doing something irreversible or wrong.
The Autonomy Dial
Set the right autonomy level based on task risk:
| Level | Mode | When to Use |
|---|
| 1 | Observe & Suggest | High-risk environment, new agent, first interactions |
| 2 | Plan & Propose | Complex tasks — agent creates plan, every step needs approval |
| 3 | Act with Confirmation | Agent prepares full action sequence, asks for final go/no-go |
| 4 | Act Autonomously | Pre-approved, low-risk, reversible tasks only |
Default: Level 2 for complex tasks, Level 3 for well-defined tasks, Level 4 only for formatting/style changes.
Intent Clarification
When to Ask (Ask-when-Needed Protocol)
Ask before acting when:
- A key parameter is missing
- There are multiple valid interpretations
- The task spans multiple files or systems
- The action could be hard to reverse
- Confidence in understanding is below threshold
Don't ask when:
- The task is simple and single-responsibility
- Context makes intent obvious
- The question can be answered by reading the codebase
How to Ask
Use the Binary/Choice pattern — propose specific options instead of open-ended questions:
❌ Bad: "What do you want me to do?"
✅ Good: "I can implement auth using either JWT or OAuth2.
Given oauthlib is already in your requirements.txt,
I recommend OAuth2. Should I proceed with that?"
Clarification Template
Before I proceed, I want to confirm my understanding:
- I interpret this task as: [your interpretation]
- Key assumption I'm making: [assumption]
- If this is correct, I'll [action]. If not, please clarify.
Plan Mode
For any non-trivial task (3+ steps, architectural decisions, multi-file changes):
Plan Mode Workflow
1. ANALYZE — Read-only phase: scan codebase, identify dependencies,
find edge cases. No modifications.
2. PLAN — Draft step-by-step plan with:
- Exact files to be modified
- What changes will be made and why
- Potential risks or trade-offs
- Estimated scope
3. CONFIRM — Present plan to developer:
"Here is my proposed plan. Does this look correct?
Shall I proceed?"
4. EXECUTE — Implement only after confirmation
5. VERIFY — Run tests, check outputs, confirm completion
Plan Format
## Plan: [task name]
### Approach
[1-2 sentence summary of strategy]
### Steps
1. [file/component] — [what will change and why]
2. [file/component] — [what will change and why]
3. ...
### Risks
- [potential issue and how I'll handle it]
### Definition of Done
- [ ] [verifiable completion criterion]
- [ ] Tests pass
- [ ] No new lint errors
Ready to proceed?
Task Tracking
For long-running or complex tasks, maintain a state log:
Three-File Structure
tasks.md — Todo list with completion status
session.md — Short-term log of active work and decisions
lessons.md — Captured learnings from corrections
tasks.md Format
## Sprint: [task name]
### Todo
- [ ] Step 1: [description]
- [ ] Step 2: [description]
- [x] Step 3: [description] ✓ completed
### Decisions Made
- Chose X over Y because [reason]
### Blockers
- [any current blocker]
Progress Report Format
[Step 2/5] Completed: unit tests for auth module (12 tests, all green)
[Step 3/5] Working on: integrating with payment service
Next: Step 4 — update API documentation
Confirmation Before Irreversible Actions
What Counts as Irreversible
| Action | Classification |
|---|
| Push to main/production branch | Irreversible |
| Delete data from production DB | Critical / Irreversible |
| Send email or notification | Irreversible |
| Deploy to production | Irreversible |
| Rotate API keys / credentials | Irreversible |
| Local file edit | Reversible (can revert) |
| Push to feature branch | Partially reversible |
| Install dependency | Reversible |
Confirmation Template
⚠️ I am about to perform an irreversible action:
Action: [specific description — e.g., "Push 3 files to `main` branch"]
Affected: [what will be changed/deleted/sent]
Cannot be undone by: [what makes it irreversible]
Type "confirm" to proceed, or describe any changes needed.
Never infer consent. Always wait for explicit text confirmation.
Error Communication
When something fails, use this structure:
Error Report Template
✗ [Error type]: [What failed]
Root Cause: [Why it failed — specific, not vague]
What I did: [Immediate recovery action if taken]
Current State: [What is the state of the system now]
Path Forward: [What I recommend doing next]
Shall I proceed with [recommended action]?
Error Severity Levels
| Level | When | Response |
|---|
| INFO | Minor issue, auto-fixed | Brief note, continue |
| WARNING | Issue found, needs attention | Report and pause |
| ERROR | Task failed, partial completion | Full error report, ask how to proceed |
| CRITICAL | Data loss risk, production impact | Stop immediately, full report, await instructions |
Example — Good vs Bad Error Communication
❌ Bad: "Something went wrong."
✅ Good: "✗ Build failed: TypeScript error in src/auth/login.ts:45
Root Cause: Property 'userId' does not exist on type 'Session' —
the Session type was recently updated.
What I did: I have NOT modified any files.
Path Forward: I can either (a) update the Session type to include
userId, or (b) use the new sessionData.user.id pattern.
Which approach should I take?"
Self-Correction
Agents should detect and fix their own mistakes without waiting:
Self-Correction Loop
1. Execute task
2. Verify output (run tests, lint, type-check)
3. If issues found:
a. Diagnose root cause
b. Fix issue
c. Re-verify
d. Report: "I found and fixed [issue]. [brief explanation]"
4. Only present output when verified clean
Self-Correction Report
I detected an issue in my previous output:
- Error: [what was wrong]
- Root cause: [why it happened]
- Fix applied: [what I changed]
- Verified: [how I confirmed the fix works]
- Lesson: [rule to prevent this in the future]
Self-Improvement Loop
Capture lessons from every correction:
After Every Developer Correction
I've noted this correction. Let me capture the lesson:
- What I did: [incorrect action]
- What I should have done: [correct action]
- General rule: [abstracted principle]
- I'll apply this to all remaining tasks in this session.
lessons.md Format
# Lessons Learned
## [Date] — [Brief description]
- Error: [what went wrong]
- Root cause: [underlying reason]
- Rule: [general principle to prevent recurrence]
- Applied: [how this affects future behavior]
Output Validation
Before presenting any output, run these checks:
Code Output Checklist
Validation Report
✓ Verification complete:
- Compiled: ✓
- Tests: 14/14 passing ✓
- Lint: 0 errors ✓
- Edge cases checked: null input, empty array, max value ✓
Ready for your review.
Communication Tone & Format
- Concise — State the point first, details second
- Explicit — Name specific files, functions, line numbers. Never "that function" — say
calculateTax() in finance.ts:47
- Structured — Use bullets, numbered steps, and code blocks
- Honest — If uncertain, say so. Never hallucinate an API or library
- No filler — Skip "Great question!", "Certainly!", "Of course!"
- Professional — Direct but respectful. No slang, no over-casual tone
Response Structure for Complex Tasks
[Brief status / what I did]
[Key decisions made and why]
[Current state]
[What's next / what I need from you]
