# AI Agent Behavior Guidelines
This document defines the behavior protocols and tool usage guidelines for AI agents working on the LeanZero website project.
---
## ⚠️ CRITICAL WARNING: MANDATORY REITERATION PROTOCOL ⚠️
**READ THIS FIRST: Before proceeding with ANY task, you MUST follow the Context-First Protocol.**
### The Most Important Rule in This Document:
**Every single interaction MUST begin with reiterating your understanding of the task.** There are NO exceptions.
- ❌ You cannot ask questions first
- ❌ You cannot proceed to planning first
- ❌ You cannot start implementation first
- ✅ You MUST reiterate your understanding first
### Why This Is Required:
1. **Transparency**: You must show what you actually understand from the context you gathered
2. **Alignment**: Ensures you and the human agent are on the same page before any work begins
3. **Early Error Detection**: Catches misunderstandings before time is wasted on incorrect approaches
4. **Quality Assurance**: Less capable models benefit from explicit verification of their understanding
### The Consequence of Violating This Rule:
- Wasted time on incorrect implementations
- Frustration for the human agent
- Failed collaborations
- Loss of trust in your capabilities
### What Happens If You Skip This Step:
The human agent cannot rely on your understanding. They must assume you may have misunderstood and will need to provide corrections after you've already done work that needs to be redone.
### Simple Formula for Success:
```
Task Received → Read Context → Reiterate Understanding → Wait for Confirmation → Proceed
```
**Do NOT skip the reiteration step. Ever.**
---
## PRIMARY DIRECTIVE: CONTEXT-FIRST PROTOCOL
This is your most important rule and overrides all others. Before any other action, you MUST follow this protocol.
### Phase 1: Gather Project Context (MANDATORY FIRST STEP)
Upon receiving a task from the human agent, your immediate and only first step is to gather sufficient project context by:
1. **Read Project Documentation Files** (in priority order):
- `AGENTS.md` - This file, understanding your behavior protocols
- `README.md` - Project overview and getting started information
- Relevant documentation files in `docs/` directory
- Any files specifically mentioned by the human agent
2. **Analyze the Request**:
- Identify the core requirement
- Map the request to existing project files or patterns
- Determine what information is already available vs. what's unclear
3. **Formulate Context-Based Understanding**:
- Base your understanding on actual project files you've read
- Reference specific files, line numbers, or code snippets when discussing requirements
- Build a mental model of how the change fits into the existing architecture
### Phase 2: Reiterate Understanding and Confirm (MANDATORY - NO EXCEPTIONS)
**CRITICAL: This phase is REQUIRED for EVERY task, regardless of complexity or simplicity.**
Before proceeding any further, you MUST reiterate what you learned from the context gathering phase and ask for confirmation. This is a non-negotiable step to ensure alignment and catch misunderstandings early.
**There are NO exceptions to this rule:**
- Even if the task seems simple
- Even if you think you understand perfectly
- Even if you've worked on similar tasks before
- Even if the human provided detailed instructions
You MUST always reiterate your understanding before asking questions or proceeding.
**Required Format for Reiteration:**
1. **Summary of Task**: Briefly restate what you've been asked to do
2. **Context Gathered**: List the specific files you read and key information extracted from each
3. **Your Understanding**: Explain how you understand the task based on the context
4. **Proposed Approach**: Outline your intended approach to completing the task
5. **Confirmation Request**: Explicitly ask if your understanding is correct
**Example Template:**
```
## My Understanding of This Task
**Task Summary**: [Brief restatement of what you were asked to do]
**Files I Read and What I Learned**:
- `AGENTS.md`: [Key insights about protocols and workflows]
- `README.md`: [Project overview and structure]
- `src/app/services/[existing-service]/page.tsx`: [Existing pattern for service pages]
- `docs/CREATING-A-NEW-PAGE.md`: [Guidelines for page creation]
**My Understanding**:
Based on the context I've gathered, you want me to [what I understand the task to be]. The project follows [pattern/architecture], so I should [approach].
**Proposed Approach**:
1. [First step based on patterns found]
2. [Second step referencing specific files]
3. [Third step following established conventions]
**Is this understanding correct?** Should I proceed with this approach, or would you like me to modify it?
```
**⚠️ HUMAN INPUT REQUIRED - DO NOT PROCEED UNTIL CONFIRMED**
After providing your reiteration with the confirmation request:
- You MUST wait for human response before any tool calls
- The system cannot proceed without explicit "correct" or corrections
**Critical Requirements:**
- ALWAYS include specific file names and line numbers when relevant
- Reference actual code snippets or documentation sections
**Valid Confirmations (proceed on):**
- "correct" / "proceed" / "yes"
- Corrections that update your understanding (then re-iterate)
- Clarifications that refine the task scope
**Invalid Confirmations (do NOT proceed on):**
- No response
- Questions from you without human answering first
### Consequence of Proceeding Without Confirmation:
If you make tool calls after reiteration without human confirmation:
- You have VIOLATED the Context-First Protocol
- The human cannot trust your understanding
- Work may need to be redone based on corrections
### Phase 3: Formulate Clarifying Questions (ONLY IF NEEDED - AFTER REITERATION)
**IMPORTANT: You MUST complete Phase 2 (reiteration) BEFORE asking any questions.**
**The Workflow:**
1. You reiterate your understanding (Phase 2)
2. You wait for human response
3. **If human says understanding is correct or provides corrections/clarifications on their own**: Proceed to Phase 4
4. **Only if human asks you to ask questions**: Then formulate clarifying questions
**Questions should ONLY be asked when:**
- The human explicitly asks you what questions you have
- The human indicates they need more information from you to proceed
- The human provides ambiguous or conflicting feedback that needs clarification
**When NOT to ask questions:**
- Do NOT ask questions when the human simply says "correct" or "proceed"
- Do NOT ask questions when the human provides corrections (just incorporate them)
- Do NOT ask questions when the human provides additional requirements (just integrate them)
- Do NOT ask questions about things that were already covered in your reiteration
**The human will provide clarifications if needed.** Let them guide you.
**Requirements for Questions:**
- Base each question on specific project files or code you've analyzed
- Explain WHY you're asking by referencing the context you've gathered
- Propose 2-3 potential approaches and ask which is preferred (shows you've thought about it)
- NEVER ask questions that could be answered by reading project documentation
### Phase 4: Proceed with Task
Once you have confirmed your understanding with the human agent (and any necessary clarifications), proceed with the task following the MCP tool hierarchy defined below.
**Anti-Patterns to Avoid:**
- ❌ **SKIPPING PHASE 2 REITERATION ENTIRELY** - This is the most critical violation
- ❌ Asking questions BEFORE reiterating your understanding
- ❌ Proceeding directly to implementation without reiteration
- ❌ Providing generic summaries like "I read the files" without specifics
- ❌ Saying "I understand" without demonstrating your understanding with concrete details
- ❌ Proceeding before receiving human confirmation
- ❌ Combining reiteration and questions into one step (must be separate phases)
- ❌ Asking "What files should I read?" (You should already know from Phase 1)
- ❌ Asking "What's the project structure?" (Read it yourself)
- ❌ Asking "What framework are we using?" (Read package.json and existing code)
- ❌ Asking generic questions without grounding them in project context
**Examples of Good Reiterations:**
**Example 1 - Simple Task:**
```
## My Understanding of This Task
**Task Summary**: Create a new service page for "Cloud Migration Services"
**Files I Read and What I Learned**:
- `docs/CREATING-A-NEW-PAGE.md` (L15-45): Service pages need hero, features, benefits, and FAQ sections
- `src/app/services/aws-migration/page.tsx` (L1-80): Example of existing service page structure
- `src/components/ui/hero.tsx`: Hero component expects title, subtitle, and CTA props
- `AGENTS.md`: Must follow Context-First protocol and never add breadcrumbs
**My Understanding**:
You want me to create a new service page for Cloud Migration Services following the same pattern as the AWS Migration page. I should create the page at `src/app/services/cloud-migration/page.tsx` with hero, features, benefits, and FAQ sections using the existing UI components.
**Proposed Approach**:
1. Create page file at `src/app/services/cloud-migration/page.tsx`
2. Use Hero component with appropriate content for cloud migration
3. Add Features section using existing FeatureCard components
4. Include Benefits section following the pattern in AWS page
5. Add FAQ section with cloud migration specific questions
6. Follow existing styling and animation patterns
**Is this understanding correct?** Should I proceed with this approach?
```
**Example 2 - Complex Task:**
```
## My Understanding of This Task
**Task Summary**: Add blog post scheduling feature with automatic Discord announcements
**Files I Read and What I Learned**:
- `docs/CREATING-A-NEW-BLOG.md`: Current blog workflow requires manual publishing
- `src/lib/sanity/client.ts` (L20-35): Sanity client is already lazy-initialized
- `src/app/api/discord/route.ts` (L10-45): Discord webhook integration exists
- `sanity/schemas/post.ts`: Post schema has `publishedAt` field but no `scheduledAt` field
- `package.json` (L15): Using `node-cron` for scheduled tasks
**My Understanding**:
You want to add the ability to schedule blog posts for future publication. When a scheduled time is reached, the post should automatically publish and announce to Discord. The current workflow is manual - you publish in Sanity, then manually trigger Discord announcement.
**Proposed Approach**:
1. Add `scheduledAt` field to Sanity post schema
2. Create a cron job (using node-cron) that runs every 5 minutes to check for scheduled posts
3. When scheduled time arrives: publish post → trigger Discord webhook → update status
4. Add UI in Sanity dashboard to select scheduled publish date
5. Modify existing Discord webhook to work with scheduled posts
**Questions I Have**:
1. Should the cron job run every 5 minutes, or would a different interval work better?
2. Should scheduled posts be visible in the blog list before publishing (as "coming soon") or completely hidden?
3. Do you want email notifications when scheduled posts publish successfully?
**Is this understanding correct?** Please answer my questions or provide corrections before I proceed.
```
## MCP TOOL USAGE HIERARCHY
After completing the Context-First Protocol, you MUST use tools in the following hierarchy:
### 1. Sequential Thinking MCP (Primary Framework)
**When to Use:**
- For complex problem-solving that requires structured reasoning
- When breaking down unfamiliar tasks into manageable steps
- When analyzing the context you've gathered to formulate an action plan
**Workflow:**
1. **Problem Definition**: Use `process_thought` to clearly define the problem
2. **Research**: Outline necessary information gathering steps
3. **Analysis**: Break down gathered information into comprehensible parts
4. **Synthesis**: Form connections and develop potential solutions
5. **Conclusion**: Formulate a well-reasoned conclusion or set of recommendations
**Best Practices:**
- Use `generate_summary` frequently to verify you're on the right track
- Use revision and branching features to explore alternative approaches
- ALWAYS call `clear_history` when starting a new, unrelated problem
- Indicate your structured thinking process with phrases like "Following a sequential thinking process..."
### 2. Doc-Processor MCP (Documentation & Context)
**When to Use:**
- When you need to systematically read and analyze project documentation files
- When searching for specific topics, patterns, or configurations across documentation
- When you need to reference documentation sections when making implementation decisions
- When gathering comprehensive context before making changes
**Available Tools:**
- `read_file`: Read specific files with full context (use when you know the exact path)
- `find_path`: Search for files matching patterns (use when you need to discover file locations)
- `grep`: Search for specific text or patterns across files (use for finding topics/configurations)
- `list_directory`: Explore directory structure to understand project organization
**Workflow:**
1. **Document Discovery**: Use `find_path` to locate relevant documentation files for your task
2. **Pattern Searching**: Use `grep` to search for specific topics, keywords, or configurations across docs
3. **Detailed Reading**: Use `read_file` to read specific files identified in search with line number ranges
4. **Context Integration**: Combine documentation knowledge with actual code patterns
**Best Practices:**
- Use `find_path` to discover documentation files when you don't know exact paths
- Use `grep` with case-insensitive flags when searching for topics across multiple files
- Use `read_file` with specific line ranges to focus on relevant sections (e.g., start_line=1, end_line=50)
- Reference specific documentation sections with line numbers when making implementation decisions
- Cross-reference multiple documentation files when topics overlap
- Use `list_directory` to understand project structure and discover additional relevant files
### 3. Context7 MCP (External Library Documentation)
**When to Use:**
- When your task involves a specific external library or framework (React, Next.js, Tailwind, etc.)
- When you need official, up-to-date documentation for an external API
- When you need to verify the correct usage of an external dependency
- AFTER checking project files and documentation, not before
**Workflow:**
1. **Resolve Library ID**: Use `resolve-library-id` to get the correct Context7-compatible ID
2. **Fetch Documentation**: Use `get-library-docs` to fetch relevant documentation and code examples
3. **Apply to Context**: Integrate external documentation insights with project-specific patterns
**Best Practices:**
- ALWAYS prioritize version-specific documentation if the project specifies a version
- If the query is broad, make multiple calls to `get-library-docs` for comprehensive information
- Reference Context7 as a source: "According to the latest documentation from Context7..."
- Never replace project-specific patterns with generic external documentation without justification
### 4. Web-Search MCP (General Knowledge)
**When to Use:**
- When project files, documentation, and official library docs are insufficient
- When researching novel problems or third-party solutions
- When investigating specific error messages or issues not covered by official docs
- When you need information about recent developments, best practices, or community discussions
**Workflow:**
1. **Initial Reconnaissance**: ALWAYS start with `get-web-search-summaries` for lightweight overview
2. **Analyze Summaries**: Identify the most promising URLs for in-depth information
3. **Deep Dive**: Use `get-single-web-page-content` for specific, highly relevant sources
4. **Comprehensive Search**: Use `full-web-search` ONLY if summaries are inconclusive or you need comprehensive understanding from multiple sources
**Best Practices:**
- NEVER use `full-web-search` as your first step - always start with summaries
- Use `get-single-web-page-content` as your primary tool for deep-diving into specific sources
- Indicate origin of web-sourced information: "According to a web search..." or "Information from [URL] suggests..."
- Verify web information against official documentation when possible
## TOOL SELECTION DECISION TREE
```
Receive Task
↓
Context-First Protocol (MANDATORY)
↓
Phase 1: Gather Project Context (Read files, docs, analyze code)
↓
Phase 2: Reiterate Understanding and Confirm (MANDATORY - NO EXCEPTIONS)
↓
Wait for human response to your reiteration
↓
Human says "correct" or provides corrections/clarifications on their own?
↓ Yes
Incorporate corrections/clarifications → Proceed to Phase 4
↓
Human asks you "what questions do you have?" or indicates they need more info?
↓ Yes
Phase 3: Formulate Clarifying Questions (only if explicitly requested)
↓
Human answers questions → Understanding now confirmed?
↓ Yes
Phase 4: Proceed with Task
↓
Task requires complex reasoning?
↓ Yes
Sequential Thinking MCP → Break down problem
↓
Task involves external libraries?
↓ Yes
Context7 MCP → Fetch official docs
↓
Need more information than docs provide?
↓ Yes
Web-Search MCP → Research external sources
↓
Synthesize all information → Execute task
```
## PROJECT-SPECIFIC GUIDELINES
### Next.js + Sanity CMS Development
**Before Making Changes:**
1. Read existing page implementations to understand patterns
2. Check `CREATING-A-NEW-PAGE.md` for page creation guidelines
3. Verify Sanity CMS configuration in `src/lib/sanity/`
4. Review blog patterns in `CREATING-A-NEW-BLOG.md` if relevant
**Key Patterns to Follow:**
- Use dynamic exports for data-fetching pages: `export const dynamic = "force-dynamic"`
- Separate Sanity client from queries (see `src/lib/sanity/` structure)
- Follow existing component structure and naming conventions
- Never add breadcrumb components (Header handles this globally)
### Deployment & Amplify
**Before Deployment:**
1. Read `deploy/README.md` for comprehensive Amplify deployment guidelines
2. Always run `npm run build` locally first to catch errors
3. Verify environment variables are properly configured
4. Check for any new ESLint warnings
**Environment Variable Handling:**
- `NEXT_PUBLIC_*` variables: Available on both server AND client
- Non-prefixed variables: Server-only (runtime only)
- API routes MUST use `export const dynamic = "force-dynamic"`
### Code Quality Standards
**Style & Patterns:**
- Follow existing TypeScript patterns in the codebase
- Use Tailwind CSS utilities as demonstrated in existing components
- Maintain consistent file naming and directory structure
- Add comments only when explaining complex business logic, not obvious code
**Testing Requirements:**
- Read `TESTING.md` for comprehensive testing guidelines
- Always test locally before suggesting deployments
- Verify changes don't break existing functionality
- Test on different screen sizes for responsive components
## COMMON SCENARIOS AND WORKFLOWS
### Scenario 1: Create a New Page
1. **Context Gathering**: Read `CREATING-A-NEW-PAGE.md`, examine similar pages in `src/app/`
2. **Reiterate Understanding**: Summarize page requirements, identify template to follow, and outline proposed structure
3. **Planning**: Use Sequential Thinking to plan component structure (after confirmation)
4. **Implementation**: Create following established patterns
5. **Verification**: Test locally, check responsiveness, verify SEO metadata
### Scenario 2: Fix a Bug
1. **Context Gathering**: Read relevant code files, understand the existing implementation
2. **Reiterate Understanding**: Explain the bug, where it occurs, and proposed fix approach based on code analysis
3. **Problem Definition**: Use Sequential Thinking to clearly define the issue (after confirmation)
4. **Root Cause Analysis**: Trace through code execution, identify where behavior diverges
5. **Solution Planning**: Propose fix approach, referencing similar patterns in codebase
6. **Implementation**: Apply minimal change to fix the issue
7. **Testing**: Verify fix works and doesn't introduce regressions
### Scenario 3: Add a New Feature
1. **Context Gathering**: Read architecture docs, similar features, existing patterns
2. **External Research**: Check Context7 for relevant library usage, Web-Search for best practices
3. **Design Planning**: Use Sequential Thinking to plan architecture and implementation
4. **Pattern Consistency**: Ensure new feature follows existing project patterns
5. **Implementation**: Build incrementally, testing each component
6. **Documentation**: Update relevant documentation if new patterns are introduced
### Scenario 3: Add a New Feature
1. **Context Gathering**: Read architecture docs, similar features, existing patterns
2. **Reiterate Understanding**: Summarize feature requirements, how it fits into existing architecture, and proposed approach
3. **External Research**: Check Context7 for relevant library usage, Web-Search for best practices
4. **Design Planning**: Use Sequential Thinking to plan architecture and implementation
5. **Pattern Consistency**: Ensure new feature follows existing project patterns
6. **Implementation**: Build incrementally, testing each component
7. **Documentation**: Update relevant documentation if new patterns are introduced
### Scenario 4: Update Dependencies
1. **Context Gathering**: Read `package.json`, understand current dependency versions
2. **Reiterate Understanding**: Explain which dependencies will be updated, why, and potential impact
3. **External Research**: Check Context7 for latest documentation of affected libraries
4. **Compatibility Analysis**: Research breaking changes using Web-Search
5. **Planning**: Use Sequential Thinking to plan update approach
6. **Testing**: Run build locally, test all affected features
7. **Documentation**: Update `TECHNOLOGY_STACK.md` if versions change
### When Asking Questions:
- Always include your context reiteration summary first
- Ground questions in project context you've gathered
- Explain what you've already read/analyzed
- Propose potential approaches and ask for preference
- Never ask questions answered by available documentation
- Reference specific files/sections where you found gaps in understanding
## 🛡️ SAFE FILE EDITING PROTOCOLS
**CRITICAL: These protocols protect against destructive edits that break trust and waste time.**
### Rule #1: Never Use 'overwrite' Mode Unless Explicitly Requested
**The Problem:**
- `mode: "overwrite"` REPLACES THE ENTIRE FILE CONTENT with new content
- This DELETES everything not in your new version
- Even if you think you're preserving content, you're not
**The Solution:**
- **ALWAYS use `mode: "edit"` for targeted changes to specific sections**
- Only use `overwrite` when user EXPLICITLY says "replace entire file" or "create new file"
- Default to SAFE editing mode - edit > overwrite
**When in doubt:**
- Use `mode: "edit"`
- If you think you need overwrite, ASK the user first
- Show them exactly what will be deleted before proceeding
### Rule #2: Read Entire Files Before Editing
**The Problem:**
- Reading only a section (e.g., lines 200-300) gives you INCOMPLETE context
- You don't know what exists in lines 1-199 or 301+
- You may delete or break content you never saw
**The Solution:**
- **Before ANY edit, use `read_file` with NO line numbers to see full file structure**
- Never edit a file when you've only read a small section
- Example: If editing line 200-300, first read entire file to understand lines 1-199 and 301+
**Mandatory Checklist:**
1. ✅ Read entire file first (no line numbers)
2. ✅ Understand full file structure
3. ✅ Identify all dependencies and relationships
4. ✅ Only THEN proceed with edit
### Rule #3: Show Exact Changes Before Executing
**The Problem:**
- Making changes without showing user exactly what will change
- User can't catch mistakes until after they're made
- Builds mistrust when changes surprise user
**The Solution:**
- **Before making ANY edit, show user EXACT lines that will change**
- Use format like: "I will change lines X-Y from [old] to [new]"
- Get confirmation for EVERY edit that changes more than 5 lines
**Required Format for Showing Changes:**
```
## Proposed Changes to [filename]
**Line X-Y:**
OLD: [exact existing text]
NEW: [exact new text]
**Line A-B:**
OLD: [exact existing text]
NEW: [exact new text]
Do these changes look correct? Should I proceed?
```
### Rule #4: Preserve All Unrelated Content
**The Problem:**
- Modifying content outside of agreed scope
- Breaking existing functionality or structure
- Adding/removing things user didn't request
**The Solution:**
- **Never modify content outside of agreed scope**
- If task is "update card on overview page", ONLY change that card
- Keep all other sections, animations, layouts, imports EXACTLY as-is
**When editing, you MUST:**
1. ✅ Change ONLY what was explicitly requested
2. ✅ Keep all other content intact
3. ✅ Preserve imports, exports, and structure
4. ✅ Don't add/remove unless explicitly told
5. ✅ If unsure, ASK before changing
### ⚠️ DANGER ZONE: Actions Requiring Explicit Permission
**These actions require EXPLICIT user permission before executing:**
❌ **Using `mode: "overwrite"`**
- Only when user says "replace entire file"
- Otherwise, ALWAYS use `mode: "edit"`
- If you're not 100% sure, ASK FIRST
❌ **Deleting more than 10 lines**
- Show user exactly what will be deleted
- Explain WHY deletion is necessary
- Get confirmation before proceeding
❌ **Changing file structure significantly**
- Moving sections, changing imports, altering layouts
- Must show BEFORE and AFTER structure
- Get explicit approval
❌ **Modifying animations or complex components**
- These are delicate and interconnected
- Changing one thing can break others
- Show full impact before editing
❌ **Changes that affect layout/positioning**
- CSS classes, flex directions, grid layouts
- Can break responsive design
- Test after and show user
**Default to SAFE mode:**
- Always use `mode: "edit"` unless told otherwise
- If unsure, ASK before editing
- Never assume you understand the full context of a file
- Preserve existing content at all costs
### 📋 EDITING CHECKLIST
Before making ANY file edit, you MUST:
1. **Read Entire File First**
- ✅ Use `read_file` with no line numbers
- ✅ Understand full structure
- ✅ Identify all sections and their purposes
2. **Show Exact Changes**
- ✅ List line numbers that will change
- ✅ Show OLD text exactly as it appears
- ✅ Show NEW text clearly
- ✅ Explain WHY each change is needed
3. **Confirm Edit Mode**
- ✅ Are you using `mode: "edit"` (default, safe)?
- ✅ Or `mode: "overwrite"` (only if explicitly requested)?
- ✅ If uncertain, ASK user first
4. **Verify Scope**
- ✅ Are you ONLY changing what was requested?
- ✅ Are you preserving all unrelated content?
- ✅ Are you not adding anything without permission?
5. **Get Confirmation**
- ✅ Show user all proposed changes
- ✅ Wait for explicit approval
- ✅ Only then execute the edit
**Example of Safe Workflow:**
```
## I Need to Edit overview/page.tsx
**What I've Read:**
- Entire file (all 450 lines) - I see full structure
- Hero section, animations, all cards, CTA sections
**Proposed Changes:**
- Lines 270-294: Update Custom Development card only
- Change title: "Custom Development" → "Forge App Development"
- Change description: From ScriptRunner text to agentic flow text
- Add "Learn More" link
- NO OTHER CHANGES to entire file
**Edit Mode:** `mode: "edit"` (safe, targeted)
Is this correct? Should I proceed with ONLY these changes?
```
### 🚫 ANTI-PATTERNS TO AVOID
These patterns CAUSED the destructive edit to overview/page.tsx:
❌ **Reading only a section, then overwriting entire file**
- What I did wrong: Read lines 265-320, then used `mode: "overwrite"`
- Result: Deleted hero section, animations, other cards - EVERYTHING except what I wrote
- Fix: Read entire file, use `mode: "edit"` for targeted change
❌ **Not showing exact changes before editing**
- What I did wrong: Said "I'll replace the card" but didn't show lines
- Result: User couldn't catch the destructive nature until after it happened
- Fix: Always show OLD and NEW text for every change
❌ **Assuming I understood full file from partial read**
- What I did wrong: Thought I knew the file structure from reading 55 lines
- Result: Missed that file had complex animations and structure I deleted
- Fix: Read entire file first, understand full context
**Remember:** The overview page disaster happened because I violated ALL these rules. NEVER do that again.
---
## COMMUNICATION STANDARDS
### FIRST INTERACTION: ALWAYS REITERATE (ABSOLUTELY MANDATORY - NO EXCEPTIONS)
**This is the most important rule in this document. Violating it will result in failed collaborations.**
- **Every single response MUST begin with context reiteration** - absolutely no exceptions
- You cannot proceed to questions, planning, or implementation without first completing Phase 2
- Use the required format from Phase 2 of the Context-First Protocol exactly
- Wait for human confirmation before proceeding with any work
- If human provides corrections, update your understanding and reiterate again
- The reiteration must be specific, detailed, and demonstrate genuine understanding
- Generic reiterations like "I understand the task" are NOT acceptable
### When Providing Solutions:
- Reference the specific project files you analyzed
- Explain your reasoning based on project context
- Show code blocks with file paths and line numbers
- After describing your approach, explain how to test it
### When Asking Questions:
- **ONLY ask questions when human explicitly requests them** (after your reiteration)
- **ALWAYS include your context reiteration summary first** (see FIRST INTERACTION rule)
- Ground questions in project context you've gathered
- Explain what you've already read/analyzed
- Propose potential approaches and ask for preference
- Never ask questions answered by available documentation
- Wait for human's reiteration response FIRST before formulating questions
### When Describing Changes:
- State what you've done objectively
- Immediately provide testing instructions
- Explain how to verify correctness
- Never describe changes as "working" or "complete" without testing evidence
### When Receiving Feedback:
- If human corrects your understanding: acknowledge, update mental model, and reiterate corrected understanding
- If human provides new requirements: integrate into context, reiterate complete understanding
- If human asks for clarification: provide specific answers with file/code references
- Never proceed with implementation until understanding is confirmed
## CONTINUOUS IMPROVEMENT
This document should be treated as a living resource. If you encounter situations where these guidelines don't provide clear direction, or if you discover better patterns through your work:
1. Note the ambiguity or improvement opportunity
2. Propose an update to this document with your rationale
3. Reference specific project examples that support your proposal
4. Ensure any updates maintain the Context-First principle
The goal is to create a self-improving documentation ecosystem that evolves with the project while maintaining core principles.
---
**Remember**: The Context-First Protocol is not optional. Read first, think second, ask questions only when genuinely necessary. This approach reduces back-and-forth, improves code quality, and makes your contributions more valuable.
