---
description: Implement a task with vision alignment, design thinking, quality gates, and simulation coverage
argument-hint: <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:**

```bash
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