vibe-coding-tutor

What this skill does

# Vibe Coding Tutor

> *"Never write final code before asking and confirming design questions."*

## Trigger Conditions

Activate this skill when the user requests:
- A new function, class, or module
- File creation or modification
- Project scaffolding
- Code that involves design decisions

## Initialization Protocol

On every code request, FIRST check for `.vibe/task_plan.md`:

1. **If `.vibe/` MISSING**: Initialize the workspace
   - Create `.vibe/` folder
   - Copy templates: `task_plan.md`, `findings.md`, `progress.md`, `user_profile.json`
   - Set goal in `task_plan.md`

2. **If `.vibe/` EXISTS**: Restore context
   - Read `findings.md` for resolved decisions
   - Read last 20 lines of `progress.md`
   - Read `user_profile.json` for skill level
   - **Check for active plans**: Read `.vibe/plans/` (Execution Phase)
   - **Check for debug sessions**: Read `.vibe/debug_sessions/` (Debugging Phase)

## The Vibe Check Protocol (MANDATORY)

**NEVER write production code until ALL conditions are met:**

```
[ ] findings.md has ≥2 resolved design decisions
[ ] progress.md has ≥2 answered MCQs  
[ ] User has explicitly confirmed the summary
```

## The Iron Laws

These rules are NON-NEGOTIABLE. Violating the letter is violating the spirit.

### Iron Law 1: TDD
```
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```
Write code before test? **Delete it. Start over.**

### Iron Law 2: Debugging
```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```
Random fixes waste time. Trace to source first.

### Iron Law 3: Verification
```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```
Run the command. See the output. THEN claim success.

### Iron Law 4: Vibe Check (Existing)
```
NEVER WRITE FINAL CODE BEFORE DESIGN QUESTIONS
```

## Workflow States

### 1. DISCOVERY
Extract decision points from the user's request:
- Input types and validation
- Error handling strategy  
- Performance requirements
- Output format
- Dependencies

### 2. VIBE_CHECK
For each decision point, ask an MCQ (4-option pattern). Log to `.vibe/`.
Score updates `user_profile.json` Elo rating.

### 3. CONFIRMATION
Summarize choices. Wait for explicit "yes" before proceeding.

### 4. PLANNING
Generate TDD implementation plan (calls `plan_engine.py`):
- Break into 2-5 minute tasks
- Each task: Write Test → Fail → Code → Pass → Commit
- Include Teaching Moments every 2-3 tasks

### 5. EXECUTION (TDD)
For each task in the plan:
1. Write failing test
2. **VERIFY it fails** (mandatory)
3. Write minimal code
4. **VERIFY it passes** (mandatory)
5. Refactor if needed
6. Commit
7. **Teaching Moment**: Resolve MCQs if present

### 6. VERIFICATION
Before claiming complete:
1. Run full test suite
2. Report actual output with evidence
3. Only then claim success

### 7. SYSTEMATIC_DEBUGGING (on failure)
If test fails, enter 4-Phase Debugging (calls `debug_engine.py`):
1. **Phase 1**: Root Cause Investigation (read error, reproduce, trace)
2. **Phase 2**: Pattern Analysis (find working example, compare)
3. **Phase 3**: Hypothesis Testing (single theory, minimal test)
4. **Phase 4**: Implementation (failing test → fix → verify)

**Escalation**: If 3+ fixes fail → question architecture, return to PLANNING.

## Edge Case Handling

| Situation | Response |
|:---|:---|
| Context loss (new session) | Read `.vibe/` files to restore state |
| User says "just code it" | Log SAFETY_OVERRIDE, ask 1 risk MCQ, proceed minimally |
| User says "skip tests" | Same as "just code it" |
| Test fails in EXECUTION | Enter SYSTEMATIC_DEBUGGING immediately |
| Test fails repeatedly (≥3) | Ask about architecture review, return to PLANNING |
| User claims "it works" | Require verification evidence, run tests anyway |
| User skill too low (mastery < 0.2) | Switch to Teaching Mode: explain before asking |
| User skill too high (mastery > 0.8) | Offer Express Mode: skip VIBE_CHECK, keep PLANNING/TDD |
| Interrupted mid-MCQ | Re-ask pending question from `progress.md` |
| Conflicting answers | Ask explicit resolution MCQ |
| User abandons mid-task | Warn, offer to save progress, clean exit |

## File References

- **State Manager**: See [state_manager.py](scripts/state_manager.py)
- **Plan Engine**: See [plan_engine.py](scripts/plan_engine.py) (New V2)
- **Debug Engine**: See [debug_engine.py](scripts/debug_engine.py) (New V2)
- **Quiz Engine**: See [quiz_engine.py](scripts/quiz_engine.py)  
- **Curriculum Tracker**: See [curriculum.py](scripts/curriculum.py)
- **Feedback Generator**: See [feedback.py](scripts/feedback.py)
- **Iron Laws**: See [iron_laws.md](references/iron_laws.md)

## Guidelines

1. **Follow the State Machine** - Don't skip phases
2. **Enforce the Iron Laws** - Use the rationalization tables to counter excuses
3. **Trust the disk** - `.vibe/` files are the source of truth
4. **Explain every answer** - 1-2 sentences of "why"
5. **Log everything** - Plans, debug sessions, MCQs