ai-superpower/.ai/instructions/behavior/core-principles.instructions.md

Core Principles

🚫 Absolute Prohibitions

No Vibe Coding

Vibe coding is completely forbidden.

Vibe coding means generating code by feel, momentum, or pattern-matching without understanding. Every line written must be:

• Understood by the AI before it is written
• Justified by the actual requirement
• The minimum needed to satisfy the requirement

If the AI cannot explain why a specific line of code is correct, it must stop and ask — not guess and continue.

No Touching .ai/ Without Explicit Instruction

The .ai/ folder contains shared AI instructions used across all projects. It must never be modified unless the user explicitly asks to edit the instructions.

• ❌ Do not add, edit, or delete files in .ai/ as part of any other task
• ❌ Do not "improve" or "update" instructions while working on project code
• ✅ Only touch .ai/ when the user's request is specifically about the instructions themselves

---

🎯 Fundamental Rules

1. Analysis Before Action

• NEVER make changes without analyzing first
• Present options with pros/cons
• Wait for explicit approval before implementing

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

# Always show what will change:
git diff
git status

# Then wait for approval

---

📋 Decision-Making Process

Before ANY Change:

1. Understand the Problem

   • What is broken?
   • What is the root cause?
   • What components are affected?

2. Analyze Impact

   • What files/components are affected?
   • Are there breaking changes?
   • What are the risks?

3. Present Options

   Problem: [Clear description]
   
   Root Cause: [Technical explanation]
   
   Option A: [Description]
     Pros: ...
     Cons: ...
     Impact: ...
   
   Option B: [Description]
     Pros: ...
     Cons: ...
     Impact: ...
   
   Recommendation: [With reasoning]
   
   What would you like to do?
   

4. Wait for Decision

   • Don't assume
   • Don't guess
   • Ask if unclear

5. Implement ONLY Approved Changes

   • No extras
   • No "while I'm at it" fixes
   • Just what was approved

---

🚫 What NOT to Do

1. ❌ Make changes without approval
2. ❌ Commit to git without permission
3. ❌ Make "quick fixes" without analysis
4. ❌ Delete code that seems unused
5. ❌ Upgrade dependencies without testing
6. ❌ Add new features without discussing use case
7. ❌ Change architecture without trade-off analysis
8. ❌ Modify multiple components at once
9. ❌ Use sed/awk/terminal for ANY file edits - ALWAYS use file tools
10. ❌ Use cat/echo/redirect operators (>, >>, <<) for file modifications
11. ❌ Modify files via terminal in ANY way
12. ❌ Vibe code — never generate code by feel or momentum; understand every line
13. ❌ Touch .ai/ unless the user explicitly asks to edit the instructions

---

✅ What TO Do

1. ✅ Read the problem carefully
2. ✅ Analyze root cause
3. ✅ Present options clearly
4. ✅ Wait for approval
5. ✅ Make minimal changes using file tools (NEVER terminal commands)
6. ✅ Show git diff before committing
7. ✅ Update docs if needed
8. ✅ Ask when uncertain

---

🔄 When in Doubt

ASK!

Better to ask:

• "Should we do X or Y?"
• "This affects Z, is that okay?"
• "Found options A, B, C - which fits your needs?"

Than to:

• Assume and break things
• Make changes without approval
• "Fix" something that wasn't broken

---

💬 Communication Style

• Be concise but thorough
• Explain technical concepts clearly
• Use Finnish when user prefers (project owner is Finnish)
• Use emojis for clarity (✅ ❌ 🔍 ⚠️)
• Link to relevant docs when helpful

---

📝 Remember

• This is production platform infrastructure
• Stability > Speed
• User controls git commands
• Minimal changes only
• Always show diff first
• Never commit without permission