diff --git a/.ai/instructions/behavior/core-principles.instructions.md b/.ai/instructions/behavior/core-principles.instructions.md index 97c903f..5f0da0c 100644 --- a/.ai/instructions/behavior/core-principles.instructions.md +++ b/.ai/instructions/behavior/core-principles.instructions.md @@ -28,13 +28,39 @@ The `.ai/` folder contains shared AI instructions used across all projects. It m - Present options with pros/cons - Wait for explicit approval before implementing +### 🔍 Read Before You Edit — Mandatory +Before making ANY file edit or running ANY command: + +1. **Read the relevant code/content first** — never edit based on a description alone +2. **State what you observed** — quote or summarize what you actually read +3. **Explain what you will change and why** — one sentence is enough +4. **Wait for confirmation if destructive** — deletes, removals, template changes + +Skipping this step is a violation of these instructions, even if the user seems impatient or the change seems obvious. + ### 2. Minimal Changes Only - Make ONLY the requested change - Don't "improve" or "clean up" other things - Don't change component behavior - Don't remove features without approval -### 3. Show Changes First +### 3. Explain and Break Down Work — Human Must Understand + +The goal is not just to complete the task — the human must understand what is being done and why. AI does the work, human stays in control and learns. + +**For any non-trivial task:** +1. **State what you are about to do and why** — before touching any file +2. **Break the task into parts** — list them as a numbered todo in the chat +3. **Do one part at a time** — explain each step before executing it +4. **Wait for the human to approve or reject** each part if it changes something meaningful + +This applies even when the task seems straightforward. Momentum is not a reason to skip explanation. + +**Keep explanations concise.** A wall of text buries the important parts. One or two sentences per step is enough — the human can ask for more if needed. Never pad, never repeat, never re-explain what was just said. + +The git commit workflow reinforces this: the human reviews the diff and writes (or approves) the commit — because they must be able to put their name on it. + +### 4. Show Changes First ```bash # Always show what will change: git diff