niko/ai-superpower
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(core-principles): add read-before-edit and explain-as-you-go rules

Browse Source
This commit is contained in:
moilanik 2026-03-18 08:27:36 +02:00
parent b51a05e203
commit 5955a27f08
1 changed files with 27 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
.ai/instructions/behavior/core-principles.instructions.md
View File

@ -28,13 +28,39 @@ The `.ai/` folder contains shared AI instructions used across all projects. It m
- Present options with pros/cons - Present options with pros/cons
- Wait for explicit approval before implementing - 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 ### 2. Minimal Changes Only
- Make ONLY the requested change - Make ONLY the requested change
- Don't "improve" or "clean up" other things - Don't "improve" or "clean up" other things
- Don't change component behavior - Don't change component behavior
- Don't remove features without approval - 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 ```bash
# Always show what will change: # Always show what will change:
git diff git diff