# MANDATORY DEVELOPMENT PROTOCOL (MDP) v2.1 FINAL
Last Updated: 2025-09-06
Location: 3.7 Evidence Archive\MDP_Protocol\MDP_v2.md

Note: This is the final version. Keep it actionable, not bloated.

## ENFORCEMENT WARNING
Failure to follow this protocol = IMMEDIATE CHAT TERMINATION
No exceptions. No clever shortcuts. No cowboy coding.

## GOLDEN RULES
1. Investigation before fixes - COMPLETE Step 2 before ANY code changes
2. Data before code - Check if tables have data before assuming code problems  
3. Evidence of findings - Not every command, just what you learned
4. One fix at a time - Test completely before moving to next issue
5. Ask when unsure - Better to ask than break production

## THE 11 STEPS (MANDATORY SEQUENCE)

### STEP 1: CONTEXT & CONTROL
- Read Feature/CURRENT_STATE.md
- Check Cross_Feature_Issues/INDEX.md  
- Check for existing BUGS/[issue] folders
- State the problem clearly
- If scope unclear, STOP and ask

### STEP 2: INVESTIGATE COMPLETELY - CRITICAL
DO NOT SKIP OR RUSH THIS STEP
- Check if tables exist: SELECT * FROM information_schema.tables
- Check if data exists: SELECT COUNT(*) FROM [table]
- Check for existing seed scripts: Get-ChildItem -Filter "*seed*.py"
- Check for existing documentation in legacy MDs
- Test the actual UI, not just the API
- Find ALL related files and dependencies
- Document ALL findings in INVESTIGATION.md

### STEP 3: BACKUP & SAFETY

FOR CODE CHANGES:
- Git commit current state
- Document rollback procedure

FOR DATABASE CHANGES - MANDATORY:
1. Create full backup BEFORE any migrations or changes:
   Local: pg_dump -U postgres -d rateright_dev > backup_YYYY-MM-DD_HH-MM.sql
   Production: fly postgres backup -a rateright-db-v2

2. Verify backup is valid:
   - Check file size > 0
   - Confirm SQL content exists
   - Document backup location in INVESTIGATION.md

3. Document exact restore commands:
   Local: psql -U postgres -d rateright_dev < backup_YYYY-MM-DD_HH-MM.sql
   Production: fly postgres restore -a rateright-db-v2 [backup-id]

NO DATABASE CHANGES WITHOUT BACKUP = IMMEDIATE TERMINATION

### STEP 4: PLAN FIX
- Write complete fix plan based on investigation
- Document in SOLUTION.md (planned approach)
- Identify minimum viable fix
- Note expected side effects

### STEP 5: IMPLEMENT FIX
- Apply the planned fix
- One change at a time
- Add inline documentation

### STEP 6: LOCAL TEST
- Test the specific fix
- Test related functionality
- Verify no regressions

### STEP 7: AUTOMATED TESTS
- Run existing tests
- Add tests for the fix if missing

### STEP 8: STAGING TEST
- Deploy to staging if available
- Test integration

### STEP 9: DEPLOY
- Deploy to production
- Monitor logs during deployment

### STEP 10: VERIFY
- Test in production
- Confirm issue resolved
- Check for side effects

### STEP 11: DOCUMENT (CRITICAL LOCATION REQUIREMENT)
- Update CURRENT_STATE.md
- Finalize SOLUTION.md with working fix
- Create LESSONS.md with learnings
- Update Cross_Feature_Issues if relevant

## MANDATORY FILE LOCATION COMMANDS
CREATE ALL THREE FILES IN THIS EXACT LOCATION:
3.7 Evidence Archive\Features\[Feature_Name]\BUGS\BUG_[description]_[YYYY-MM-DD]\

REQUIRED COMMANDS IN ORDER:
1. Create folder structure:
   execute_command: mkdir "3.7 Evidence Archive\Features\[Feature]\BUGS\BUG_[issue]_[date]"

2. Create INVESTIGATION.md:
   write_to_file path="3.7 Evidence Archive\Features\[Feature]\BUGS\BUG_[issue]_[date]\INVESTIGATION.md"

3. Create SOLUTION.md:
   write_to_file path="3.7 Evidence Archive\Features\[Feature]\BUGS\BUG_[issue]_[date]\SOLUTION.md"

4. Create LESSONS.md:
   write_to_file path="3.7 Evidence Archive\Features\[Feature]\BUGS\BUG_[issue]_[date]\LESSONS.md"

NEVER create these files in root directory.
Files in wrong location = MDP violation = task failure.

## THREE FILES PER ISSUE

Every bug/issue MUST have these three files:

### 1. INVESTIGATION.md
What you found in Step 2:
- Tables checked
- Data presence  
- Error messages
- Related files
- Root cause

### 2. SOLUTION.md  
The fix that worked:
- Exact commands/changes
- Files modified
- Test commands
- Verification steps

### 3. LESSONS.md
What we learned:
- What went wrong
- What went right
- Time wasters
- Better approach for next time

## FILE STRUCTURE
Feature_Name/
  CURRENT_STATE.md              # Read this FIRST
  BUGS/
    BUG_description_YYYY-MM-DD/
      INVESTIGATION.md          # Step 2 findings (REQUIRED)
      SOLUTION.md              # The working fix (REQUIRED)
      LESSONS.md               # What we learned (REQUIRED)
      /evidence/               # Only meaningful evidence files

## INVESTIGATION CHECKLIST
Before proceeding to Step 3, confirm:
- Database tables checked for existence
- Row counts verified (not assuming empty)
- Existing seed/init scripts searched
- Error messages fully documented
- Related models/routes identified
- Foreign key relationships checked
- API endpoints tested
- UI actually clicked/tested
- Cross-feature impacts considered

## COMMON PITFALLS (AUTOMATIC FAILURE)
1. Assuming without checking - "Must be table name mismatch" (CHECK FIRST!)
2. Fixing before investigating - Making changes in Step 2
3. Not checking data - Assuming code is broken when table is empty
4. Declaring false success - "Fixed!" but did not test
5. 100 commands for 2-line fix - Investigation incomplete

## QUICK CHECKS BEFORE ANYTHING
SQL: SELECT table_name FROM information_schema.tables WHERE table_name LIKE '%keyword%';
SQL: SELECT COUNT(*) FROM table_name;
PowerShell: Get-ChildItem -Recurse -Filter "*seed*.py"
PowerShell: Get-ChildItem -Recurse -Filter "*init*.py"

## UTF-8 SETUP
$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8  
$env:PYTHONIOENCODING = "utf-8"

## WHEN TO STOP AND ASK
- Investigation reveals multiple interwoven issues
- Proposed fix could break authentication
- Three approaches tried without success
- Guessing instead of knowing
- Error does not make sense after investigation

## VIOLATIONS THAT END THE CHAT
- Applying ANY fix before completing investigation
- Making changes without INVESTIGATION.md
- Declaring success without testing
- Cowboy coding (fix-test-fix-test cycles)
- Creating 100+ commands for simple issues
- Not creating the three required files
- Creating documentation files in root directory instead of Evidence Archive

## CRITICAL NEVER-DO LIST
- DROP TABLE without backup
- DELETE without WHERE clause  
- UPDATE without WHERE clause
- Force push to main branch
- Run migrations without testing rollback
- Skip database backup for "simple" changes

## SUCCESS CRITERIA
Task is complete when:
- Issue investigated and documented in INVESTIGATION.md
- Fix applied and documented in SOLUTION.md  
- Lessons captured in LESSONS.md
- No regressions introduced
- CURRENT_STATE.md updated
- Can be reproduced by next developer

## YOUR FIRST MESSAGE TO ASSISTANT
Read and follow: 3.7 Evidence Archive\MDP_Protocol\MDP_v2.md
Current issue: [describe or point to issue]
Create the three required files: INVESTIGATION.md, SOLUTION.md, LESSONS.md
Violation of MDP = immediate chat termination.

---
Remember: This is MANDATORY. No negotiations. No shortcuts.

## CROSS-FEATURE UPDATE REQUIREMENTS

When your bug/fix affects multiple features:

### MUST UPDATE:
1. Primary Feature/CURRENT_STATE.md (where bug originated)
2. Affected Feature/CURRENT_STATE.md (any feature impacted)
3. Cross_Feature_Issues/INDEX.md (always)

### EXAMPLE:
If fixing Trade_Categories breaks Job_Posting:
- Update: Trade_Categories/CURRENT_STATE.md
- Update: Job_Posting/CURRENT_STATE.md (note the dependency)
- Update: Cross_Feature_Issues/INDEX.md (document the relationship)

### FORMAT FOR CROSS-FEATURE DOCUMENTATION:
In affected feature's CURRENT_STATE.md, add:
DEPENDENCY WARNING:
- Depends on: Trade_Categories (categories table)
- Relationship: Job.category_id -> categories.id
- Last issue: 2025-09-06 - relationship needed explicit join
- Evidence: Trade_Categories/BUGS/BUG_dropdown_empty_2025-09-06/

### INVESTIGATION MUST CHECK:
- grep -r "from app.models.category" (who imports this model?)
- grep -r "categories.id" (who references this table?)
- Check all foreign keys pointing to your table
- Check all relationships using your model