plan-feature

name	plan-feature
description	Plan a new CraveDB feature end-to-end. Use when: adding a new capability, designing a subsystem, planning a new module, proposing architecture changes. Produces a numbered design document in design/ and actionable checklist items in design/11-implementation-phases.md.
argument-hint	Describe the feature to plan

Plan Feature

Plan a new CraveDB feature by producing a design document and implementation checklist that adhere to project conventions.

When to Use

• Adding a new capability to CraveDB (e.g. replication, transactions, new storage format)
• Designing a new subsystem or module
• Proposing architecture changes that touch multiple modules
• Any work that needs a design document before implementation

Procedure

1. Gather Context

Before designing, understand the current state:

1. Read design/00-overview.md for architecture and core design decisions
2. Read design/11-implementation-phases.md to see what exists and what's planned
3. Read design/13-dependencies.md for current dependency constraints
4. Identify which existing modules the feature touches (read relevant design/NN-*.md files)
5. Check AGENTS.md for code style and toolchain constraints (nightly Rust, snafu errors, compio async, no unwrap, doc comments)

2. Research (if needed)

If the feature involves external systems or protocols:

1. Research prior art (other databases, established approaches)
2. Compare alternatives in a decision table (Pros / Cons / Decision)
3. Document why each rejected alternative was rejected

3. Write the Design Document

Create a new file at design/NN-<feature-name>.md where NN is the next available number.

Follow these conventions (derived from existing design docs):

• Title: # Feature Name (H1, single line)
• Structure: Use --- horizontal rules between major sections
• Tables: Use | - | style (single-dash separators)
• Code blocks: Always specify language (rust, plain, ```mermaid)
• Diagrams: Use Mermaid where architecture visualization helps
• Cross-references: Link to other design docs with relative paths: [09-public-api.md](09-public-api.md)
• Paragraphs: Single line per paragraph (no hard wraps), no matter how long

Required sections (adapt as needed):

# Feature Name

## Overview / Motivation
Why this feature exists, what problem it solves.

## Design
The technical design. May include subsections for:
- Data structures / types
- Algorithms / protocols
- Module layout
- Error handling approach

## Integration Points
How this feature connects to existing modules (Db, Engine, IO layer, etc.)

## Configuration
New Options fields, CLI args, or feature gates.

## Alternatives Considered
| Approach | Pros | Cons | Decision |

## Dependencies
New crates needed (with version, features, justification).

4. Update Implementation Phases

Edit design/11-implementation-phases.md:

1. Determine where the new phase belongs (after existing phases, or as a sub-section of an existing phase)
2. Add a new ## Phase N: <Feature Name> section with:
   • Goal line: one sentence describing the deliverable
   • Feature gate (if applicable): note #[cfg(feature = "...")]
   • Subsections grouped by file/module: ### <Subsection> (\src/path/file.rs`)`
   • Checklist items (- [ ]): each item is a single concrete task (one struct, one function, one test)

Checklist item conventions:

• Start with a verb: "Define", "Implement", "Add", "Integrate", "Unit tests:", "Integration test:"
• Include the type/function name in backticks
• Group by: dependencies/setup → types → core logic → integration → tests
• Mark dependencies between items via ordering (items earlier in the list are prereqs)

5. Update Dependencies (if needed)

If new crates are required, add them to design/13-dependencies.md in the appropriate section with:

• Crate name and version
• Purpose (one sentence)
• Which workspace modules use it

6. Validate

Check the plan for:

• No conflicts with existing phases or modules
• Adheres to AGENTS.md constraints (snafu errors, no unwrap, doc comments, nightly features documented)
• Feature-gated if it adds optional dependencies
• Tests specified for every non-trivial implementation item
• Design doc numbered correctly (no gaps or duplicates in design/)
• Cross-references to other design docs are correct

Conventions Reference

File numbering

Design docs are numbered sequentially: 00-overview.md, 01-types.md, ..., 14-wire-protocol.md. The next doc is 15-*.md.

Phase numbering

Phases in 11-implementation-phases.md are numbered sequentially. Insert new phases at the appropriate point (before "Polish & Optimization" which should always be last).

Feature gates

Optional features that add dependencies should be gated: define in Cargo.toml [features], use #[cfg(feature = "name")] in code, note in the phase that "All code in this phase is gated behind #[cfg(feature = \"name\")]."

Error handling

All new modules must define errors with snafu. Use context selectors, propagate with ?.

Testing expectations

• Unit tests for all new types and functions
• Integration tests for cross-module behavior
• Benchmarks for performance-sensitive code (noted as separate items)