@boshu2/vibe-check 1.8.1 → 2.2.0

package/.agents/plans/2025-12-27-vibe-check-evolution-plan.md

@@ -0,0 +1,383 @@
+---
+date: 2025-12-27
+type: Plan
+topic: "Vibe-Check Evolution: Tracer Bullets, Investigation Gaps, and Middle Loop Detection"
+research: ".agents/research/2025-12-27-vibe-check-evolution.md"
+tags: [plan, vibe-check, metrics, tracers, investigation, middle-loop]
+status: READY_FOR_APPROVAL
+---
+
+# Plan: Vibe-Check Evolution
+
+**Created:** 2025-12-27
+**Research:** [.agents/research/2025-12-27-vibe-check-evolution.md](.agents/research/2025-12-27-vibe-check-evolution.md)
+**Vibe Level:** L3 (New features with clear patterns to follow)
+
+---
+
+## Overview
+
+Implement the documented Enhancement Plan (P1-P2) plus two middle loop detectors to evolve vibe-check from an inner-loop-only tool to one that provides visibility into investigation time, proactive validation practices, and architectural health.
+
+**What we're building:**
+1. **Tracer Bullet Tracking** - Recognize `tracer:`/`tb:` commits and measure proactive validation ratio
+2. **Investigation Gap Detection** - Surface hidden debugging time from commit timestamp gaps
+3. **Eldritch Horror Detector** - Flag functions exceeding 200 lines (middle loop pattern)
+4. **Domain Cohesion Score** - Measure how scattered changes are across domains
+
+---
+
+## Approach
+
+Follow the existing metrics pattern in `src/metrics/`:
+- Each metric is a separate file returning `MetricResult`
+- Metrics are orchestrated in `src/metrics/index.ts`
+- Types are defined in `src/types.ts`
+- Tests follow the pattern in `tests/`
+
+**Why this approach:**
+- Consistent with existing architecture (100% TypeScript, clean separation)
+- Each feature can be implemented and tested independently
+- Minimal changes to existing code (additive, not destructive)
+- Follows documented Enhancement Plan specifications
+
+---
+
+## Features
+
+### Feature 1: Tracer Bullet Tracking
+
+**Priority:** P1
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] New commit type `tracer` recognized in git parser
+- [ ] `src/metrics/tracers.ts` calculates tracer metrics
+- [ ] Output shows tracer count, before-feature ratio, before-fix count
+- [ ] Rating: ELITE >20% | HIGH >10% | MEDIUM >5% | LOW <5%
+- [ ] Tests cover edge cases (no tracers, all tracers, mixed)
+
+**Files Affected:**
+- `src/git.ts` - Add `tracer` to commit type detection (line ~45)
+- `src/types.ts` - Add `TracerMetrics` interface
+- `src/metrics/tracers.ts` - NEW: Tracer calculation
+- `src/metrics/index.ts` - Include tracer metrics in result
+- `src/output/terminal.ts` - Display tracer section
+- `tests/tracers.test.ts` - NEW: Unit tests
+
+**Implementation Notes:**
+```typescript
+// Commit message patterns to match:
+// "tracer: validate Redis connection"
+// "tb: test SSE streaming"
+// "tracer(fleet): mission directory flow"
+const TRACER_PATTERNS = [/^tracer(?:\([^)]+\))?:/i, /^tb(?:\([^)]+\))?:/i];
+
+interface TracerMetrics extends MetricResult {
+  tracerCount: number;
+  tracerBeforeFeature: number;  // Tracers followed by feat: (good!)
+  tracerBeforeFix: number;       // Tracers followed by fix: (too late!)
+  tracerRatio: number;           // tracers / (feat + fix)
+}
+```
+
+**Test Strategy:**
+- Unit tests with mock commit lists
+- Integration test with analyze command
+
+---
+
+### Feature 2: Investigation Gap Detection
+
+**Priority:** P1
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] `src/metrics/investigation.ts` analyzes commit timestamp gaps
+- [ ] Gaps >15 min and <2 hours followed by `fix:` = investigation
+- [ ] Output shows total investigation time estimate and longest gap
+- [ ] Same-component detection uses existing logic from `spirals.ts`
+- [ ] Tests cover various gap scenarios
+
+**Files Affected:**
+- `src/types.ts` - Add `InvestigationMetrics` interface
+- `src/metrics/investigation.ts` - NEW: Gap analysis
+- `src/metrics/index.ts` - Include investigation metrics in result
+- `src/output/terminal.ts` - Display investigation section
+- `tests/investigation.test.ts` - NEW: Unit tests
+
+**Implementation Notes:**
+```typescript
+interface InvestigationGap {
+  startCommit: string;    // Hash of commit before gap
+  endCommit: string;      // Hash of commit after gap (the fix)
+  gapMinutes: number;
+  followedByFix: boolean;
+  component: string;
+}
+
+interface InvestigationMetrics extends MetricResult {
+  gaps: InvestigationGap[];
+  totalMinutes: number;
+  longestGap: number;
+  gapCount: number;
+}
+
+// Detection logic:
+// - Gap > 15 min AND < 120 min (SESSION_GAP)
+// - Next commit is type === 'fix'
+// - Same component as previous commit
+```
+
+**Test Strategy:**
+- Unit tests with mock commit lists at various time intervals
+- Edge cases: no gaps, all gaps, gaps at session boundaries
+
+---
+
+### Feature 3: Domain Cohesion Score
+
+**Priority:** P2
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] `src/metrics/cohesion.ts` analyzes files changed per commit
+- [ ] Domains extracted from top-level directories under `src/`
+- [ ] Commits touching 3+ domains flagged as "scattered"
+- [ ] Cohesion score = (cohesive commits / total) × 100
+- [ ] Rating: ELITE >80% | HIGH >60% | MEDIUM >40% | LOW <40%
+
+**Files Affected:**
+- `src/types.ts` - Add `CohesionMetrics` interface
+- `src/git.ts` - Add `getCommitFiles()` function (uses `git diff-tree`)
+- `src/metrics/cohesion.ts` - NEW: Cohesion calculation
+- `src/output/terminal.ts` - Display cohesion section
+- `tests/cohesion.test.ts` - NEW: Unit tests
+
+**Implementation Notes:**
+```typescript
+interface CohesionMetrics extends MetricResult {
+  avgDomainsPerCommit: number;
+  cohesiveCommits: number;     // 1 domain
+  scatteredCommits: number;    // 3+ domains
+  cohesionScore: number;       // 0-100%
+  scatteredList: Array<{       // For verbose output
+    hash: string;
+    domains: string[];
+  }>;
+}
+
+// Domain extraction:
+// src/fleet/... → "fleet"
+// src/missions/... → "missions"
+// server/... → "server" (top-level = domain)
+```
+
+**Test Strategy:**
+- Mock file lists with various domain distributions
+- Edge cases: single file, all same domain, all different
+
+---
+
+### Feature 4: Eldritch Horror Detector
+
+**Priority:** P2
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] `src/analyzers/eldritch.ts` scans for oversized functions
+- [ ] Functions >200 lines flagged as warning, >500 as critical
+- [ ] Integrates with `audit` command output
+- [ ] Provides file:line references for each horror
+- [ ] Tests with sample files
+
+**Files Affected:**
+- `src/types.ts` - Add `EldritchHorrorResult` interface
+- `src/analyzers/eldritch.ts` - NEW: Function length analysis
+- `src/commands/audit.ts` - Include eldritch detection
+- `src/output/terminal.ts` - Display eldritch section in audit
+- `tests/eldritch.test.ts` - NEW: Unit tests
+
+**Implementation Notes:**
+```typescript
+interface EldritchHorror {
+  file: string;
+  functionName: string;
+  lineStart: number;
+  lineCount: number;
+  severity: 'warning' | 'critical';
+}
+
+interface EldritchHorrorResult {
+  detected: boolean;
+  horrors: EldritchHorror[];
+  totalCount: number;
+  criticalCount: number;
+  warningCount: number;
+}
+
+// Detection approach (simple regex, not full AST):
+// Look for function/method declarations and count lines until closing brace
+// Languages: .ts, .js, .py, .go
+```
+
+**Test Strategy:**
+- Sample files with various function lengths
+- Edge cases: nested functions, arrow functions, class methods
+
+---
+
+### Feature 5: Extend Commit Types
+
+**Priority:** P1
+**Type:** refactor
+**Depends On:** None (prerequisite for Feature 1)
+
+**Acceptance Criteria:**
+- [ ] `tracer` type added to Commit type union
+- [ ] Git parser recognizes `tracer:` and `tb:` prefixes
+- [ ] Commit counts include tracer count
+- [ ] Backwards compatible (existing analysis unchanged)
+
+**Files Affected:**
+- `src/types.ts` - Add `tracer` to Commit type
+- `src/git.ts` - Update parser regex
+- `src/metrics/index.ts` - Add tracer to countCommitTypes
+
+**Test Strategy:**
+- Existing tests still pass
+- New commits with `tracer:` prefix correctly typed
+
+---
+
+### Feature 6: Update Documentation
+
+**Priority:** P3
+**Type:** docs
+**Depends On:** Features 1-4
+
+**Acceptance Criteria:**
+- [ ] README updated with new metrics descriptions
+- [ ] CHANGELOG updated with version entry
+- [ ] CLAUDE.md updated with new metric thresholds
+- [ ] docs/METRICS.md updated (if exists)
+
+**Files Affected:**
+- `README.md`
+- `CHANGELOG.md`
+- `CLAUDE.md`
+- `docs/ENHANCEMENT-PLAN.md` - Mark as IMPLEMENTED
+
+---
+
+## Implementation Order
+
+| Step | Feature | Depends On | Validation |
+|------|---------|------------|------------|
+| 1 | Feature 5: Extend Commit Types | - | `npm test` passes |
+| 2 | Feature 1: Tracer Bullet Tracking | Feature 5 | New tests pass, analyze shows tracers |
+| 3 | Feature 2: Investigation Gap Detection | - | New tests pass, analyze shows gaps |
+| 4 | Feature 3: Domain Cohesion Score | - | New tests pass, analyze shows cohesion |
+| 5 | Feature 4: Eldritch Horror Detector | - | New tests pass, audit shows horrors |
+| 6 | Feature 6: Update Documentation | 1-5 | README accurate |
+
+---
+
+## Beads Issues to Create
+
+After approval, these issues will be created:
+
+| ID | Title | Type | Priority | Depends On |
+|----|-------|------|----------|------------|
+| TBD | Epic: Vibe-Check Evolution v2.2 | epic | P1 | - |
+| TBD | Extend commit types to include tracer | task | P1 | Epic |
+| TBD | Implement tracer bullet tracking metric | feature | P1 | Commit types |
+| TBD | Implement investigation gap detection | feature | P1 | Epic |
+| TBD | Implement domain cohesion score | feature | P2 | Epic |
+| TBD | Implement eldritch horror detector | feature | P2 | Epic |
+| TBD | Update documentation for new metrics | task | P3 | All features |
+
+---
+
+## Version Bump
+
+This is a **MINOR** version bump (v2.1.0 → v2.2.0):
+- Adds new features (tracer tracking, investigation gaps, cohesion, eldritch)
+- Backward compatible (existing CLI and output unchanged)
+- No breaking changes
+
+---
+
+## Rollback Procedure
+
+If something goes wrong:
+1. `git revert` the feature commits
+2. Existing metrics continue to work (additive changes)
+3. No data migration needed (new fields are optional)
+
+---
+
+## Testing Strategy
+
+1. **Unit Tests** - Each new metric file has corresponding test file
+2. **Integration Tests** - Extend `cli.integration.test.ts` with new output validation
+3. **Manual Testing** - Run against Houston repo (50k+ lines, real data)
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npm test -- tests/tracers.test.ts
+
+# Manual validation
+node dist/cli.js --since "1 week ago" --repo /path/to/houston
+```
+
+---
+
+## Time Estimates
+
+| Feature | Effort |
+|---------|--------|
+| Feature 5: Extend Commit Types | 30 min |
+| Feature 1: Tracer Bullet Tracking | 1.5h |
+| Feature 2: Investigation Gap Detection | 2h |
+| Feature 3: Domain Cohesion Score | 2h |
+| Feature 4: Eldritch Horror Detector | 2h |
+| Feature 6: Documentation | 1h |
+| **Total** | **~9 hours** |
+
+---
+
+## Next Steps
+
+1. Review and approve this plan
+2. Run beads issue creation (after approval)
+3. `bd ready` to see unblocked issues
+4. `/implement` to execute
+
+---
+
+## Open Questions
+
+1. **Should tracer metrics affect overall rating?**
+   - Recommendation: Yes, but with lower weight initially
+   - Can calibrate based on user feedback
+
+2. **Should investigation gaps be surfaced in watch mode?**
+   - Recommendation: No, watch mode is real-time; gaps are retrospective
+
+3. **What file extensions should eldritch detector support?**
+   - Start with: `.ts`, `.js`, `.tsx`, `.jsx`, `.py`, `.go`
+   - Can extend later based on usage
+
+---
+
+**Output:** .agents/plans/2025-12-27-vibe-check-evolution-plan.md
+
+**Next:** Approve plan → Create beads issues → `/implement`