document dialectic a bit

Author: nikomatsakis

CLAUDE.md

@@ -2,157 +2,30 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-@prompts/project/ongoing-work-tracking.md
-@prompts/project/ai-insights.md
-
 ## Memory Bank Design Context
 
-### Maintenance & Workflow
-This mdBook content must be kept current as design evolves. "Checkpoint our work" includes:
-- Updating Current Design State with new insights/discoveries  
-- Moving completed items from Open Questions to Key Design Decisions
-- Documenting any design pivots or new principles discovered
-
-See project conventions:
-- GitHub tracking: @prompts/project/github-tracking-issues.md
-- Code documentation: @prompts/project/ai-insights.md
-
-### Vision & Goals
-@src/introduction.md
-
-### Design Foundation  
-@src/design-foundation.md
-
-### Current Design State
-@src/current-state.md
-(Check this section for latest open questions and discoveries)
-
-### Full Documentation
-@src/SUMMARY.md
-(Complete architecture, implementation details, research archive)
-
-## Project Overview
-
-Socratic Shell is a research experiment in deliberate AI-human collaboration design. It consists of two main MCP (Model Context Protocol) servers that enable structured collaboration patterns and pattern testing.
-
-### Core Components
-
-1. **socratic-shell** - Memory consolidation MCP server for intelligent information storage and retrieval
-2. **dialectic** - Pattern testing MCP server for evaluating collaboration approaches through structured conversation scenarios
-
-## Architecture
-
-```
-socratic-shell/
-├── socratic-shell/          # Main MCP server for memory operations
-│   └── src/socratic_shell/
-│       ├── server.py        # MCP server with consolidate/read_in/store_back tools
-│       └── models.py        # Pydantic models for memory operations
-├── dialectic/               # Pattern testing MCP server
-│   └── src/dialectic/
-│       ├── server.py        # MCP server with test_pattern tool
-│       ├── models.py        # Data models for pattern testing
-│       └── sampling.py      # Core sampling logic (placeholder)
-├── prompts/                 # User and project patterns
-├── insights/                # Research findings on collaboration
-├── work-tracking/           # Documentation on tracking approaches
-└── references/              # Research materials and background
-```
-
-## Common Development Commands
-
-### Running the Servers
+@src/memory-bank/README.md
 
-**Socratic Shell server:**
-```bash
-cd socratic-shell
-uv sync --quiet
-uv run python -m socratic_shell
-```
-
-**Dialectic server:**
-```bash
-./run-dialectic.sh
-# OR
-cd dialectic
-uv sync --quiet
-uv run python -m dialectic
-```
-
-### Testing and Code Quality
-
-**Run tests:**
-```bash
-cd dialectic  # or socratic-shell
-uv run pytest
-```
-
-**Linting and type checking:**
-```bash
-cd dialectic  # or socratic-shell
-uv run ruff check .
-uv run mypy src/
-```
-
-**Install development dependencies:**
-```bash
-cd dialectic  # or socratic-shell  
-uv sync  # Installs dev dependencies from pyproject.toml
-```
-
-## MCP Server Tools
-
-### Socratic Shell Tools
-- `consolidate` - Store insights/patterns with category and importance
-- `read_in` - Retrieve relevant memories based on query/context
-- `store_back` - Update existing memories with new insights
-
-### Dialectic Tools
-- `test_pattern` - Test collaboration patterns with multiple scenarios (currently returns placeholder results)
-
-## Work Tracking
-
-This repository uses the **ongoing files** approach for work tracking:
-
-- Create `.ongoing/task-name.md` files for active development work
-- Update status, next steps, and context as work progresses  
-- Delete files when work is complete
-- See `work-tracking/ongoing-files.md` for detailed conventions
-
-**Check current work:**
-```bash
-ls -la .ongoing/ 2>/dev/null || echo "No ongoing work tracked"
-grep -h "^## Status:" .ongoing/*.md 2>/dev/null || echo "No status found"
-```
-
-## Key Development Patterns
+### Maintenance & Workflow
+The mdBook whose table of contents lies in `src/SUMMARY.md` must be kept current as design evolves.
+The table of contents can be useful to find sources of additional information about the memory bank design.
 
-### Python Environment
-- Both servers use **uv** for dependency management
-- Python 3.11+ required
-- Pydantic for data models
-- MCP framework for server implementations
+### Checkpointing
 
-### Code Organization
-- Each server is self-contained in its own directory
-- Shared patterns documented in `prompts/` and `insights/`
-- Clear separation between MCP protocol handling and business logic
+When asked to "checkpoint our work", remember to take the following steps:
+- Update [Current Design State](./src/memory-bank/current-state.md) with new insights/discoveries  
+- Move completed items from Open Questions to Key Design Decisions
+- Document new principles discovered in the [Design Foundation](./src/memory-bank/design-foundation.md)
+- Add new questions to cover design pivots in the [FAQ](./src/memory-bank/faq.md)
 
-### Testing Strategy
-- `dialectic/` has placeholder MCP sampling capabilities (future: actual Claude API integration)
-- Test fixtures in `test/fixtures/` for system prompts and reminders
-- Pattern testing designed around real conversation scenarios
+## Dialectic testing tool
 
-## Important Files
+@src/dialectic/README.md
 
-- `run-dialectic.sh` - Quick start script for dialectic server
-- `prompts/user/main.md` - Core collaboration patterns (referenced by global CLAUDE.md)
-- `insights/*.md` - Research findings on effective AI-human collaboration
-- `work-tracking/*.md` - Documentation on different tracking approaches
+## Socratic Shell Conventions
 
-## Notes
+@src/prompts/project/github-tracking-issues.md
+@src/prompts/project/ai-insights.md
 
-- The `socratic-shell` server currently has dummy memory implementation
-- The `dialectic` server returns placeholder results until MCP sampling is fully implemented  
-- Both servers log operations to stderr for debugging
-- This is research code - focus on collaboration patterns over production polish
+@src/SUMMARY.md
+(Complete architecture, implementation details, research archive)

src/SUMMARY.md

@@ -16,6 +16,11 @@
 - [Vision and goals](./memory-bank/README.md)
 - [Design Foundation](./memory-bank/design-foundation.md)
 - [Current State](./memory-bank/current-state.md)
+- [Frequently asked questions](./memory-bank/faq.md)
+
+# Dialectic
+
+- [Introduction](./dialectic/README.md)
 
 # Appendices
 

src/dialectic/README.md

@@ -0,0 +1,48 @@
+# Dialectic Testing Tool
+
+Dialectic is a YAML-based test runner for validating collaboration patterns and prompt engineering approaches.
+
+## Purpose
+
+Test whether prompts produce expected behaviors by running conversation scenarios and validating:
+- Response content (what Claude says)
+- Tool usage (what Claude does)
+- Behavioral patterns (how Claude responds)
+
+## Usage
+
+```bash
+cd dialectic
+uv run python dialectic.py test-scripts/my-test.yaml
+```
+
+## Test Format
+
+```yaml
+name: "Test Name"
+description: "What this test validates"
+
+conversation:
+  - user: "User message"
+    expected_response:
+      should_contain: ["expected", "phrases"]
+      should_not_contain: ["forbidden", "phrases"]
+    expected_tools: []  # Empty = no tools should be called
+```
+
+## Key Features
+
+- **Fail-fast execution** - stops on first failure to avoid testing invalid conversation states
+- **Streaming output** - shows responses in real-time for debugging
+- **Tool parameter validation** - verifies correct parameters passed to tools
+- **Human-readable format** - easy to write and understand test cases
+
+## Current Status
+
+Working prototype using Claude Code SDK. Useful for testing prompt patterns before deploying them.
+
+## Development
+
+- Uses `uv` for dependency management
+- Fully typed with mypy type annotations
+- Run type checking: `uv run mypy src/`

src/memory-bank/README.md

@@ -32,4 +32,8 @@ The memory bank operates through three core operations:
 
 These operations integrate seamlessly with existing collaboration patterns, using natural conversation signals (from CLAUDE.md) as triggers rather than requiring explicit memory management.
 
-The system follows biological memory principles: frequent consolidation with natural decay, context-dependent retrieval, and intelligent forgetting that preserves signal while discarding noise.
+The system follows biological memory principles: frequent consolidation with natural decay, context-dependent retrieval, and intelligent forgetting that preserves signal while discarding noise.
+
+## Testing tool
+
+The dialectic testing tool is used