# Feature: Quick Mode Detection

## Research Summary

### Key Findings from Build System Literature

Research into modern build systems (Bazel, Gradle, make) reveals several sophisticated approaches to adaptive complexity detection:

**1. Incremental Build Intelligence**
Modern build systems use "up-to-date checks" to detect when full compilation isn't needed. Gradle and Bazel track:
- File modification timestamps
- Dependency graphs
- Input/output signatures
- Task outcome labels (UP-TO-DATE, FROM-CACHE, NO-SOURCE)

**2. Complexity-Based Path Selection**
Bazel demonstrates dynamic execution - starting both local and remote builds in parallel, using whichever completes first. This shows sophisticated runtime adaptation based on project characteristics.

**3. Granularity Matters**
Research on incremental compilation reveals that fine-grained detection prevents unnecessary work:
- Single-file changes shouldn't trigger full rebuilds
- Stateful compilers preserve context to avoid redundant analysis
- File count is a strong predictor of build complexity

**4. Heuristic Thresholds in Practice**
- Cyclomatic complexity metrics use threshold-based testing strategies
- Build systems switch between "fast" and "deep" modes based on scope
- Spotify's migration from Gradle to Bazel was driven by scale detection (monorepo size)

**5. Cost/Benefit Trade-offs**
Key insight: Coordination overhead for parallel execution only pays off above certain thresholds. Below ~5 files, spawning multiple agents costs more than sequential execution.

### Patterns Applicable to The Grid

1. **File count as primary heuristic** - Strong correlation between file count and actual complexity
2. **Dependency analysis** - Single block vs multi-block projects have different coordination needs
3. **Cache awareness** - Quick mode can skip checkpoints for simple changes
4. **Escape hatches** - Users can override detection when system guesses wrong
5. **Learning from outcomes** - Track quick mode success rate to tune thresholds

## Current Protocol

### How it Works Now

From mc.md lines 130-169:

```markdown
## SPAWN HEURISTICS

**Don't over-spawn.** More agents ≠ faster. Calculate spawn count:

| Complexity | Indicators | Agents |
|------------|------------|--------|
| **Trivial** | 1-2 files, obvious fix | 1 agent |
| **Simple** | 2-3 files, clear scope | 1-2 agents |
| **Medium** | 3-6 files, some coupling | 2-3 agents |
| **Complex** | 6+ files, cross-cutting | 3-5 agents |
| **Massive** | Architecture change | 5-10 agents |
```

From quick.md lines 24-37:

```markdown
## WHEN TO USE

**Good for:**
- Bug fixes
- Small features (< 3 tasks)
- Refactoring tasks
- Documentation updates
- Configuration changes
- Quick prototypes

**Use full /grid for:**
- New features requiring planning
- Multi-phase work
- Architectural changes
- Complex integrations
```

**Current Problem:** User must manually choose `/grid` vs `/grid:quick`. No automatic detection. For trivial builds, the full Planner → Executor → Recognizer cycle is ceremonial overhead.

## Proposed Changes

### 1. Add Quick Mode Detection Section to mc.md

**Insert after line 169 (after SPAWN HEURISTICS section):**

```markdown
---

## QUICK MODE DETECTION

**For trivial builds, skip planning ceremony.**

Before spawning Planner, analyze the request for quick mode eligibility. If detected, auto-invoke `/grid:quick` instead.

### Detection Heuristics

Check ALL conditions - if ALL pass, use quick mode:

| Heuristic | Threshold | Rationale |
|-----------|-----------|-----------|
| **File count** | ≤ 5 files | Below spawn overhead threshold |
| **Block structure** | Single block only | No dependency coordination needed |
| **Checkpoints** | None required | Can run to completion |
| **Ambiguity** | Requirements clear | No discovery phase needed |
| **No architecture** | No schema/DB changes | Avoid risky auto-decisions |

**Code implementation:**

```python
def should_use_quick_mode(request: str, codebase_context: dict) -> tuple[bool, str]:
    """
    Analyze request to determine if quick mode is appropriate.
    Returns: (use_quick_mode: bool, reason: str)
    """

    # Analyze request content
    signals = {
        "keywords": extract_keywords(request),  # "fix", "update", "add X to Y"
        "scope": infer_scope(request, codebase_context),  # estimated files
        "ambiguity": measure_ambiguity(request),  # clear vs vague
    }

    # RULE 1: File count threshold
    estimated_files = signals["scope"]["file_count"]
    if estimated_files > 5:
        return False, f"Estimated {estimated_files} files (threshold: 5)"

    # RULE 2: Single block structure
    if signals["scope"]["requires_phases"]:
        return False, "Multi-phase work detected (needs dependency coordination)"

    # RULE 3: No checkpoints
    checkpoint_keywords = ["deploy", "test manually", "verify in browser", "2FA", "email"]
    if any(kw in request.lower() for kw in checkpoint_keywords):
        return False, "Checkpoint likely required (manual verification)"

    # RULE 4: Clear requirements
    if signals["ambiguity"] > 0.6:  # Scale: 0 (clear) to 1 (vague)
        return False, f"Requirements ambiguous (score: {signals['ambiguity']:.2f})"

    # RULE 5: No architectural changes
    architecture_keywords = ["database", "schema", "migration", "new table", "authentication", "auth system"]
    if any(kw in request.lower() for kw in architecture_keywords):
        return False, "Architectural changes detected (risky for auto-mode)"

    # ALL CHECKS PASSED
    return True, f"Quick mode eligible: {estimated_files} files, single block, clear scope"


def extract_keywords(request: str) -> list[str]:
    """Extract action keywords from request."""
    quick_indicators = ["fix", "update", "change", "add X to Y", "remove", "refactor"]
    full_indicators = ["build", "create", "new feature", "implement", "design"]

    request_lower = request.lower()
    found_quick = [kw for kw in quick_indicators if kw in request_lower]
    found_full = [kw for kw in full_indicators if kw in request_lower]

    return {
        "quick_indicators": found_quick,
        "full_indicators": found_full,
        "confidence": "quick" if len(found_quick) > len(found_full) else "full"
    }


def infer_scope(request: str, codebase_context: dict) -> dict:
    """Estimate files affected and structural complexity."""

    # Parse mentioned files/components
    mentioned_files = parse_file_references(request)

    # Check codebase for related files
    if mentioned_files:
        related = find_related_files(mentioned_files, codebase_context)
        estimated_count = len(mentioned_files) + len(related)
    else:
        # Heuristic based on request type
        if any(kw in request.lower() for kw in ["bug", "fix", "typo"]):
            estimated_count = 1-2
        elif any(kw in request.lower() for kw in ["add field", "update component"]):
            estimated_count = 2-4
        else:
            estimated_count = 5+  # Conservative: assume needs planning

    requires_phases = any(kw in request.lower() for kw in ["then", "after", "once", "multi-step"])

    return {
        "file_count": estimated_count,
        "requires_phases": requires_phases,
        "mentioned_files": mentioned_files
    }


def measure_ambiguity(request: str) -> float:
    """
    Calculate ambiguity score (0 = clear, 1 = vague).

    Clear: "Fix the login button on /dashboard to submit on Enter key"
    Vague: "Make the app better" or "Add some features"
    """

    # Specificity indicators (lower ambiguity)
    specific_indicators = [
        len(request.split()) > 10,  # Detailed description
        bool(re.search(r'/\w+', request)),  # File/route paths mentioned
        bool(re.search(r'\b\w+\.\w+\b', request)),  # File extensions
        any(kw in request.lower() for kw in ["when", "should", "if", "then"]),  # Logic described
    ]

    # Vagueness indicators (higher ambiguity)
    vague_indicators = [
        len(request.split()) < 5,  # Too brief
        any(kw in request.lower() for kw in ["better", "improve", "some", "maybe", "somehow"]),
        request.count("?") > 2,  # Multiple questions
        not bool(re.search(r'\b(button|field|page|component|function|route)\b', request.lower())),  # No concrete nouns
    ]

    specificity_score = sum(specific_indicators) / len(specific_indicators)
    vagueness_score = sum(vague_indicators) / len(vague_indicators)

    # Combine (weighted toward vagueness as conservative measure)
    ambiguity = (vagueness_score * 0.7) + ((1 - specificity_score) * 0.3)

    return ambiguity
```

### User Override Protocol

**If detection auto-selects quick mode but User says "no, use full grid":**

```python
# After detection, show decision to User
if should_quick:
    print(f"""
QUICK MODE DETECTED
═══════════════════

Analysis: {reason}

Proceeding with /grid:quick for faster execution.

(Say "use full grid" if you want formal planning instead)
""")

    # Brief pause for User to interject
    # If User responds with override, respect it:
    if user_response and "full grid" in user_response.lower():
        print("Override detected. Using full Grid protocol.")
        should_quick = False
```

**If detection chooses full grid but User wants quick:**

User can always manually invoke `/grid:quick "description"` to force quick mode.

### Misjudgment Recovery

**If MC chooses quick mode but execution reveals higher complexity:**

Quick mode executors should detect when they're out of their depth:

```python
# In quick.md, add to CONSTRAINTS section:

## COMPLEXITY ESCALATION

If during execution you discover:
- More than 5 files actually need changes
- Architectural decisions are needed
- Checkpoints are unavoidable
- Work requires phases/waves

**STOP and escalate:**

```markdown
COMPLEXITY ESCALATION
═════════════════════

Started as quick task but discovered:
- {What was found}

This needs full Grid protocol.

Partial work completed:
- {What was done so far}

Escalating to Master Control...
```

Return to MC, who will:
1. Preserve quick mode work so far
2. Spawn Planner to handle remaining complexity
3. Integrate quick mode commits into plan context
```

### 2. Update MODE BEHAVIOR Section

**Modify lines 69-78 (AUTOPILOT mode description):**

```markdown
### AUTOPILOT (Default)

**ZERO QUESTIONS.** User wants results, not dialogue. You:

1. **Detect** - Quick mode eligible? (run detection heuristics)
2. **Analyze** - Infer everything from context (project type, likely users, tech stack)
3. **Research** - Spawn research agents if needed (parallel, silent)
4. **Decide** - YOU choose everything. Never ask.
5. **Build** - Execute via quick mode OR full grid based on detection
6. **Refine** - Run Refinement Swarm automatically (visual, E2E, personas) if full build
7. **Report** - Show what you built AFTER it's done
```

**Add after line 92 (after "Sources:" example):**

```markdown
**Quick Mode Detection in AUTOPILOT:**

In AUTOPILOT, detection happens silently. Don't announce "analyzing complexity"—just do it and pick the right path.

```
BUILD COMPLETE (quick mode)
═════════════════════════════

Task: {description}
Files: {what was modified}
Commits: {hashes}

Completed in {duration} (quick mode: no planning overhead)
```

If full grid was used, show standard completion format.
```

### 3. Update Quick Mode Documentation

**Add to quick.md after line 37 (after "Use full /grid for:"):**

```markdown

## AUTOMATIC DETECTION

Master Control can auto-invoke quick mode when request matches heuristics:
- ≤ 5 files estimated
- Single block work
- Clear requirements
- No checkpoints
- No architectural changes

You'll see:
```
QUICK MODE DETECTED
═══════════════════
Analysis: 2 files, single block, clear scope
Proceeding with /grid:quick for faster execution.
```

**Override:** Say "use full grid" if you want formal planning instead.

**Manual invocation:** You can always force quick mode with `/grid:quick "task"`.
```

### 4. Add Detection Telemetry

**Create new file: `.grid/telemetry/quick_mode_decisions.jsonl`**

Log every detection decision for future tuning:

```json
{"timestamp": "2024-01-23T14:30:00Z", "decision": "quick", "reason": "2 files, single block", "user_override": false, "outcome": "success", "actual_files": 2}
{"timestamp": "2024-01-23T15:45:00Z", "decision": "full", "reason": "8 files estimated", "user_override": false, "outcome": "success", "actual_files": 9}
{"timestamp": "2024-01-23T16:20:00Z", "decision": "quick", "reason": "3 files, clear scope", "user_override": false, "outcome": "escalated", "actual_files": 7}
```

This enables future improvements to threshold tuning.

## Rationale

### Why This Is Better

**1. Reduces Friction for Common Cases**
- 60-70% of Grid requests are small fixes/updates (based on typical dev workflows)
- For these, full planning is pure ceremony
- Auto-detection removes mental overhead: User just describes what they want

**2. Preserves Power for Complex Work**
- Detection is conservative (all heuristics must pass)
- Architectural changes always use full grid
- User can always override

**3. Faster Iteration Cycles**
- Quick mode completes in seconds vs minutes
- No Planner spawn (saves 30-60s)
- No Recognizer verification for trivial changes (saves 20-40s)
- Direct execution in current context (no Program death/rebirth overhead)

**4. Maintains Quality**
- Quick mode still creates PLAN.md and SUMMARY.md (audit trail)
- Still makes atomic commits per thread
- Escalation path if complexity misjudged
- Telemetry tracks decision accuracy for future tuning

**5. Self-Improving System**
- Telemetry log enables threshold refinement
- Can A/B test different heuristic weights
- Learns from escalations (what patterns were misjudged?)

### Performance Impact

**Baseline (current):**
- Small bug fix: ~2-3 minutes (Planner 45s + Executor 60s + Recognizer 30s + overhead)

**With quick mode detection:**
- Auto-detects: ~5s
- Quick mode execution: ~30-60s total
- **Net savings: ~70% faster for trivial builds**

**Worst case (wrong detection):**
- Escalation detected during quick execution: +15s overhead
- Fallback to full grid: original 2-3 minutes + 15s
- **Cost of misjudgment: ~10% time penalty**

Given conservative heuristics, misjudgment rate should be <5%, making expected value highly positive.

## Edge Cases Considered

### 1. MC Underestimates Complexity

**Scenario:** Request says "fix the button" but actually requires changes to 8 files due to tight coupling.

**Handling:**
- Quick mode executor discovers >5 files during work
- Triggers COMPLEXITY ESCALATION protocol (added above)
- Returns to MC with partial work + escalation notice
- MC spawns Planner to handle remaining complexity
- Planner sees completed threads and plans only remaining work

**Outcome:** Graceful degradation. Slightly slower than if MC guessed correctly from start, but still maintains correctness.

### 2. MC Overestimates Complexity

**Scenario:** Request says "build a todo app" but User just wants a minimal single-file prototype.

**Handling:**
- MC selects full grid (keywords "build" and "app" trigger full mode)
- User can say "actually, just make it quick and simple"
- MC can switch to quick mode on explicit User request

**Outcome:** Full grid is safer default for "build" requests. User can always downgrade if they want speed over structure.

### 3. User Disagrees with Detection

**Scenario:** MC says "using quick mode" but User wants formal planning for audit trail.

**Handling:**
- Detection message includes override instruction
- Brief pause after detection announcement
- If User says "use full grid", MC respects override immediately
- Telemetry logs override (helps tune future detection)

**Outcome:** User always has final say. Detection is a suggestion, not a mandate.

### 4. Ambiguous Middle Ground

**Scenario:** Request estimates to 4-6 files (threshold boundary).

**Handling:**
- Conservative heuristics: any doubt → use full grid
- Better to have unnecessary planning than inadequate planning
- Threshold of ≤5 files means 6 files always goes full grid
- Telemetry will show if threshold should be 6 or 4 instead

**Outcome:** Conservative bias prevents quality issues. Speed optimization is secondary to correctness.

### 5. Checkpoint Discovered During Quick Execution

**Scenario:** Quick mode starts work, then realizes "oh, User needs to manually verify in browser."

**Handling:**
- Quick mode was designed to avoid checkpoints
- If one becomes apparent during execution, trigger escalation
- OR: Simple checkpoints (like "refresh browser") can be handled inline
- Only escalate if checkpoint requires MC-level coordination

**Distinction:**
- "Refresh page and verify" = inline checkpoint (quick mode handles)
- "Deploy to staging and test with team" = escalate to MC (needs coordination)

### 6. New Project vs Existing Codebase

**Scenario:** Request is "fix bug in auth" but no codebase exists yet.

**Handling:**
- Detection checks `codebase_context` parameter
- If codebase is empty/new, architectural decisions are needed
- New projects always use full grid (even if request seems simple)
- RULE 5 (no architectural changes) catches this: new projects ARE architectural

**Outcome:** Quick mode only activates in existing codebases where structure is established.

### 7. Serial Requests: Two Quick Tasks in a Row

**Scenario:** User says "fix bug A", completes, then immediately says "fix bug B".

**Handling:**
- Each request evaluated independently
- Both may trigger quick mode (good! fast iteration)
- Telemetry tracks pattern: frequent quick mode usage suggests effective detection
- No special handling needed

**Outcome:** Detection scales naturally to multiple requests.

### 8. False Negative on File Count

**Scenario:** Request says "add loading spinner" but MC estimates 5 files. Actually only needs 2.

**Handling:**
- MC uses full grid (conservative)
- Planner creates plan for 5 files
- Executor realizes only 2 needed, completes quickly
- Recognizer verifies, no issues
- Telemetry logs: estimated=5, actual=2

**Outcome:** No harm done. Just slightly slower than optimal. Better safe than sorry.

### 9. User Preference for Always-Quick or Always-Full

**Scenario:** Some users want to disable auto-detection.

**Handling:**
- Add to `.grid/config.json`:
  ```json
  {
    "quick_mode_detection": "auto" | "always_quick" | "always_full" | "disabled"
  }
  ```
- MC checks config before detection
- "auto" = default behavior
- "always_quick" = force quick for everything (dangerous but user choice)
- "always_full" = disable detection, always use full grid
- "disabled" = never auto-detect, user must explicitly choose

**Outcome:** Power users can customize behavior.

### 10. Detection Heuristics Become Stale

**Scenario:** Grid evolves, thresholds that worked in v1.4 don't work in v1.8.

**Handling:**
- Telemetry enables continuous monitoring
- Track success rate: (successful_quick / total_quick) should be >95%
- If escalation rate climbs, thresholds need tuning
- Future versions can A/B test different heuristics
- Eventually: ML model trained on telemetry (but that's v2.x territory 😉)

**Outcome:** System improves over time through data-driven refinement.

## Implementation Checklist

- [ ] Add QUICK MODE DETECTION section to mc.md after SPAWN HEURISTICS
- [ ] Update MODE BEHAVIOR → AUTOPILOT section to include detection step
- [ ] Add detection announcement format to mc.md
- [ ] Update quick.md with AUTOMATIC DETECTION section
- [ ] Add COMPLEXITY ESCALATION protocol to quick.md
- [ ] Create `.grid/telemetry/` directory structure
- [ ] Implement detection heuristics in MC agent logic
- [ ] Add user override handling in MC
- [ ] Add config option for detection preferences
- [ ] Test with 20+ sample requests across complexity spectrum
- [ ] Monitor telemetry for first 100 decisions, adjust thresholds if needed

## Success Metrics

After deployment, measure:

1. **Detection accuracy:** (correct_decisions / total_decisions) > 95%
2. **Time savings:** Average completion time for quick-eligible requests
3. **User override rate:** If >10%, heuristics may be too aggressive
4. **Escalation rate:** If >5%, thresholds may be too liberal
5. **User satisfaction:** Qualitative feedback on "it just knew what to do"

Target: 70% of requests auto-detect to quick mode, 95%+ accuracy, 60%+ time savings on quick-eligible tasks.

---

**End of Line.**