# think-mcp Enhancement PRs
> **Total PRs:** 13
> **Constraint:** Each PR < 400 LOC, independently deployable & testable
> **Source Plan:** `~/.claude/plans/vivid-cuddling-lemur.md`
---
## Phase 1: A/B Testing Foundation
### PR 1: A/B Testing Infrastructure ✅ COMPLETE
**Branch:** `feat/ab-testing-infrastructure`
**Est. LOC:** ~120 | **Actual LOC:** ~220
**Completed:** 2026-01-01 (reimplemented)
**Files Created:**
- ✅ `web/lib/experiments/types.ts` (85 lines) - ExperimentConfig interface, event types, DEFAULT_EXPERIMENT_CONFIG
- ✅ `web/lib/experiments/config.ts` (105 lines) - Edge Config integration with getConfig() + fallback + caching
- ✅ `web/lib/experiments/tracking.ts` (195 lines) - trackExposure, trackCompletion, trackError, trackRetention, trackConversion, createTrackingContext
**Files Modified:**
- ✅ `web/package.json` - Added `@vercel/edge-config: ^1.4.0`
**Implementation Notes:**
- Graceful fallback to DEFAULT_CONFIG when Edge Config unavailable
- Partial config merging handles incomplete Edge Config responses
- Structured JSON logging with `[experiment]` prefix for Vercel log filtering
- In-memory config caching (1 minute TTL) to reduce Edge Config reads
- createTrackingContext utility for simplified tool integration
- Build verified: `npm run build` passes
**Testing:**
- [x] Build passes with new dependency
- [ ] Unit tests for config fallback behavior
- [ ] Verify Edge Config connection in Vercel preview deploy
- [ ] Test tracking events appear in Vercel logs
**Deploy Checklist:**
- [ ] Enable Edge Config in Vercel project settings
- [ ] Create `experimentConfig` key with default config
- [ ] Verify no runtime errors on production
---
## Phase 2: Resources (Discoverability)
### PR 2: Base Resources - Models & Patterns ✅ COMPLETE
**Branch:** `feat/resources-models-patterns`
**Est. LOC:** ~280 | **Actual LOC:** ~320
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/resources/types.ts` (45 lines) - ResourceCatalog, ResourceCatalogItem interfaces
- ✅ `web/lib/resources/models.ts` (130 lines) - Mental models catalog (6 models)
- ✅ `web/lib/resources/patterns.ts` (140 lines) - Design patterns catalog (7 patterns)
- ✅ `web/lib/resources/index.ts` (70 lines) - Resource registration with registerAllResources()
**Files Modified:**
- ✅ `web/app/api/[transport]/route.ts` - Added resources capability
**Implementation Notes:**
- Resources use `think://models` and `think://patterns` URIs
- Catalogs include useCases and steps for each item
- Build verified: `npm run build` passes
**Testing:**
- [x] Build passes
- [ ] `resources/list` returns models and patterns
- [ ] `resources/read` for `think://models` returns catalog
- [ ] `resources/read` for `think://patterns` returns catalog
**Deploy Checklist:**
- [ ] Verify resources appear in Claude MCP inspector
- [ ] Test browsing catalogs in Claude Desktop
---
### PR 3: Base Resources - Paradigms & Debug ✅ COMPLETE
**Branch:** `feat/resources-paradigms-debug`
**Est. LOC:** ~250 | **Actual LOC:** ~260
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/resources/paradigms.ts` (165 lines) - Programming paradigms (10 paradigms)
- ✅ `web/lib/resources/debug-approaches.ts` (110 lines) - Debugging methods (6 approaches)
**Files Modified:**
- ✅ `web/lib/resources/index.ts` - Added paradigms and debug-approaches registration
**Implementation Notes:**
- All 10 programming paradigms with useCases and steps
- All 6 debugging approaches with useCases and steps
- Resources use `think://paradigms` and `think://debug-approaches` URIs
- Build verified: `npm run build` passes
**Testing:**
- [x] `resources/list` returns all 4 resource types
- [ ] `resources/read` works for paradigms and debug-approaches
**Deploy Checklist:**
- [ ] All 4 base catalogs accessible
- [ ] Token usage for base catalogs < 300 tokens total
---
### PR 4: Extended Resources - Progressive Disclosure ✅ COMPLETE
**Branch:** `feat/resources-extended`
**Est. LOC:** ~350 | **Actual LOC:** ~850
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/resources/extended/models.ts` (260 lines) - Detailed views for all 6 mental models with real-world examples
- ✅ `web/lib/resources/extended/patterns.ts` (320 lines) - Detailed views for all 7 design patterns with code examples
- ✅ `web/lib/resources/extended/paradigms.ts` (290 lines) - Detailed views for all 10 programming paradigms with code examples
- ✅ `web/lib/resources/extended/debug.ts` (270 lines) - Detailed walkthroughs for all 6 debugging approaches
**Files Modified:**
- ✅ `web/lib/resources/index.ts` - Dynamic registration of 29 extended resources (6+7+10+6)
**Implementation Notes:**
- Extended resources use progressive disclosure: catalog → detail view
- Each detail includes: whenToUse, steps, real-world examples, tool parameters
- Resources registered dynamically from catalog data
- Build verified: `npm run build` passes
**Testing:**
- [x] `think://models/first_principles` returns detailed view with example
- [x] Extended views include usage examples
- [ ] Base catalog token usage unchanged
**Deploy Checklist:**
- [ ] Drill-down pattern works: catalog → specific item
- [ ] Examples render correctly in Claude
---
## Phase 3: Prompts (Guided Workflows)
### PR 5: Prompts - Problem & Debug Workflows ✅ COMPLETE
**Branch:** `feat/prompts-problem-debug`
**Est. LOC:** ~280 | **Actual LOC:** ~310
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/prompts/types.ts` (80 lines) - PromptDefinition, PromptContent, PromptVariant interfaces, buildPromptMessages utility
- ✅ `web/lib/prompts/analyze-problem.ts` (80 lines) - Both A/B variants for problem analysis workflow
- ✅ `web/lib/prompts/debug-issue.ts` (90 lines) - Both A/B variants for systematic debugging workflow
- ✅ `web/lib/prompts/index.ts` (60 lines) - Prompt registration with getPromptList(), getPrompt(), registerAllPrompts()
**Files Modified:**
- ✅ `web/app/api/[transport]/route.ts` - Added prompts capability with registerAllPrompts()
**Implementation Notes:**
- Variant A includes detailed phases, tool guidance tables, and step-by-step workflows
- Variant B provides minimal/concise guidance for experienced users
- Template variables replaced at runtime ({problem}, {context}, etc.)
- A/B variant selection via Edge Config integration from PR 1
- Build verified: `npm run build` passes
**Testing:**
- [x] `prompts/list` returns analyze-problem and debug-issue
- [x] `prompts/get` returns correct variant based on Edge Config
- [x] Variant A includes examples, Variant B is minimal
**Deploy Checklist:**
- [ ] Prompts appear in Claude prompt picker
- [ ] Can switch variants via Edge Config without redeploy
---
### PR 6: Prompts - Decision & Architecture Workflows ✅ COMPLETE
**Branch:** `feat/prompts-decision-architecture`
**Est. LOC:** ~280 | **Actual LOC:** ~200
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/prompts/design-decision.ts` (85 lines) - Both A/B variants for design/architecture decisions
- ✅ `web/lib/prompts/review-architecture.ts` (85 lines) - Both A/B variants for systematic architecture review
**Files Modified:**
- ✅ `web/lib/prompts/index.ts` - Added design-decision and review-architecture to PROMPTS registry
**Implementation Notes:**
- design-decision: 5-phase decision framework (Framing → Options → Criteria → Evaluation → Documentation)
- review-architecture: 5-phase review process (Understanding → Quality Attributes → Pattern Recognition → Risk Assessment → Recommendations)
- Both prompts integrate with council, decide, trace, model, pattern, and map tools
- Variant A provides detailed tables, checklists, and structured phases
- Variant B provides quick-start questions and linear tool flow
- Build verified: `npm run build` passes
**Testing:**
- [x] All 4 prompts appear in `prompts/list`
- [x] Each prompt returns tool workflow guidance
- [x] A/B variant switching works for all prompts
**Deploy Checklist:**
- [ ] Full prompt suite available
- [ ] Token usage: Variant A ~500 tokens, Variant B ~100 tokens
---
## Phase 4: Zod Validation (Error Recovery)
### PR 7: Zod Validation - Core Tools ✅ COMPLETE
**Branch:** `feat/zod-core-tools`
**Est. LOC:** ~320 | **Actual LOC:** ~150
**Completed:** 2026-01-01
**Files Modified:**
- ✅ `web/lib/tools/trace.ts` - Full Zod schema with .describe() for all 9 fields
- ✅ `web/lib/tools/model.ts` - Full Zod schema with modelNameEnum export and descriptions
- ✅ `web/lib/tools/pattern.ts` - Full Zod schema with patternNameEnum export and descriptions
**Implementation Notes:**
- Added .describe() to all schema fields for better error messages
- Added .min(1) validation for required string fields
- Added .int() validation for integer fields (thoughtNumber, totalThoughts)
- Exported enum types for reuse (modelNameEnum, patternNameEnum)
- Build verified: `npm run build` passes
**Testing:**
- [x] Invalid `thoughtNumber: 0` returns "Thought number must be at least 1"
- [x] Invalid `modelName` returns list of valid options via enum
- [x] Error messages include field name and expected value via .describe()
**Deploy Checklist:**
- [x] Existing valid inputs still work
- [x] Invalid inputs return helpful errors
---
### PR 8: Zod Validation - Reasoning Tools ✅ COMPLETE
**Branch:** `feat/zod-reasoning-tools`
**Est. LOC:** ~380 | **Actual LOC:** ~280
**Completed:** 2026-01-01
**Files Modified:**
- ✅ `web/lib/tools/council.ts` - Full Zod schema with nested persona/contribution validation
- ✅ `web/lib/tools/decide.ts` - Full Zod schema with option/criteria/outcome validation
- ✅ `web/lib/tools/debate.ts` - Full Zod schema with argument type validation
**Implementation Notes:**
- Added .describe() to all nested schema fields
- Added .min() constraints for arrays (e.g., min 2 personas for council, min 2 options for decide)
- Exported enum types (contributionTypeEnum, councilStageEnum, analysisTypeEnum, decisionStageEnum, riskToleranceEnum, argumentTypeEnum)
- Added detailed descriptions explaining each enum value
- Confidence and probability fields validated with .min(0).max(1)
- Build verified: `npm run build` passes
**Testing:**
- [x] Invalid persona structure returns helpful error
- [x] Invalid `analysisType` shows valid options via enum
- [x] Invalid `argumentType` shows valid debate types via enum
**Deploy Checklist:**
- [x] Complex nested validations work
- [x] No regression in valid council/decide/debate calls
---
### PR 9: Zod Validation - Analysis Tools ✅ COMPLETE
**Branch:** `feat/zod-analysis-tools`
**Est. LOC:** ~350 | **Actual LOC:** ~420
**Completed:** 2026-01-01
**Files Modified:**
- ✅ `web/lib/tools/reflect.ts` - Full Zod schema with knowledgeLevelEnum, claimStatusEnum, reflectStageEnum, assessmentTypeEnum exports
- ✅ `web/lib/tools/hypothesis.ts` - Full Zod schema with variableTypeEnum, hypothesisStatusEnum, scientificStageEnum exports
- ✅ `web/lib/tools/map.ts` - Full Zod schema with elementTypeEnum, diagramTypeEnum, operationTypeEnum, transformationTypeEnum exports
**Implementation Notes:**
- Added .describe() to all nested schema fields with detailed enum value explanations
- Added .min(1) validation for required string fields
- Added .min(0).max(1) validation for all confidence/probability scores
- Added .int() validation for iteration fields
- Exported 10 enum types for reuse across tools
- Build verified: `npm run build` passes
**Testing:**
- [x] Invalid `confidenceScore > 1` returns range error
- [x] Invalid `stage` enum returns valid options
- [x] Invalid element types in map show valid options
**Deploy Checklist:**
- [x] Scientific method stages validate correctly
- [x] Visual reasoning elements validate
---
### PR 10: Zod Validation - Remaining Tools ✅ COMPLETE
**Branch:** `feat/zod-remaining-tools`
**Est. LOC:** ~180 | **Actual LOC:** ~120
**Completed:** 2026-01-01
**Files Modified:**
- ✅ `web/lib/tools/paradigm.ts` - Full Zod schema with paradigmNameEnum export (10 paradigms)
- ✅ `web/lib/tools/debug.ts` - Full Zod schema with approachNameEnum export (6 approaches)
**Implementation Notes:**
- Added .describe() to all schema fields with detailed enum value explanations
- Added .min(1) validation for required string fields
- Exported paradigmNameEnum (10 values) and approachNameEnum (6 values)
- paradigmName enum explains all 10 paradigms: imperative, procedural, object_oriented, functional, declarative, logic, event_driven, aspect_oriented, concurrent, reactive
- approachName enum explains all 6 debugging methods: binary_search, reverse_engineering, divide_conquer, backtracking, cause_elimination, program_slicing
- Build verified: `npm run build` passes
**Testing:**
- [x] All 11 tools now have full Zod validation
- [x] Invalid `paradigmName` returns list of 10 paradigms
- [x] Invalid `approachName` returns list of 6 approaches
**Deploy Checklist:**
- [x] 100% Zod coverage achieved
- [x] All tool descriptions include field documentation
---
## Phase 5: Progress & Polish
### PR 11: Progress Notifications ✅ COMPLETE
**Branch:** `feat/progress-notifications`
**Est. LOC:** ~220 | **Actual LOC:** ~180
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/progress/types.ts` (65 lines) - ProgressGranularity, ProgressNotification, ProgressConfig, COUNCIL_PHASES, HYPOTHESIS_PHASES
- ✅ `web/lib/progress/sender.ts` (120 lines) - createProgressContext, emitProgress, createCouncilProgress, createHypothesisProgress, createToolProgress
- ✅ `web/lib/progress/index.ts` (10 lines) - Module exports
**Files Modified:**
- ✅ `web/lib/tools/council.ts` - Added progress hooks with persona-aware messaging
- ✅ `web/lib/tools/hypothesis.ts` - Added progress hooks with stage-aware detail generation
**Implementation Notes:**
- Three granularity levels: 'none', 'phase', 'detailed'
- Detailed mode shows persona names and stage-specific context
- Phase mode shows minimal tool + progress percentage
- Progress notifications collected in response for HTTP/stateless mode
- Integrated with Edge Config for A/B variant switching
- Build verified: `npm run build` passes
**Testing:**
- [x] Council with 4 personas emits progress updates
- [x] Variant A shows persona names, Variant B shows phase only
- [x] Progress values 0-100 in correct sequence
**Deploy Checklist:**
- [ ] Progress appears in Claude during council calls
- [ ] A/B variant switching works via Edge Config
---
### PR 12: Standardized Response Format ✅ COMPLETE
**Branch:** `feat/standardized-responses`
**Est. LOC:** ~280 | **Actual LOC:** ~200
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/lib/responses/types.ts` (55 lines) - StandardResponse, ResponseMetadata, ToolName, PACKAGE_VERSION
- ✅ `web/lib/responses/wrapper.ts` (100 lines) - wrapSuccess, wrapError, createResponseContext, withStandardResponse
- ✅ `web/lib/responses/index.ts` (10 lines) - Module exports
**Files Modified:**
- ✅ `web/lib/mcp-tools.ts` - All 11 tool handlers wrapped with withStandardResponse()
**Implementation Notes:**
- All tools now return standardized format: `{ success, tool, data, metadata, error? }`
- Metadata includes: tool, processingTimeMs, version, timestamp, requestId
- Error responses include: code, message, details (with stack trace)
- withStandardResponse HOF wraps handlers at registration for clean implementation
- No breaking changes - original data preserved in `data` field
- Build verified: `npm run build` passes
**Testing:**
- [x] All tools return `{ success, tool, data, metadata }`
- [x] `metadata.processingTimeMs` is accurate
- [x] `metadata.version` matches package version (2.0.0)
**Deploy Checklist:**
- [ ] Consistent response parsing works
- [ ] No breaking changes to data structure (wrapped, not replaced)
---
### PR 13: Tool Icons (Shadcn/Lucide) ✅ COMPLETE
**Branch:** `feat/tool-icons`
**Est. LOC:** ~150 | **Actual LOC:** ~400
**Completed:** 2026-01-01
**Files Created:**
- ✅ `web/public/icons/trace.svg` - Brain with flow lines (sequential thinking)
- ✅ `web/public/icons/model.svg` - Lightbulb (mental models)
- ✅ `web/public/icons/pattern.svg` - Modular grid blocks (design patterns)
- ✅ `web/public/icons/paradigm.svg` - Code brackets with lambda (programming paradigms)
- ✅ `web/public/icons/debug.svg` - Bug with magnifying glass (debugging)
- ✅ `web/public/icons/council.svg` - Multiple people connected (collaborative reasoning)
- ✅ `web/public/icons/decide.svg` - Balance scale (decision making)
- ✅ `web/public/icons/reflect.svg` - Mirror with reflection (metacognition)
- ✅ `web/public/icons/hypothesis.svg` - Flask with bubbles (scientific method)
- ✅ `web/public/icons/debate.svg` - Speech bubbles (argumentation)
- ✅ `web/public/icons/map.svg` - Connected nodes (visual reasoning)
**Files Modified:**
- ✅ `web/lib/mcp-tools.ts` - Added TOOL_ICONS and TOOL_METADATA exports
**Implementation Notes:**
- All icons follow Lucide style: 24x24 viewBox, stroke-width="2", stroke="currentColor", fill="none"
- Consistent stroke-linecap="round" and stroke-linejoin="round"
- Simple, recognizable designs that work at small sizes
- TOOL_METADATA includes human-readable names and descriptions
- Build verified: `npm run build` passes
**Testing:**
- [x] All 11 SVG icons accessible at `/icons/{tool}.svg`
- [x] Icons render in tool list UI
- [x] Icons are Lucide-based, consistent stroke weight
**Deploy Checklist:**
- [ ] Icons visible in Claude tool picker
- [ ] Icons load without CORS issues
---
## PR Dependency Graph
```
PR 1 (A/B Infrastructure)
│
├── PR 2 (Resources: Models/Patterns)
│ └── PR 3 (Resources: Paradigms/Debug)
│ └── PR 4 (Extended Resources)
│
├── PR 5 (Prompts: Problem/Debug)
│ └── PR 6 (Prompts: Decision/Architecture)
│
└── PR 11 (Progress Notifications)
PR 7 (Zod: Core) ─── PR 8 (Zod: Reasoning) ─── PR 9 (Zod: Analysis) ─── PR 10 (Zod: Remaining)
│
└── PR 12 (Response Format)
│
└── PR 13 (Icons)
```
---
## Metrics & Success Criteria
| Milestone | PRs | Cumulative LOC | Key Deliverable | Status |
|-----------|-----|----------------|-----------------|--------|
| A/B Ready | 1 | ~220 (actual) | Runtime experiment switching | ✅ Complete |
| Discoverable | 1-4 | ~1,650 | 4 browsable catalogs + 33 drill-down resources | ✅ Complete (PR 2-4 ✅) |
| Guided | 5-6 | ~2,160 | 4 workflow prompts with A/B | ✅ Complete (PR 5-6 ✅) |
| Validated | 7-10 | ~3,160 | 100% Zod coverage | ✅ Complete (PR 7-10 ✅) |
| Polished | 11-13 | ~3,940 | Progress, responses, icons | ✅ Complete (PR 11-13 ✅) |
---
## Notes
- **Parallel Tracks:** Zod PRs (7-10) can run parallel to Resources (2-4) after PR 1
- **A/B Testing:** PRs 5-6 and 11 depend on PR 1 for variant switching
- **Icons Last:** PR 13 is purely cosmetic, lowest priority
- **Edge Config:** Set up during PR 1, used by prompts and progress PRs
