# Tractatus Framework Improvement Implementation Plan
**Date**: 2025-10-21
**Session**: 2025-10-07-001
**Based On**: Session effectiveness assessment (4/10 rating)

---

## Executive Summary

**Problem**: Framework is architecturally sound but behaviorally passive
- Hooks work (reactive enforcement) ✅
- But don't guide decisions (proactive assistance) ❌
- Metrics collected but not actionable ❌
- Rules exist but aren't consulted during work ❌

**Impact**: Framework missed 15+ inst_017 violations that existed for weeks

**Solution**: Implement 3 critical improvements to make framework ACTIVE, not passive

---

## Current vs Future State

### Current State (4/10)
```
┌─────────────────────────────────────────────────────────────┐
│  USER WORKS                                                 │
│                                                             │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐          │
│  │ Read     │ --> │ Edit     │ --> │ Commit   │          │
│  │ Files    │     │ Files    │     │ Changes  │          │
│  └──────────┘     └──────────┘     └──────────┘          │
│                                                             │
│  Framework Activity:                                        │
│  - Hooks validate (background, invisible)                   │
│  - Metrics collected (not surfaced)                         │
│  - Rules exist (not consulted)                              │
│                                                             │
│  Result: Violations slip through ❌                         │
└─────────────────────────────────────────────────────────────┘
```

### Future State (8/10)
```
┌─────────────────────────────────────────────────────────────┐
│  SESSION START                                              │
│  🔍 Scanning for prohibited terms...                        │
│      ⚠ Found 15 violations (inst_017)                       │
│      Run: node scripts/scan-violations.js --fix             │
│                                                             │
│  USER WORKS                                                 │
│                                                             │
│  ┌──────────┐     📋 Editing markdown?                     │
│  │ Edit     │         Rules: inst_016, inst_017, inst_018  │
│  │ README   │                                               │
│  └──────────┘     ┌──────────┐                             │
│                   │ Validate │                             │
│                   └──────────┘                             │
│                                                             │
│  💡 MetacognitiveVerifier:                                  │
│      Test failed 3 times - try minimal reproduction?        │
│      (inst_050)                                             │
│                                                             │
│  Result: Violations prevented proactively ✅                │
└─────────────────────────────────────────────────────────────┘
```

---

## 🔴 Improvement 1: Proactive Content Scanning

### Problem
- inst_017 violations (15+ instances of "guarantee") existed for weeks
- No automated detection until user manually requested audit
- Framework was REACTIVE, not PROACTIVE

### Solution
**File**: `scripts/framework-components/ProhibitedTermsScanner.js`

Automated scanner that:
1. Runs on session start
2. Scans user-facing files for prohibited terms
3. Reports violations immediately
4. Provides auto-fix suggestions

### Integration Points
1. **Session Init**: Show violations at startup
2. **Pre-Commit Hook**: Block commits with violations
3. **CLI Tool**: Manual scanning and fixing

### Example Output
```bash
▶ 7. Scanning for Prohibited Terms

  ⚠ Found violations in user-facing content:
    inst_017: 15 violations

  Run: node scripts/scan-violations.js --details
  Or:  node scripts/scan-violations.js --fix
```

### Effort & Impact
- **Development**: 5-7 hours
- **Impact**: Would have caught all 15 violations at session start
- **ROI**: HIGH - Prevents values violations before they reach production

---

## 🔴 Improvement 2: Context-Aware Rule Surfacing

### Problem
- 52 active rules - too many to remember
- Rules not surfaced during relevant activities
- Framework was invisible during decision-making

### Solution
**File**: `scripts/framework-components/ContextAwareRules.js`

Context detection system that:
1. Detects activity type (editing markdown, debugging, deploying)
2. Surfaces relevant rules for that context
3. Reduces cognitive load (show 3-5 rules, not 52)

### Context Mappings
```
editing_markdown    → inst_016, inst_017, inst_018 (content rules)
editing_public_html → inst_017, inst_041, inst_042 (values + CSP)
writing_tests       → inst_050, inst_051 (testing rules)
debugging           → inst_050, inst_024 (minimal repro, document)
deploying           → inst_038, inst_039 (pre-action, closedown)
```

### Example Output
```bash
📋 You're editing documentation. Remember:
   • inst_017: NEVER use prohibited terms: 'guarantee', 'guaranteed'
   • inst_016: Avoid fabricated statistics without sources
   • inst_018: Accurate status claims (proof-of-concept, not production-ready)

🔍 Hook: Validating file edit: docs/introduction.md
```

### Effort & Impact
- **Development**: 8-9 hours
- **Impact**: Makes 52 rules actionable when relevant
- **ROI**: HIGH - Guides decisions during work

---

## 🟡 Improvement 3: Active MetacognitiveVerifier

### Problem
- Spent 2+ hours debugging integration tests without framework guidance
- Made repeated attempts (trial and error)
- No suggestions like "Try minimal reproduction"

### Solution
**Enhanced**: `scripts/framework-components/MetacognitiveVerifier.service.js`

Pattern detection system that:
1. Logs activities (test runs, file edits, commands)
2. Detects patterns (repeated failures, same file edited 5+ times)
3. Surfaces relevant suggestions automatically

### Patterns Detected
```
repeated_test_failure    → Suggest: Create minimal reproduction (inst_050)
same_file_edited_5x      → Suggest: Make incremental changes (inst_025)
high_token_usage         → Suggest: Run pressure check (inst_034)
long_running_command     → Suggest: Use timeout or background execution
```

### Example Output
```bash
💡 MetacognitiveVerifier: Suggestions available

> node scripts/show-suggestions.js

💡 METACOGNITIVE SUGGESTIONS

1. Repeated test failures detected
   Related rules: inst_050

   • Create minimal reproduction case
   • Isolate the failing component
   • Check test setup (beforeAll/afterAll)
   • Verify dependencies are connected

2. File edited 7 times: tests/integration/api.auth.test.js
   Related rules: inst_025

   • Are you making incremental changes?
   • Test each change before the next
   • Document what you're learning
```

### Effort & Impact
- **Development**: 9-11 hours
- **Impact**: Guides debugging, reduces trial-and-error time
- **ROI**: MEDIUM-HIGH - Most helpful for complex problem-solving

---

## Implementation Roadmap

### Phase 1: Proactive Scanning (Week 1)
**Files to Create**:
- `scripts/framework-components/ProhibitedTermsScanner.js`
- `tests/unit/ProhibitedTermsScanner.test.js`
- `.git/hooks/pre-commit` (optional)

**Modifications**:
- `scripts/session-init.js` - Add scanning step

**Deliverable**: Session start shows violations immediately

---

### Phase 2: Context Awareness (Week 2)
**Files to Create**:
- `scripts/framework-components/ContextAwareRules.js`
- `scripts/framework-components/context-prompt.js` (CLI tool)

**Modifications**:
- `scripts/hook-validators/validate-file-edit.js` - Surface rules

**Deliverable**: Relevant rules shown during work

---

### Phase 3: Metacognitive Assistant (Week 3)
**Files to Create**:
- `scripts/hook-validators/log-activity.js` (post-tool hook)
- `scripts/framework-components/show-suggestions.js` (CLI tool)

**Modifications**:
- `scripts/framework-components/MetacognitiveVerifier.service.js` - Enhance

**Deliverable**: Framework provides suggestions during complex work

---

## Success Criteria

### Effectiveness Target
**Current**: 4/10  
**Target**: 8/10

### Quantitative Metrics

**Proactive Detection**:
- ✅ 100% of inst_016/017/018 violations caught on session start
- ✅ Pre-commit hook prevents violations (0% slip through)
- ✅ Scan time <5 seconds

**Context Awareness**:
- ✅ Relevant rules surfaced >90% of the time
- ✅ User surveys rate rules as helpful (>80%)
- ✅ Rule overhead <2 seconds per tool use

**Metacognitive Assistance**:
- ✅ Suggestions appear after 3rd repeated failure
- ✅ Pattern detection accuracy >80%
- ✅ User reports reduced debugging time (30%+ improvement)

---

## Resource Requirements

### Development Time
- **Phase 1**: 5-7 hours
- **Phase 2**: 8-9 hours
- **Phase 3**: 9-11 hours
- **Total**: 22-27 hours (3-4 weeks part-time)

### Testing Time
- **Unit Tests**: 5-6 hours
- **Integration Testing**: 3-4 hours
- **User Testing**: 2-3 hours
- **Total**: 10-13 hours

### Grand Total: 32-40 hours (1 month part-time)

---

## Risks & Mitigation

### Risk 1: Notification Fatigue
**Risk**: Too many suggestions become annoying

**Mitigation**:
- Rate limit to 1 suggestion per 10 minutes
- Allow `--quiet` mode
- User can configure threshold (3 failures vs 5)

### Risk 2: False Positives
**Risk**: Scanner flags legitimate uses

**Mitigation**:
- Comprehensive exclude patterns (tests, case studies)
- Easy whitelist mechanism
- Context-aware scanning

### Risk 3: Performance Impact
**Risk**: Scanning slows session start

**Mitigation**:
- Scan only user-facing files (not node_modules, tests)
- Run asynchronously, show when ready
- Cache results, re-scan only changed files

---

## Expected Outcomes

### Immediate Benefits (Phase 1)
1. Zero inst_017 violations in future commits
2. Violations caught before they reach production
3. User confidence in framework enforcement

### Medium-term Benefits (Phase 2)
1. Reduced cognitive load (don't need to remember 52 rules)
2. Rules become part of natural workflow
3. Faster decision-making with relevant context

### Long-term Benefits (Phase 3)
1. Reduced debugging time (30%+ improvement)
2. Better problem-solving patterns
3. Framework actively guides learning

---

## Next Steps

### Immediate
1. Review this plan with user
2. Get approval to proceed
3. Set up development branch

### Week 1
1. Implement ProhibitedTermsScanner.js
2. Write unit tests
3. Integrate with session-init.js
4. Test on current codebase

### Week 2
1. Implement ContextAwareRules.js
2. Build context mappings
3. Integrate with hooks
4. User testing

### Week 3
1. Enhance MetacognitiveVerifier
2. Implement pattern detection
3. Build CLI tools
4. Final integration testing

---

## Appendix: Technical Specifications

### ProhibitedTermsScanner API
```javascript
const scanner = new ProhibitedTermsScanner();

// Scan all files
const violations = await scanner.scan();

// Scan with options
const violations = await scanner.scan({
  silent: false,
  fixMode: false,
  staged: false  // Git staged files only
});

// Auto-fix (simple replacements)
const result = await scanner.autoFix(violations);
// => { fixed: 12, total: 15 }
```

### ContextAwareRules API
```javascript
const contextRules = new ContextAwareRules();

// Detect context
const contexts = contextRules.detectContext('public/index.html');
// => ['editing_public_html']

// Get relevant rules
const rules = contextRules.getRelevantRules('editing_public_html');
// => [{ id: 'inst_017', text: '...', quadrant: 'VALUES' }]

// Format for display
const message = contextRules.formatRulesForDisplay('editing_public_html');
// => "📋 You're editing public HTML. Remember:..."
```

### MetacognitiveVerifier API
```javascript
const verifier = new MetacognitiveVerifier();

// Log activity
verifier.logActivity({
  type: 'bash',
  command: 'npm test',
  exitCode: 1,
  duration: 5000
});

// Check patterns
verifier.checkPatterns(tokenCount);
// => Surfaces suggestions if patterns detected

// Clear suggestions
verifier.clearSuggestions();
```

---

## Conclusion

The Tractatus Framework has **excellent architecture** but **weak behavioral integration**. These 3 improvements transform it from a passive validator to an active assistant.

**Key Insight**: Framework needs to be PROACTIVE, not just REACTIVE.

**Bottom Line**: With these improvements, framework effectiveness goes from 4/10 to 8/10.

---

**Status**: Ready for implementation  
**Approval Required**: User sign-off to proceed  
**Timeline**: 1 month part-time development  
**Expected ROI**: High - Prevents violations, guides work, reduces debugging time

---

**Created**: 2025-10-21  
**Author**: Claude Code (Tractatus Framework v3.4)  
**Session**: 2025-10-07-001
