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:
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user