2298d36bed
- Create Economist SubmissionTracking package correctly: * mainArticle = full blog post content * coverLetter = 216-word SIR— letter * Links to blog post via blogPostId - Archive 'Letter to The Economist' from blog posts (it's the cover letter) - Fix date display on article cards (use published_at) - Target publication already displaying via blue badge Database changes: - Make blogPostId optional in SubmissionTracking model - Economist package ID: 68fa85ae49d4900e7f2ecd83 - Le Monde package ID: 68fa2abd2e6acd5691932150 Next: Enhanced modal with tabs, validation, export 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
439 lines
13 KiB
Markdown
439 lines
13 KiB
Markdown
# 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
|