stemedb/.claude/commands/implement.md

description	argument-hint
Implement a task with vision alignment, design thinking, quality gates, and simulation coverage	<task-description>

Implement Task: $ARGUMENTS

You are implementing a task for Episteme (StemeDB). Follow this rigorous process.

---

Phase 1: Vision Alignment

Read and internalize the vision:

• Read vision.md to understand the core philosophy
• Read architecture.md to understand the system design
• Read roadmap.md to understand where we're headed

Answer before proceeding:

1. How does this task align with "Git for Truth" and the probabilistic knowledge lattice?
2. Does this task respect append-only semantics?
3. Which architectural tier does this touch (Spine, Lattice, or Cortex)?

If the task conflicts with the vision, STOP and explain the conflict to the user.

---

Phase 2: Code Understanding

Explore the existing codebase:

1. Use the Explore agent to find all files relevant to this task
2. Read the existing code thoroughly - understand patterns, not just syntax
3. Check ai-lookup/ for documented facts about related components
4. Check .claude/guides/ for relevant procedures

Document your understanding:

• What existing code does this task interact with?
• What patterns are already established that we must follow?
• Are there any technical debts or constraints to be aware of?

---

Phase 3: Design Thinking

Apply best practices and principles from "Philosophy of Software Design" by John Ousterhout:

1. Complexity is the enemy. Design for simplicity, not cleverness.
2. Deep modules over shallow modules. Hide complexity behind simple interfaces.
3. Define errors out of existence. Design APIs so invalid states are unrepresentable.
4. Strategic vs tactical programming. We're building for the long term, not quick wins.
5. Comments should describe what isn't obvious. Code tells how, comments tell why.

Design the implementation:

1. What is the minimal interface that solves this problem?
2. What complexity can we hide inside the module?
3. How will this decision look in 2 years? 5 years?
4. What are the failure modes and how do we handle them defensively?

Write down your design before coding:

• The public interface (traits, structs, functions)
• The internal implementation strategy
• Error handling approach
• Test strategy

---

Phase 4: Agent Selection & Implementation

Select the appropriate specialized agent based on the task domain:

Domain	Agent	Use When
Storage, WAL, LSM	storage-engine-architect	Write path, durability, crash recovery
Graph structures, concurrency	rust-graph-engine-architect	Lock-free structures, cache optimization
Lens system, queries	stemedb-lens-architect	Query resolution, ranking algorithms
Defensive patterns	defensive-systems-architect	Rate limiting, hostile input, circuit breakers
General Rust features	primary-developer	Feature implementation, refactoring

Delegate to the agent: Use the Task tool to spawn the selected agent with:

• The task description
• Your design from Phase 3
• Specific files to modify
• Constraints and patterns to follow

---

Phase 5: Quality Gates

Run all quality checks:

make quality

This runs:

• cargo fmt --check - Formatting
• cargo clippy -- -D warnings - Linting (zero warnings policy)
• jscpd - Code duplication detection
• cargo test - All tests pass

Code review checklist:

• No unwrap() or expect() in production code
• All public APIs have doc comments
• Error types are descriptive and actionable
• New code follows existing patterns
• No hardcoded values that should be configurable

If any quality gate fails, fix the issues before proceeding.

---

Phase 6: Simulation Coverage (steme-sim)

Every feature must be representable in the simulation.

The simulation (stemedb-sim / The Arena) validates StemeDB under adversarial conditions. Check simulation-vision.md for context.

Update the simulation to cover this feature:

1. Which agent persona exercises this feature?

   • Scientist (truth-seeking)
   • Troll (adversarial)
   • Believer (consensus-following)
   • Skeptic (variance-detecting)
   • Historian (context-preserving)

2. What scenario tests this feature?

   • Create or extend a scenario in the simulation config
   • Define success criteria (what should happen vs. what shouldn't)

3. What metrics should we track?

   • Add any new observability to the simulation metrics

If the simulation doesn't exist yet:

• Document how this feature WOULD be tested in the simulation
• Add a TODO in simulation-vision.md under Implementation Plan

---

Phase 7: Documentation

Update documentation:

• If new types/concepts: add to ai-lookup/
• If new procedures: add to .claude/guides/
• Update CLAUDE.md routing if this is a major feature
• Ensure code comments explain WHY, not just HOW

---

Output

When complete, provide:

1. Summary: What was implemented and why
2. Files Changed: List of modified files
3. Design Decisions: Key decisions and their rationale (referencing Philosophy of Software Design)
4. Quality Status: Output of make quality
5. Simulation Coverage: How this feature is validated in the simulation
6. Follow-up: Any remaining work or known limitations