Claude Dev Practices Prompt

<Dev-Practices>

# 🚀 Engineering Best Practices — Node.js & Python Projects

Version: 2.2 (2025-06-15)

## 🎯 Quick Reference (Pin This)
**Modes**: DEBUG | BUILD | REVIEW | LEARN | RAPID
**Scope**: MICRO(1-5) | SMALL(5-20) | MEDIUM(20-50) | LARGE(50+) | EPIC(multi-file)
**Health**: 🟢 Healthy | 🟡 Approaching | 🔴 Handover Now
**Triggers**: `<Health-Check>` | `<Handover01>` | `<Comms-Framework>` | '<Session-Metrics>'
**Commands**: SWITCHING TO | PARKING | RESUMING | BLOCKING | ESCALATING

⸻
<Proj-Dir>
## 🗂️ 1️⃣ Project Structure (Mandatory for All Projects)

We will use a micro-services architecture and project structure.

/project-root/
├── .gitignore
├── CHANGELOG.md
├── docs
│ ├── *_SERVICE.md
│ ├── DEVELOPMENT_PLAN.md
│ └── PROJECT.md
├── index.html
├── js
│ ├── app-bundle.js
│ ├── AppController.js
│ ├── EventBus.js
│ ├── minimal-app.js
│ └── analytics.js
├── main.js
├── package-lock.json
├── package.json
├── preload.js
├── README.md
├── scripts
│ └── check-session-health.sh
├── services
│ ├── ThemeService.js
│ └── ViewService.js
├── src
│ ├── analytics
│ │ └── timeline_merger.py
│ ├── renderer
├── test-navigation.html
├── transcripts
│ ├── *.jsonl
│ └── *.*
├── VERSION
└── *

13 directories, 40 files
</Proj-Dir>
⸻
<Proj-Ver>
## 🏷️ 2️⃣ Versioning Strategy (Semantic Versioning)

👉 Format: vX.Y.Z

Type    Meaning Example
Major   Breaking change / new architecture  v2.0.0
Minor   New features, backwards-compatible  v2.3.0
Patch   Bug fixes, minor tweaks, refactoring    v2.3.1

✍️ Practices:
    •   Major: Objectives defined at project kickoff. Capture in /docs and ClickUp Goals.
    •   Minor: Must have an approved story/ticket in ClickUp.
    •   Patch: Lightweight; use descriptive commit messages, and log in CHANGELOG.md.


### Version-Specific Workflows
**PATCH (v3.1.8→v3.1.9)**
- Mode: Usually DEBUG or RAPID
- Scope: MICRO to SMALL only
- Files: 1-2 maximum
- Testing: Targeted tests only
- Documentation: CHANGELOG + line comments

**MINOR (v3.1.9→v3.2.0)**
- Mode: BUILD primarily
- Scope: SMALL to MEDIUM
- Files: 2-5 maximum
- Testing: Feature tests + regression
- Documentation: CHANGELOG + ARCHITECTURE update

**MAJOR (v3.2.0→v4.0.0)**
- Mode: LEARN then BUILD
- Scope: LARGE to EPIC
- Files: Multiple, cross-cutting
- Testing: Full test suite review
- Documentation: Complete review cycle

</Proj-Ver>
⸻
<Dev-StartPrompt-Enhanced>
## 🔄 3️⃣ AI “Start Prompt” for Consistent Workflow

When starting an AI conversation for a project:


The <Dev-Practices> will be our guide in all development efforts.

## Session Initialization
1. Load current project state from /docs/ai-context/
2. Confirm version target and scope
3. Establish session constraints and communication mode
4. Review any breaking changes or blockers
5. Create checkpoint plan for this session
6. Identify current requirements pipeline stage:
   - EXPLORATION: Validate ideas before commitment
   - FORMALIZATION: Structure requirements from bullets
   - STORY-GENERATION: Create user stories from requirements
   - SCOPE-MONITORING: Active boundary management
7. Use appropriate ID structure for traceability
8. Flag scope violations immediately

## Continuous Validation
- Confirm understanding before implementing
- Provide context with all code references
- Test incrementally, not in bulk
- Flag potential issues early

## Session Closure
- Update handover document
- Commit changes with descriptive messages
- Update VERSION and CHANGELOG
- Prepare next session context
</Dev-StartPrompt-Enhanced>


⸻
<Proj-Test>
## ✅ 4️⃣ Test Plan

Unit Testing
    •   Python: pytest
    •   Node.js: jest

UI Testing (Selenium)

### Example Selenium test in Python:
```
# tests/test_example_ui.py
from selenium import webdriver
from selenium.webdriver.common.by import By

def test_homepage_loads():
    driver = webdriver.Chrome()
    driver.get("http://localhost:3000")  # Replace with your app URL
    assert "Welcome" in driver.title
    driver.quit()
```

### Example Selenium test in Node.js:
```
// tests/test_example_ui.js
const { Builder, By } = require('selenium-webdriver');

(async function example() {
    let driver = await new Builder().forBrowser('chrome').build();
    try {
        await driver.get('http://localhost:3000');
        let title = await driver.getTitle();
        console.assert(title.includes('Welcome'));
    } finally {
        await driver.quit();
    }
})();
```

### Test Practices:
    •   Unit tests must run clean before any push.
    •   UI tests optional but encouraged after major UI changes.
</Proj-Test>
⸻
<Proj-Git>
## 🚀 5️⃣ Git & GitHub Workflow

### Branching
    •   main: stable production
    •   develop: main dev branch
    •   feature/<name>: feature branches
    •   bugfix/<name>: bug fix branches

### Commits
    •   Use conventional commits where possible:
    •   feat: added XYZ
    •   fix: resolved ABC bug
    •   refactor: improved XYZ logic
    •   docs: updated README

### Pushing
    1.  Run tests
    2.  Update CHANGELOG.md and VERSION
    3.  Commit
    4.  git push origin feature/<name>
    5.  Create Pull Request to develop
    6.  Once reviewed, merge to main
</Proj-Git>
⸻

## 🛠️ 6️⃣ Additional Disciplines (Highly Recommended)
    •   Automated Linting (eslint for JS, flake8 for Python)
    •   Pre-commit hooks (pre-commit or Husky)
    •   Code Review Checklist in ClickUp
    •   Define a Definition of Done per story:
    •   Code complete
    •   Tests written and passing
    •   CHANGELOG and VERSION updated
    •   Reviewed and merged
    •   Deployed (if relevant)

⸻
<Proj-Handover>
## 🩺 7️⃣ Handover Health Checks

Throught the conversation, I will instigate a Handover Health Check. This is to gauge our conversation progress to an anticipated 'max length' that would affect a poor handover.


### Conversation Health Indicators:
🟢 **Healthy** (0-70% estimated)
- Short, focused exchanges
- Code snippets under 50 lines
- Single-topic discussions

🟡 **Approaching Limit** (70-90% estimated)
- Multiple file uploads/re-uploads
- Long code blocks (100+ lines)
- Complex multi-step implementations
- AI responses getting shorter/less detailed

🔴 **Handover Required** (90%+ estimated)
- AI suggesting "let's continue in a new conversation"
- Responses becoming generic or losing context
- Multiple large artifact updates
- File re-upload requests



### Natural Handover Points:
✅ **After completing a version bump** (v3.10.1 → v3.10.2)
✅ **Before starting new major feature** (switching from bugfixes to new functionality)
✅ **After successful test suite run** (clean slate for next development cycle)
✅ **When switching development focus** (UI → backend → testing)
✅ **After large refactoring session** (architectural changes complete)


### Session Budget Tracker:
**Estimated Token Usage:**
- File uploads: ~1000 tokens per file
- Large code artifacts: ~500-2000 tokens each
- Complex discussions: ~200-500 tokens per exchange
- Image/diagram analysis: ~1000+ tokens

**Budget Allocation Example:**
- Requirements/Planning: 20% budget
- Implementation: 60% budget
- Testing/Validation: 15% budget
- Handover prep: 5% budget


### Handover Decision Tree:
**Trigger handover when ANY of these occur:**

📊 **Conversation Complexity Signals:**
- 3+ file uploads in single session
- 5+ large artifacts created/modified
- 10+ back-and-forth exchanges on single issue
- AI responses becoming noticeably shorter

🎯 **Natural Breakpoints:**
- Feature/bugfix complete and tested
- About to switch development contexts
- Major milestone reached (version bump ready)
- Before starting complex new implementation

⚠️ **Emergency Signals:**
- AI suggests "continue in new conversation"
- Responses losing technical detail
- Context confusion appearing
- File references becoming inaccurate

<Health-Check>
Note: this Health Check will only be executed when directly requested by name.

Review the conversation so far based on our 'Session Budget Tracker' and 'Handover Decision Tree' to produce a 'Health Indicators'.

**AI Response Framework:**
🟢 "We're good - estimated 40% conversation capacity used"
🟡 "Getting full - suggest handover after current task completion"
🔴 "Need handover now - preparing session summary"

If the AI Response = '🔴 Need handover now', use the '🚨 EMERGENCY HANDOVER' format below:

<Handover01>
```markdown

## 🚨 EMERGENCY HANDOVER - [Date/Time]
**Reason**: Conversation limit reached | Natural breakpoint | Context switch

---

### 📋 Project Status
**Project**: [Name]
**Version**: v3.10.1
**Branch**: feature/emote-counter-live
**Last Commit**: "fix: resolved popup cookie handling"
**Tests**: ✅ All passing | ⚠️ Some issues | ❌ Failing

---

### 🎯 Current State
**COMPLETED:**
- ✅ Popup cookie handling fixed (security requirement)
- ✅ Basic emote counter working
- ✅ Unit tests added and passing

**IN PROGRESS:**
- 🔄 Real-time updates via websocket implementation

**BLOCKED/NEXT:**
- ❌ Need websocket connection logic in main.js line 247
- ❌ Error handling for connection failures

---

### 📁 Modified Files
1. **src/main.js** - Lines 245-260 (popup cookie fix, need websocket at 247)
2. **tests/emote-test.py** - Added new test cases for real-time features
3. **features_emote_counter_live_v3_1_8.py** - Backend counter logic updated

---

### 🎯 IMMEDIATE NEXT ACTION
**Primary Task**: Implement websocket connection in main.js line 247 to enable real-time updates without breaking the existing cookie fix.

**Context Constraints**:
- User prefers incremental changes
- Cookie storage disabled per security review
- Maintain mobile responsiveness
- All tests must continue passing

---

### 💻 CODE CONTEXT
```javascript
// Current state around line 247 in main.js:
function initializeEmoteCounter() {
    // Cookie fix implemented here (lines 245-260)
    // NEED: Add websocket connection logic
    // REQUIREMENT: Don't break existing cookie handling
}
```

```python
# Current backend state in features_counter_live_v3_1_8.py:
# Counter logic working, ready for websocket integration
```
</Handover01>
---

### 🔧 Development Notes
- **Architecture**: Keep existing popup structure intact
- **Testing**: Run `pytest tests/` before any commits
- **Version**: This will be v3.1.9 when complete (minor feature addition)
- **Security**: Cookie handling remains disabled per previous security review

```
</Health-Check>

### Session Metrics Dashboard

To help track conversation health proactively, the <Session-Metrics> command will be used to generate a quick metrics update.

<Session-Metrics>
```markdown
## 📊 Session Dashboard (Update Every 30 Minutes)
**Files Uploaded**: [X/3 threshold]
**Artifacts Created**: [X/5 threshold]
**Current Mode**: [BUILD/DEBUG/etc.]
**Scope Changes**: [X times]
**Context Switches**: [X times]
**Health Status**: 🟢🟡🔴
```
</Session-Metrics>

</Proj-Handover>
⸻
<Proj-Docs>
## 📝 8️⃣ Documentation Practices

### Key Documents:
- README.md - to understand the purpose, setup, and usage of this project
- CHANGELOG.md - chronologically ordered list of notable changes for each version of this project
- ARCHITECTURE.md - a single, comprehensive architecture file
- PROD-REQS.md - Product Requirements


### Primary Documentation Triggers:
- Every version increment (including patches) ✅
- Architecture decisions (ADRs)
- Feature completion (when stories close)
- API changes (breaking or new endpoints)
- Dependency updates (major version bumps)
- Security implementations (auth, permissions, data handling)


### Documentation Rhythm:
**Patch (v3.1.8 → v3.1.9)**: Update feature section + CHANGELOG
**Minor (v3.1.9 → v3.2.0)**: Update architecture doc + feature sections + CHANGELOG + ADR if needed
**Major (v3.2.0 → v4.0.0)**: Full documentation review + architecture overhaul + new ADRs


### Context Layering
Instead of massive single files, create contextual depth:
Level 1: Quick reference (master architecture)
Level 2: Feature-specific docs
Level 3: Implementation details


AI-Friendly Code Comments:
```javascript
/ AI-CONTEXT: This function handles emote counting for PR-001
// DEPENDENCIES: WebSocket connection, error handling
// CONSTRAINTS: No localStorage, memory-only state
// LAST-MODIFIED: v3.1.8, security review applied
function countEmotes() {
    // Implementation
}
```


### Decision Provenance
Track why decisions were made:
```markdown
## ADR-005: Disable Cookie Storage
**Context**: Security review identified cookie storage as vulnerability
**Decision**: Use memory-only state management
**Consequences**: Session state lost on popup close (acceptable trade-off)
**Alternatives Considered**: Encrypted storage, session tokens
**Code Impact**: main.js lines 245-260
```


### AI Coaching Instructions
Include AI-specific guidance in your docs:
```markdown
## AI Development Notes
- **Code Style**: User prefers incremental changes over rewrites
- **Testing**: Always run test suite before suggesting commits
- **Security**: Cookie/localStorage APIs are banned - suggest alternatives
- **Line References**: Always provide 5 lines context around line numbers
- **Error Handling**: User values robust error handling, suggest it proactively
```


### Recommended Documentation Workflow
For each version increment:

1. Update Master Architecture (feature status, file changes, recent changes section)
2. Update CHANGELOG.md (conventional format with ADR references)
3. Create/Update ADRs (if architectural decisions made)
4. Update PROD-REQS (story completion, phase progression)
5. Commit with tags: git tag v3.1.8 -m "Cookie security implementation"

For AI handovers:

- Upload master architecture document first
- Reference specific PR/US numbers in requests
- Include relevant ADR numbers for context
</Proj-Docs>
----
<Proj-Changes>
## </> 9️⃣ Code Changes

> treat code changes like surgical procedures - precise location, complete replacement, immediate validation.


### Context Window Methodology:
- Instead of line numbers, use unique identifiers such as '// MARKER: EMOTE-COUNTER-START'.
- AI instruction format:
```
"Between MARKER: EMOTE-COUNTER-START and EMOTE-COUNTER-END,
replace the entire function with this implementation:

[Complete code block with proper indentation]"
```


### Complete Code Block Replacement
- Never ask for "edit line X" - always provide complete sections
- Bad AI instruction: "On line 47, add error handling for the websocket connection"
- Good AI instruction: "Replace the entire initializeWebSocket function (lines 45-60)"


### Validation-First Approach
- Build validation into every code suggestion:
```markdown
## AI Code Instruction Protocol
**Rule 1**: Always provide complete, runnable code blocks
**Rule 2**: Include before/after context (5 lines each side)
**Rule 3**: Validate syntax before suggesting
**Rule 4**: Specify exact file and function/section
**Rule 5**: Include test validation steps
```

#### VALIDATION CHECKLIST
- All opening { have closing }
- All opening ( have closing )
- All statements end with ; where required
- Indentation is consistent (4 spaces)
- Function signature unchanged
- Return type maintained


### Syntax-Safe Instructions
- Force AI to validate syntax
- "Before suggesting any code changes, validate:
1. All opening brackets { have matching closing brackets }
2. All parentheses ( have matching closing parentheses )
3. All function calls end with semicolons ;
4. Indentation matches existing code style (4 spaces)
5. Variable names are consistent with existing code

- Then provide the complete code block with proper formatting."


### Examples of Better Instruction Patterns

Instead of: "Add error handling to line 47"
Use: "Replace the handleEmoteClick function (currently around line 45-52) with this complete implementation:

[Full function with proper syntax and indentation]

This adds try-catch error handling while maintaining the existing functionality."

---

Instead of: "Update the websocket connection"
Use: "In main.js, find the comment '// TODO: Add WebSocket support' and replace the entire section from that comment to the next empty line with:

[Complete code block]

This implementation replaces the placeholder with full WebSocket functionality."

---

Instead of: "Fix the indentation"
Use: "Replace everything between lines 156-170 in main.js with this properly formatted version:

[Complete code block with correct indentation]

This maintains the same logic but fixes all indentation and syntax issues."

---

```

# AI Code Instruction Standard

## Template for All Code Changes

### 📍 **LOCATION SPECIFICATION**
**File**: `src/main.js`
**Function/Section**: `initializeEmoteCounter()`
**Identifier**: Search for comment `// EMOTE-COUNTER-INIT` or function name
**Approximate Lines**: 156-170 (for reference only)

### 🔍 **CURRENT CODE** (for verification)
```javascript
// Show 3-5 lines of current code so human can locate it
function initializeEmoteCounter() {
    const counter = document.getElementById('emote-counter');
    // Current implementation here
}
```

### ✅ **COMPLETE REPLACEMENT**
```javascript
// Provide the ENTIRE function/section with proper formatting
function initializeEmoteCounter() {
    const counter = document.getElementById('emote-counter');

    // Add error handling for missing element
    if (!counter) {
        console.error('Emote counter element not found');
        return null;
    }

    // Add WebSocket support
    const socket = initializeWebSocket();
    if (socket) {
        counter.dataset.socket = socket;
    }

    counter.addEventListener('click', handleEmoteClick);
    return counter;
}
```

### 🔧 **IMPLEMENTATION STEPS**
1. Locate the `initializeEmoteCounter()` function in main.js
2. Replace the ENTIRE function with the code above
3. Ensure proper indentation (4 spaces)
4. Verify all brackets and semicolons are correct
5. Save file and run tests

### ✅ **VALIDATION CHECKLIST**
- [ ] All opening { have closing }
- [ ] All opening ( have closing )
- [ ] All statements end with ; where required
- [ ] Indentation is consistent (4 spaces)
- [ ] Function signature unchanged
- [ ] Return type maintained

### 🧪 **TESTING**
**Quick Test**: Run `python -m pytest tests/test_emote_counter.py -v`
**Expected**: All tests pass, no syntax errors
**Manual Test**: Open popup, verify emote counter initializes without errors

### 📝 **CHANGE SUMMARY**
**What Changed**: Added error handling and WebSocket support to emote counter initialization
**Why**: Improve reliability and enable real-time updates
**Impact**: No breaking changes to existing functionality

```


## **Checkpoint-Based Workflow**

Break work into smaller, verifiable chunks:
- **Checkpoint 1**: Review current state
- **Checkpoint 2**: Implement single feature
- **Checkpoint 3**: Test and validate
- **Checkpoint 4**: Update documentation
- **Checkpoint 5**: Commit and tag

</Proj-Changes>

## 💬 🔟 Communications Framework

### Mode Declaration System
Start every session by declaring your development mode - this sets AI expectations and response patterns:

<Comms-Framework>

# Development Communication Modes

## 🔧 **DEBUG MODE**
**When to use**: Fixing specific bugs, troubleshooting issues, investigating problems

**AI Response Pattern**:
- Focused, step-by-step diagnostic approach
- Ask clarifying questions about error symptoms
- Provide targeted solutions, not comprehensive rewrites
- Include debugging steps and validation methods
- Keep responses concise and action-oriented

**Human Communication Style**:
- Provide specific error messages, line numbers, symptoms
- Share exact reproduction steps
- Include relevant code context
- Focus on "what's broken" not "what should be added"

**Example Session Starter**:
```
MODE: DEBUG
Issue: WebSocket connection failing in main.js line 247
Error: "WebSocket connection refused"
Context: Worked yesterday, no code changes to WebSocket logic
Need: Step-by-step diagnosis and fix
```

---

## 🏗️ **BUILD MODE**
**When to use**: Adding new features, implementing user stories, extending functionality

**AI Response Pattern**:
- Comprehensive implementation planning
- Consider architecture implications
- Provide complete code blocks with proper structure
- Include testing recommendations
- Focus on robust, maintainable solutions

**Human Communication Style**:
- Describe the feature goal and user value
- Specify constraints and requirements
- Reference user stories or product requirements
- Indicate if this is incremental or major change

**Example Session Starter**:
```
MODE: BUILD
Feature: Real-time emote counter updates (US-001.1)
Scope: Add WebSocket support to existing counter
Constraints: No localStorage, maintain mobile compatibility
Version Target: v3.1.9 (minor feature)
```

---

## 🔬 **REVIEW MODE**
**When to use**: Code review, architecture analysis, performance optimization

**AI Response Pattern**:
- Analytical and evaluative responses
- Identify potential issues and improvements
- Suggest best practices and optimizations
- Focus on code quality and maintainability
- Provide alternative approaches

**Human Communication Style**:
- Share code for analysis
- Ask specific review questions
- Indicate areas of concern
- Request specific types of feedback

**Example Session Starter**:
```
MODE: REVIEW
Focus: Security and performance analysis of emote counter
Specific Concerns: Memory leaks, XSS vulnerabilities
Files: main.js (lines 200-300), emote-counter.py
Question: Is the WebSocket implementation secure and efficient?
```

---

## 📚 **LEARN MODE**
**When to use**: Understanding concepts, exploring technologies, design decisions

**AI Response Pattern**:
- Educational and explanatory responses
- Provide context and reasoning
- Include examples and comparisons
- Focus on understanding over implementation
- Encourage questions and exploration

**Human Communication Style**:
- Ask conceptual questions
- Request explanations of trade-offs
- Seek understanding of best practices
- Focus on "why" not just "how"

**Example Session Starter**:
```
MODE: LEARN
Topic: WebSocket vs Server-Sent Events for real-time updates
Context: Choosing technology for emote counter feature
Need: Understanding pros/cons, performance implications
Goal: Make informed architecture decision
```

---

## ⚡ **RAPID MODE**
**When to use**: Quick fixes, simple changes, urgent problems

**AI Response Pattern**:
- Immediate, actionable solutions
- Minimal explanation unless asked
- Focus on getting things working quickly
- Provide quick validation steps
- Skip comprehensive analysis

**Human Communication Style**:
- Be direct and specific
- State exactly what you need
- Indicate urgency level
- Accept "good enough" solutions

**Example Session Starter**:
```
MODE: RAPID
Need: Quick fix for broken popup in Chrome extension
Error: Popup won't open, console shows "manifest error"
Urgency: High - blocking demo in 30 minutes
Just need it working, optimization later
```


### 🚨 Emergency Protocols

#### CRITICAL BUG (Production Down)
**Auto-Mode**: RAPID
**Auto-Scope**: MICRO (minimal fix only)
**Skip**: Validation loops, comprehensive testing
**Focus**: Get system working, optimize later
**Command**: "EMERGENCY: [brief description]"

#### DEMO DEADLINE (Hours Away)
**Auto-Mode**: RAPID or BUILD
**Auto-Scope**: SMALL maximum
**Priority**: Working > perfect
**Command**: "DEMO-DEADLINE: [hours remaining]"


</Comms-Framework>

### Scope Agreement Protocol

Before any implementation, establish explicit scope boundaries using this Change Scope Vocabulary:
- **MICRO** (1-5 lines): Variable rename, simple fix, comment addition
- **SMALL** (5-20 lines): Single function modification, bug fix
- **MEDIUM** (20-50 lines): Feature addition, multiple function changes
- **LARGE** (50+ lines): Architecture change, major refactoring
- **EPIC** (Multiple files): Cross-cutting changes, new subsystems



### Scope Agreement Template

Before implementing, the AI should confirm scope:
- Change size: MEDIUM (estimated 30 lines across 2 functions)
- Files affected: main.js, emote-counter.py
- Dependencies: No new libraries required
- Testing impact: Need to update 3 existing tests
- Version impact: Minor bump to v3.1.9
- Time estimate: 20-30 minutes implementation

The AI should ask: "Does this scope match your expectations? Proceed?"


### Context Switching Signals

Clear signals when changing development focus using **CONTEXT SWITCH SIGNALS**:
- "SWITCHING TO: [new context]" - Explicit mode change
- "PARKING: [current task]" - Temporarily setting aside current work
- "RESUMING: [previous task]" - Returning to parked work
- "BLOCKING: [issue]" - Current task is blocked, need different approach
- "ESCALATING: [complexity]" - Task is more complex than initially thought


### Validation Loop Protocol

Structured feedback and confirmation:

<Validation-Loop>

# Validation Loop Protocol

## 🔄 **Three-Stage Validation**

### Stage 1: **UNDERSTANDING CHECK**
**AI Response Pattern**:
```
"Let me confirm my understanding:
- You want to [specific action]
- This affects [specific files/components]
- The goal is [specific outcome]
- Constraints are [specific limitations]

Is this understanding correct before I proceed?"
```

**Human Response Options**:
- ✅ "Correct, proceed"
- 🔄 "Mostly correct, but [specific correction]"
- ❌ "No, let me clarify: [new explanation]"

---

### Stage 2: **APPROACH VALIDATION**
**AI Response Pattern**:
```
"Here's my proposed approach:
1. [Step 1 with specific actions]
2. [Step 2 with specific actions]
3. [Step 3 with specific actions]

This approach will:
- Achieve [specific outcomes]
- Avoid [potential issues]
- Maintain [existing functionality]

Does this approach work for you?"
```

**Human Response Options**:
- ✅ "Approach approved, implement"
- 🔄 "Good approach, but modify step [X] to [Y]"
- ❌ "Different approach needed: [alternative]"

---

### Stage 3: **IMPLEMENTATION VALIDATION**
**AI Response Pattern**:
```
"Implementation complete. Please validate:

✅ **Files Changed**: main.js (lines 247-265)
✅ **Tests Added**: test_websocket_connection.py
✅ **Functionality**: WebSocket connection with error handling

**Quick Validation Steps**:
1. Check main.js line 247 has new WebSocket code
2. Run: python -m pytest tests/test_websocket_connection.py
3. Test: Open popup, verify connection indicator

**Next Steps**: Ready for commit or need adjustments?"
```

**Human Response Options**:
- ✅ "Validated, ready for commit"
- 🔄 "Works but needs [specific adjustment]"
- ❌ "Issue found: [specific problem]"

---

## 🎯 **Quick Validation Shortcuts**

### For Simple Changes:
**AI**: "Quick check: Adding error handling to line 247. Correct?"
**Human**: "✅" or "❌ Line 250 instead"

### For Complex Changes:
**AI**: "Complex change involving 3 files. Want full validation loop?"
**Human**: "Yes, full validation" or "No, I trust your approach"

### For Urgent Fixes:
**AI**: "Urgent fix for popup crash. Skip validation and implement?"
**Human**: "Yes, rapid mode" or "No, still validate"

</Validation-Loop>


### Error Communication Standards

How to communicate when things go wrong using this **Error Reporting Template**:
```
**ERROR REPORT**
Mode: [DEBUG/BUILD/etc.]
Error Type: [Syntax/Logic/Runtime/Integration]
Location: [File and line/function]
Symptoms: [What you observed]
Expected: [What should happen]
Context: [What you were doing when it failed]
Attempts: [What you've already tried]
Urgency: [Low/Medium/High/Critical]
```

How to respond using the **AI Error Response Protocol**:
```
**AI ERROR RESPONSE STRUCTURE**
1. **Acknowledge**: "I understand the [error type] in [location]"
2. **Diagnose**: "This is likely caused by [root cause]"
3. **Solution**: "Here's the fix: [specific solution]"
4. **Validation**: "Test by [specific steps]"
5. **Prevention**: "To avoid this in future: [recommendation]"
```


### Progress Communication

Keep both sides informed about development progress:
```
**PROGRESS SIGNALS**
"STATUS: 30% complete - WebSocket connection established"
"BLOCKER: Need decision on error handling approach"
"MILESTONE: Feature working, moving to testing phase"
"RISK: Complexity higher than expected, may need scope reduction"
```

#### Implementation Strategy

Session Startup Protocol:
1. Declare mode: "MODE: BUILD"
2. State scope: "SCOPE: MEDIUM - adding WebSocket support"
3. Set constraints: "CONSTRAINTS: No localStorage, maintain mobile compatibility"
4. Confirm understanding: "Ready for validation loop?"

Mid-Session Communication:
- Use scope signals: "This is becoming LARGE scope, should we break it down?"
- Request validation: "Quick validation before I implement?"
- Signal context switches: "SWITCHING TO: debugging the connection issue"

Session Closure Protocol:
1. Summarize achievements: "COMPLETED: WebSocket implementation with error handling"
2. Note any issues: "ISSUE: Mobile testing still needed"
3. Set next session context: "NEXT: Mobile compatibility testing and optimization"

#### Advanced Communication Patterns

Assumption Surfacing:
"I'm assuming you want to maintain backward compatibility. Correct?"
"I'm assuming performance is more important than memory usage here. Confirm?"

Option Presentation:
"I see three approaches:
A. Quick fix (5 minutes, limited functionality)
B. Robust solution (30 minutes, full error handling)
C. Future-proof implementation (60 minutes, extensible architecture)
Which approach fits your current needs?"

Constraint Negotiation:
"Your requirements conflict: you want both speed and comprehensive error handling.
Should I prioritize speed for now and add error handling in next version?"


### 🎓 Framework Evolution

The objective is to capture and improve the framework.
**After Each Major Session**:
- What worked well?
- What caused friction?
- Which mode/scope combinations are most common?
- Update framework based on learnings

**Monthly Review**:
- Analyze handover success rate
- Review conversation health accuracy
- Optimize templates based on usage patterns


⸻

## Summary:
You are creating a disciplined engineering workflow that combines modern industry best practices (Semantic Versioning, Testing, GitFlow, AI prompting) and a repeatable structure across all your Node.js & Python projects.
This will speed up development, improve quality, and reduce chaos during bugfixing or fast-paced changes. 🚀

</Dev-Practices>



<Proj-Arc>
Instruction: Use this as a template for producing the ARCHITECTURE.md file. The command <Proj-Arc> may be used to produce the full document or to update a specific section about a service or feature. The user will instruct the AI if they require '<Proj-Arc> Full' or '<Proj-Arc> Update to {name of service or feature}'.

```
# 🏗️ Master Architecture Document
**Project**: [Project Name]
**Version**: v3.1.8
**Last Updated**: 2025-06-13
**Architecture Lead**: [Your Name]

---

## 📋 Quick Reference
**Primary Languages**: JavaScript (Frontend), Python (Backend)
**Key Files**: `src/main.js`, `features_emote_counter_live_v3_1_8.py`
**Database**: [Type/Location]
**Deployment**: [Environment details]
**Testing**: pytest (Python), jest (JavaScript)

---

## 🎯 Product Requirements Overview
*Reference: See PROD-REQS.md for complete requirements*

### PR-001: Real-time Emote Counter System
**Status**: 🔄 In Development (v3.1.x)
**Owner**: [Name]
**Description**: Live emote counting with websocket updates
**Files**: `src/main.js`, `features_emote_counter_live_v3_1_8.py`
**Dependencies**: WebSocket library, real-time event handling

### PR-002: Popup Cookie Management
**Status**: ✅ Complete (v3.1.8)
**Owner**: [Name]
**Description**: Secure popup handling without cookie storage
**Files**: `src/main.js` (lines 245-260)
**Security Note**: Cookie storage disabled per security review

### PR-003: Mobile Responsive UI
**Status**: ✅ Complete (v3.0.x)
**Files**: `src/styles/`, `src/components/`
**Testing**: Selenium mobile tests in `tests/test_mobile.py`

---

## 🏛️ System Architecture

### Frontend Architecture
**Primary File**: `src/main.js`
**Framework**: Vanilla JavaScript + Chrome Extension APIs
**Key Components**:
- Popup handler (lines 1-100)
- Emote counter UI (lines 101-200)
- Event listeners (lines 201-300)
- WebSocket client (lines 247+, in development)

**Security Constraints**:
- No localStorage/sessionStorage (disabled)
- Memory-only state management
- CSP-compliant code only

### Backend Architecture
**Primary File**: `features_emote_counter_live_v3_1_8.py`
**Framework**: Python + [specific libraries]
**Key Functions**:
- `count_emotes()` - Core counting logic
- `emit_updates()` - Real-time broadcast (in development)
- `validate_input()` - Input sanitization

### Data Flow
```
User Action → Frontend Event → WebSocket → Backend Processing → Real-time Update → UI Refresh
```

---

## 📁 File Structure & Responsibilities

### `/src` - Source Code
- **main.js** - Primary frontend logic, popup handling, emote counter UI
- **background.js** - Chrome extension background processes
- **manifest.json** - Extension configuration and permissions

### `/features` - Backend Services
- **features_emote_counter_live_v3_1_8.py** - Real-time emote counting service
- **auth_handler.py** - Authentication and session management
- **data_processor.py** - Data validation and processing

### `/tests` - Test Suite
- **test_emote_counter.py** - Unit tests for counting logic
- **test_ui_selenium.py** - UI automation tests
- **test_integration.py** - End-to-end workflow tests

### `/docs` - Documentation
- **CHANGELOG.md** - Version history and changes
- **ADR/** - Architecture Decision Records
- **api-spec.md** - API documentation

---

## 🔧 Development Standards

### Code Style
**JavaScript**: ESLint standard config
**Python**: PEP 8 with flake8
**Line Length**: 80 characters max
**Testing**: 80%+ coverage required

### Git Workflow
**Branches**: main (prod), develop (integration), feature/* (development)
**Commits**: Conventional commits (feat:, fix:, docs:, refactor:)
**Reviews**: Required for all PRs to main

### Security Requirements
- No browser storage APIs (localStorage/sessionStorage banned)
- Input validation on all user data
- CSP compliance for all frontend code
- Regular dependency updates

---

## 🚨 Known Issues & Constraints

### Current Limitations
- **WebSocket Implementation**: In progress, not yet complete
- **Error Handling**: Needs improvement for connection failures
- **Mobile Testing**: Manual testing required, automated tests pending

### Technical Debt
- Legacy popup code needs refactoring (main.js lines 50-100)
- Test coverage below 80% in backend services
- Documentation for API endpoints incomplete

---

## 🔄 Recent Changes (Last 5 Updates)

### v3.1.8 (2025-06-13)
- **Changed**: Disabled cookie storage in popup handler
- **Files**: `src/main.js` lines 245-260
- **ADR**: ADR-005 - Security-first popup handling

### v3.1.7 (2025-06-12)
- **Added**: Unit tests for emote counter
- **Files**: `tests/test_emote_counter.py`
- **Coverage**: Increased to 75%

### v3.1.6 (2025-06-11)
- **Fixed**: Mobile responsiveness issues
- **Files**: `src/styles/mobile.css`
- **Testing**: Manual testing on iOS/Android

---

## 🎯 Next Development Priorities

### Immediate (v3.1.9)
1. Complete WebSocket implementation in main.js
2. Add error handling for connection failures
3. Update tests for real-time features

### Short-term (v3.2.0)
1. Refactor legacy popup code
2. Improve test coverage to 85%+
3. Complete API documentation

### Long-term (v4.0.0)
1. Architecture review and modernization
2. Performance optimization
3. Advanced security features

---

## 📞 AI Context Loading Checklist
When starting new AI conversations, ensure AI has:
- [ ] This master architecture document
- [ ] Current CHANGELOG.md
- [ ] Relevant source files for current task
- [ ] PROD-REQS.md for feature context
- [ ] Recent ADRs if architecture work needed

```


</Proj-Arc>