feat: add more voilation consequence and troubleshooting section

Author: matscode

README.md

@@ -40,26 +40,26 @@ Watch how the Interactive Coding Agent works:
 
 ## Setup
 
-### Option 1: Full Setup (Recommended)
-**Copy and paste everything** from this folder into your project root. This gives you interactive coding agent capability in all configured/supported editors.
+### Quick Start (Recommended)
+**Copy this `interactive-coding-agent` folder's contents** (the AGENTS.md file, rules/ folder, and others) **into your project root.** That's it! You now have interactive coding agents.
 
-### Option 2: Editor-Specific Setup
-If you only want to setup for one editor, copy these files:
+### Minimal Setup
+Want just the essentials? Copy these:
 
-**Always Required:**
-- `AGENTS.md` (root level)
-- `rules/` folder (contains the main rules - **entry point: `rules/index.rules.md`**)
+**Required Files and Folders:**
+- `AGENTS.md` (put in your project root)
+- `rules/` folder (the main rules)
+- `project-specs/` folder
+- `specs/` folder
 
-**Plus your editor's config:**
-- For **Trae AI**: Copy `.trae/` folder
-- For **Cursor**: Copy `.cursor/` folder (if available)
-- For **Windsurf**: Copy `.windsurf/` folder
-- For **Kiro**: Copy `.kiro/` folder
+**Your Editor Config:**
+- **Trae AI**: Copy `.trae/` folder
+- **Cursor**: Copy `.cursor/` folder  
+- **Windsurf**: Copy `.windsurf/` folder
+- **Kiro**: Copy `.kiro/` folder
 
-### How It Works
-Once copied, the rules will automatically apply when you start a new coding sessions in supported editors.
-
-**Important:** After copying the configuration files, you must **start a new chat session** for the rules to take effect.
+### Activation
+After copying files, **start a new chat** in your editor. The rules activate automatically.
 
 ## 👤 User Persona System
 
@@ -122,6 +122,40 @@ The persona system ensures you get exactly the right level of detail and communi
 | **Gemini** | CLI | `AGENTS.md` | ❌ Not Working Yet |
 | **Gemini Code Assist (VS Code)** | IDE | `AGENTS.md` | ❌ Not Working Yet |
 
+## 🔧 Troubleshooting
+
+### Quick Fix (Try This First!)
+**Problem**: Agent not behaving as expected
+- **Simple Solution**: Ask the AI to "read the project rules" 
+- **Fun Trick**: Just type "You violated" - agents usually take responsibility and self-correct
+- **Reset**: These prompts often trigger proper rule compliance immediately
+
+### Agent Not Following Rules
+**Problem**: Agent ignores interactive protocols or makes assumptions
+- **Solution**: Start a **new chat session** - rules only activate on fresh sessions
+- **Check**: Verify `AGENTS.md` or editor config files are in your project root
+- **Verify**: Look for rule violations in agent responses and point them out directly
+
+### Rules Not Activating  
+**Problem**: Agent behaves normally without interactive questioning
+- **Solution**: Confirm you copied the correct files for your editor (see Setup section)
+- **Check**: Ensure `rules/` folder is present with `index.rules.md` as entry point
+- **Restart**: Close and reopen your editor, then start a new chat session
+
+### Interactive Questions Not Working
+**Problem**: Agent shows questions as text instead of executing them like a command
+- **Solution**: This indicates a rule violation - remind agent to use `run_command` tool
+- **Check**: Agent should execute questions like `echo "question"; read answer`
+- **Escalate**: If persistent, explicitly request: "Use the run_command tool for questions"
+
+### Persona Setup Issues
+**Problem**: Agent doesn't ask about user persona or uses wrong communication style  
+- **Solution**: Delete `specs/user-persona.spec.md` and start a new chat session
+- **Manual**: Create persona file manually using templates in `rules/templates/`
+- **Predefined**: Copy from `specs/user-personas/` (senior-software-engineer.spec.md, product-designer.spec.md, etc.) to `specs/user-persona.spec.md`
+- **Override**: Edit existing persona file directly to update preferences
+- **Final Step**: Start a new chat and ask the agent to "setup my user persona"
+
 ---
 
 *Created by [@matscode](https://www.tiktok.com/@matscode) | [LinkedIn](https://www.linkedin.com/in/matscode)*

rules/core-principles.rules.md

@@ -49,8 +49,15 @@ This file defines the fundamental workflow and core principles that ALL coding a
 - **WAIT** for explicit user approval before coding
 - **CONFIRM** implementation steps align with specifications
 
+### 6.5. DOCUMENT USER DECISIONS
+**DECISION DOCUMENTATION PROTOCOL:**
+- **MANDATORY:** After ANY user decision or choice, ask: "Should this decision be documented in the relevant spec file for future reference?"
+- **USE `run_command` TOOL** for documentation questions - **MUST FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
+- **INCLUDE** all decisions: colors, preferences, library choices, UI layouts, feature behaviors
+- **ENSURE** specs become complete blueprints for exact reproduction
+
 ### 7. IMPLEMENT ACCORDING TO SPECIFICATIONS
-- **RE-READ** all relevant specifications after approval but before implementation
+- **RE-READ** all relevant specifications immediately before implementation
 - **FOLLOW** approved specifications exactly
 - **MAINTAIN** consistency with established patterns
 - **IMPLEMENT** only what was approved

rules/spec-management.rules.md

@@ -71,8 +71,9 @@ When coding agents need context for:
 5. **RESEARCH OPTIONS** - Present alternatives with trade-offs
 6. **PROPOSE SPECIFICATION** - Create spec file with decision rationale
 7. **WAIT FOR APPROVAL** - **USE `run_command` TOOL** for approval questions - **MUST FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
-8. **RE-READ SPECIFICATIONS** - **MANDATORY:** Read all relevant specs again after approval but before implementation to ensure most current information
-9. **IMPLEMENT ACCORDING TO SPEC** - Follow approved specification exactly
+8. **DOCUMENT USER DECISIONS** - **MANDATORY:** After ANY user decision or choice, ask: "Should this decision be documented in the relevant spec file for future reference?" - **USE `run_command` TOOL** - **MUST FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
+9. **RE-READ SPECIFICATIONS** - **MANDATORY:** Read all relevant specs immediately before implementation to ensure most current information
+10. **IMPLEMENT ACCORDING TO SPEC** - Follow approved specification exactly
 
 **AGENT QUESTIONING PROTOCOL FOR SPECIFICATION DOCUMENTATION:**
 Before creating any specification file, agents MUST ask these questions to ensure optimal documentation:

rules/violation-enforcement.rules.md

@@ -19,18 +19,20 @@
 2. **Adding unrequested features or scope creep** → STOP session, acknowledge violation, rollback changes
 3. **Proceeding without clarification on ambiguous requirements** → STOP session, acknowledge assumption error
 4. **Implementing without reading existing specifications** → STOP session, acknowledge spec violation
-5. **Displaying interactive commands as text instead of executing** → STOP session, acknowledge execution failure
-6. **Making architectural decisions without creating specifications** → STOP session, acknowledge documentation failure
+5. **Not re-reading specifications immediately before implementation** → STOP session, acknowledge timing violation
+6. **Displaying interactive commands as text instead of executing** → STOP session, acknowledge execution failure
+7. **Making architectural decisions without creating specifications** → STOP session, acknowledge documentation failure
 
 ### MAJOR VIOLATIONS (Immediate Correction Required)
 **Stop immediately and correct, but session can continue:**
 
 1. **Missing mandatory stop points** → STOP immediately, acknowledge missed step, execute required question
 2. **Skipping session closure protocol** → STOP immediately, execute mandatory closure question
 3. **Failing to ask "Does this meet expectations?"** → STOP immediately, ask retroactively
-4. **Removing working components without permission** → STOP immediately, acknowledge preservation violation
-5. **Ignoring established patterns without justification** → STOP immediately, acknowledge pattern violation
-6. **Skipping specification index updates** → STOP immediately, update index file
+4. **Not asking about decision documentation** → STOP immediately, ask: "Should this decision be documented in the relevant spec file for future reference?"
+5. **Removing working components without permission** → STOP immediately, acknowledge preservation violation
+6. **Ignoring established patterns without justification** → STOP immediately, acknowledge pattern violation
+7. **Skipping specification index updates** → STOP immediately, update index file
 
 ### MINOR VIOLATIONS (Acknowledge and Correct)
 **Acknowledge error and implement correction:**