From 8d7a7a804557d88e66892fb7b6a3d061f9f6b3cb Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Sun, 1 Feb 2026 14:11:32 -0500 Subject: [PATCH] docs: add code modification safety protocols to guidelines Added 110 lines of safety guidelines to prevent future bugs: New CRITICAL PROHIBITIONS: - NEVER delete code without reading full context (20 lines before/after) - NEVER make cascading fix-up edits without git diff review - NEVER skip post-edit verification New MANDATORY REQUIREMENTS: - Post-Edit Verification (mandatory for all file modifications) - Backup Before Large Changes - Large Deletion Safety Pattern New ERROR RECOVERY PROTOCOL: - Immediate actions when mistakes occur - Recovery examples with git commands - Prevention learning points New WORKFLOW CHECKLISTS: - Error Recovery Protocol - Phase Completion Verification These guidelines address the critical bug where auth functions were accidentally deleted during cleanup, preventing recurrence. --- PROJECT_GUIDELINES.md | 111 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) diff --git a/PROJECT_GUIDELINES.md b/PROJECT_GUIDELINES.md index 52dfeb9..f4404c6 100644 --- a/PROJECT_GUIDELINES.md +++ b/PROJECT_GUIDELINES.md @@ -23,6 +23,45 @@ - ❌ **NEVER force push to main/master** branches - ❌ **NEVER commit files with secrets** (.env, credentials.json, etc.) - ❌ **NEVER make assumptions** - ask clarifying questions when uncertain +- ❌ **NEVER delete code without reading full context first** (minimum 20 lines before/after) +- ❌ **NEVER make cascading fix-up edits without git diff review** + - After compilation error: STOP, review `git diff`, understand full impact + - Use revert/re-apply pattern instead of blind fixes +- ❌ **NEVER skip post-edit verification** - must compile after each file edit + +### Cascading Fix-up Pattern (PROHIBITED) + +**WHAT NOT TO DO** - This caused critical bugs: +```go +// ❌ WRONG: Blindly making fixes after compilation error + +Edit 1: Delete deprecated code +[Compilation error: undefined Register] + +Edit 2: Try to fix error (over-broad deletion) +[More errors: undefined Login, GetProfile, etc.] + +Edit 3: Try to fix again (worse damage) +[Even more errors: major functionality broken] +``` + +**CORRECT APPROACH**: +```go +// ✅ CORRECT: Stop, understand, then fix deliberately + +Edit 1: Delete deprecated code +[Compilation error: undefined Register] + +STOP → Review git diff → Understand Register was accidentally deleted +RESTORE → Get exact Register function from git history +VERIFY → Compile successfully +``` + +**Key Principle**: When compilation errors occur after edits: +1. STOP - Don't make more edits +2. ANALYZE - Use `git diff` to understand what was changed +3. RECOVER - Restore what was accidentally deleted/broken +4. VERIFY - Compile and test before proceeding --- @@ -80,6 +119,22 @@ - ✅ If **.env is missing**, auto-generate secure values - ✅ Never commit secrets to repository +### Code Modification Safety +- ✅ **Post-Edit Verification (MANDATORY for ALL file modifications)**: + - Run `go build` for affected packages immediately after each edit + - Review `git diff filename` to verify only intended changes + - Validate functionality still works as expected + - Never proceed to next file until current edit is verified +- ✅ **Backup Before Large Changes**: + - Create a stash: `git stash push -m "Pre-cleanup snapshot"` before removing >50 lines + - Or create a backup branch: `git branch backup-before-cleanup` + - This allows instant recovery if mistakes occur +- ✅ **Large Deletion Safety Pattern**: + - Read at least 20 lines before/after deletion target + - Include unique identifiers in match (function signatures, specific comments) + - Use narrow matches - avoid generic patterns + - Verify line numbers match intended section + ### Documentation - ✅ Update **README.md** when users/admins need to be informed - ✅ Document API changes with Bruno collections @@ -111,6 +166,43 @@ --- +## 🔄 ERROR RECOVERY PROTOCOL + +When code modification mistakes occur (deleted wrong code, broke compilation, etc.): + +### Immediate Actions +1. **STOP** - Don't make more edits +2. **ASSESS** - What was deleted? Is it critical? +3. **REVIEW** - Run `git diff` to see exact changes +4. **RESTORE** - Choose appropriate recovery method: + - **Recent mistake**: `git checkout -- filename` + - **Complex restoration**: Use `git show HEAD:filename` to recover deleted code + - **Multiple files**: `git reset HEAD~1` (if safe) +5. **VERIFY** - Compile and test restored code +6. **DOCUMENT** - Note what went wrong for future reference + +### Recovery Examples +```bash +# Recover a deleted function from original file +git show HEAD:internal/handlers/auth.go | sed -n '70,275p' > recovery.txt + +# Revert entire file to original state +git checkout HEAD -- internal/handlers/auth.go + +# Use git stash to save current state before rollback +git stash push -m "Broken state before fix" +git checkout -- internal/handlers/auth.go +``` + +### Prevention (Learn From Mistakes) +- Why did the mistake happen? +- Was it too-broad matching? +- Was it insufficient context reading? +- Was it cascading fix-up attempts? +- Update guidelines to prevent recurrence + +--- + ## 📋 WORKFLOW CHECKLISTS ### Before Making Frontend-Only Changes @@ -155,6 +247,25 @@ - [ ] Verify logical commit structure - [ ] Update README.md if user-facing changes +### Error Recovery Protocol (If Code Mistakes Occur) +- [ ] **Stop immediately** - don't make more edits +- [ ] **Assess impact**: What was deleted? Is it critical? +- [ ] **Review git diff**: See exact changes made +- [ ] **Restore strategy**: + - If recent mistake: `git checkout -- filename` + - If complex: Reconstruct from git diff using `git show HEAD:filename` +- [ ] **Verify recovery**: Compile and test restored code +- [ ] **Document mistake**: Note what went wrong for future reference + +### Phase Completion Verification (Before Declaring "Complete") +- [ ] All target code is removed/intact as intended +- [ ] No unintended code was deleted +- [ ] All affected files compile successfully +- [ ] Run `go build ./...` for entire project +- [ ] No critical functionality was broken +- [ ] Git diff shows only intended changes +- [ ] Review all modified files with `git diff --stat` + --- ## 🏗 ARCHITECTURAL PATTERNS