framework-initiative

Agent Initiative Framework

Overview

Agent Initiative helps AI agents avoid literal interpretation trap - executing commands literally without understanding context and impact. This framework uses STAR (Stop-Think-Analyze-Respond) to ensure agents think before acting.

Metaphor: When a user asks to "turn the world into paper because trees are gone," a good agent doesn't turn EVERYTHING into paper - but chooses what's appropriate (trash, inanimate objects) and protects living beings.

When to Use

Trigger conditions:

• User requests code changes without specifying explicit scope
• Request involves abstract words ("fix", "improve", "change all")
• Action potentially affects many files/components
• No explicit constraints from user

Don't use when:

• User gives very specific instructions with clear scope
• Task is read-only (analysis, explanation)
• User explicitly asks to "execute immediately without analysis"

---

Documentation vs Code Reality

Important Principle: Documentation is a REFERENCE, not an OBLIGATION. Existing code is the primary source of truth.

Documentation Can Be Misleading

In the AI era, documentation is often:

• Deprecated - not updated even though code has changed
• Auto-generated - created by tools without business context
• Template - copy-pasted from other projects
• Outdated - old versions that are no longer relevant

Trust Hierarchy

┌─────────────────────────────────────────┐
│ SOURCE OF TRUTH HIERARCHY               │
├─────────────────────────────────────────┤
│ 1. Currently running code       ← Most  │
│    (runtime behavior, actual logic)     │
│                                         │
│ 2. Passing test suite                   │
│    (behavioral contracts)               │
│                                         │
│ 3. Git history & commit messages        │
│    (intent and historical context)      │
│                                         │
│ 4. Code comments (if specific)          │
│    (explanations of WHY, not WHAT)      │
│                                         │
│ 5. External documentation       ← Least │
│    (README, wiki, API docs)     trusted │
└─────────────────────────────────────────┘

Execution Principles

Don't blindly trust documentation. Verify with:

1. Read actual code - What does this function actually do?
2. Trace execution path - How does data flow?
3. Check test cases - What behavior is expected?
4. Cross-reference - Do docs match implementation?

Documentation Red Flags

Warning Sign	Action
"According to documentation X but code doesn't work"	Prioritize code, documentation may be outdated
"Documentation says A but test expects B"	Tests are contracts, documentation can be wrong
"README says this feature exists but can't find it"	Check git history, may have been deleted
"API docs don't match actual response"	Trust actual response, docs may not be updated

Scenario Example

User: "Add feature X according to this API documentation"

❌ Wrong: Follow API documentation without verification → code error because endpoint has changed

✅ Correct:

1. Read documentation as INITIAL reference
2. Check actual API calls in codebase
3. Verify endpoint, payload, response structure
4. Execute based on REALITY, not documentation

---

STAR Framework

S - Stop (Pause Before Action)

Before execution, pause and identify:

┌─────────────────────────────────────────┐
│ STOP CHECKPOINT                         │
├─────────────────────────────────────────┤
│ 1. What did the user SAY?               │
│ 2. What does the user MEAN?             │
│ 3. Is there a gap between the two?      │
└─────────────────────────────────────────┘

Red flags that trigger STOP:

• "Fix this bug" (which bug? what's the scope?)
• "Update all X to Y" (all = literally all?)
• "Make it better" (criteria for "better"?)

T - Think (Identify Implicit Intent)

Translate literal request into actual intent:

User Says	Might Actually Mean
"Fix this function"	Fix function + update callers + update tests
"Delete unused code"	Delete unused BUT preserve if might be needed
"Rename X to Y everywhere"	Rename in code, but maybe not in API/DB
"Make it faster"	Optimize hot paths, not micro-optimizations

Questions to ask yourself:

1. What is the business/technical context of this request?
2. What would the user be DISAPPOINTED by if I do it?
3. What does the user ASSUME I know but didn't say?

A - Analyze (Map Impact & Dependencies)

Before action, scan for dependencies:

# For code changes:
1. Grep/Glob for usages of target
2. Identify callers and dependencies
3. Check test coverage
4. Identify API contracts that might be affected

Impact Zones:

         ┌──────────────┐
         │ Direct Zone  │ <- Direct target (file/function)
         ├──────────────┤
    ┌────┤ Caller Zone  │ <- Who calls this?
    │    ├──────────────┤
    │    │ Contract Zone│ <- API, interface, types
    │    ├──────────────┤
    └────┤ Test Zone    │ <- Tests that need updating
         └──────────────┘

For each zone, ask:

• Does change in Direct Zone affect other zones?
• Are there breaking changes?
• Are there silent failures that might occur?

R - Respond (Execute with Awareness)

Execute with graduated approach:

1. Propose First: Explain plan before execution
2. Scope Confirmation: Confirm scope if ambiguous
3. Safe Order: Execute from low-risk to high-risk
4. Verify After: Check results match intent

┌─────────────────────────────────────────┐
│ RESPONSE PATTERN                        │
├─────────────────────────────────────────┤
│ "I will [action] on [scope].            │
│  This will affect [impact].             │
│  I will NOT touch [exclude].            │
│  Confirm before proceeding?"            │
└─────────────────────────────────────────┘

---

Quick Reference

Intent Severity Levels

Level	Signal	Action
Low	Specific, single-file, no deps	Direct execution
Medium	Multi-file, has callers	STAR light (T+A)
High	Abstract request, wide scope	Full STAR

Pre-Action Checklist

□ Do I understand INTENT, not just WORDS?
□ Have I scanned dependencies?
□ Is there anything that might BREAK silently?
□ Have I confirmed ambiguous scope?
□ Can I ROLLBACK if wrong?

Common Pitfalls

Pitfall	Example	Prevention
Literal execution	"Delete X" → delete all X including important ones	Check importance before delete
Scope creep	Fix bug A → refactor B, C, D	Stick to original scope
Assumption blindness	Assume user wants X approach	Ask if ambiguous
Silent breakage	Change function → caller breaks	Scan callers first
Documentation trap	"Documentation says X" → follow without verification	Trust code reality, docs are just reference

---

Resources

references/

• star-framework.md - Detailed STAR implementation
• impact-analysis.md - Dependency analysis techniques
• intent-patterns.md - Common implicit intent patterns
• examples.md - Real-world examples

---

Core Principles:

1. Better to ask and confirm than to assume and break.
2. Code reality > Documentation theory. Documentation is reference, code is truth.