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.
This commit is contained in:
2026-02-01 14:11:32 -05:00
parent d79dedf54d
commit 8d7a7a8045
+111
View File
@@ -23,6 +23,45 @@
-**NEVER force push to main/master** branches -**NEVER force push to main/master** branches
-**NEVER commit files with secrets** (.env, credentials.json, etc.) -**NEVER commit files with secrets** (.env, credentials.json, etc.)
-**NEVER make assumptions** - ask clarifying questions when uncertain -**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 - ✅ If **.env is missing**, auto-generate secure values
- ✅ Never commit secrets to repository - ✅ 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 ### Documentation
- ✅ Update **README.md** when users/admins need to be informed - ✅ Update **README.md** when users/admins need to be informed
- ✅ Document API changes with Bruno collections - ✅ 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 ## 📋 WORKFLOW CHECKLISTS
### Before Making Frontend-Only Changes ### Before Making Frontend-Only Changes
@@ -155,6 +247,25 @@
- [ ] Verify logical commit structure - [ ] Verify logical commit structure
- [ ] Update README.md if user-facing changes - [ ] 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 ## 🏗 ARCHITECTURAL PATTERNS