Recent Entries 3
- principle critical 139d agoGit safety: never amend after hook failureWhen a pre-commit hook fails (linting error, formatting issue, test failure), the git commit does NOT happen — it's aborted. A common mistake is to fix the issue and then run 'git commit --amend', thinking you're retrying the failed commit. But --amend doesn't retry — it modifies the PREVIOUS successful commit. If that previous commit was from yesterday's feature work, amending would: (1) merge today's unrelated changes into yesterday's commit, (2) lose yesterday's original commit message, (3) create a confusing git history where one commit contains changes from two different features, and (4) if already pushed, would require a force-push to fix. This is especially dangerous for AI coding agents that automate git operations.
- principle critical 139d agoNever delete user files without explicit permissionUsers sometimes ask AI coding assistants to 'clean up', 'reset', 'start fresh', 'remove old files', or 'reorganize the project'. These requests are ambiguous — the user might mean 'move unused files' or they might mean 'permanently delete everything I don't currently need.' Deletion is irreversible (unless there's a backup or git history). A user who loses work due to overzealous cleanup will lose trust in the tool permanently. This also applies to: git reset --hard (destroys uncommitted work), git clean -f (removes untracked files), rm -rf (recursive deletion), force-push (overwrites remote history), dropping database tables, and overwriting files without backup.
- principle critical 139d agoAlways read a file before editing itThe Edit tool (and similar find-and-replace based code editing tools) fails or produces wrong results when you attempt to modify a file without first reading its contents. Common failure modes: (1) The old_string doesn't match because whitespace (tabs vs spaces, trailing spaces) differs from what you assumed. (2) The old_string matches multiple locations in the file, causing an ambiguity error. (3) The surrounding context has changed since you last saw it (another edit modified nearby lines). (4) Line endings differ (CRLF vs LF). (5) The indentation level is wrong because you guessed the nesting depth. (6) Unicode characters or special characters in the file don't match your assumed content. This wastes time with failed edit attempts and can corrupt code if a partial match succeeds at the wrong location.