Module

---
description: Define the next undefined module with types, traits, and stub implementations
allowed-tools: Read, Write, Edit, Bash, Glob
---

# Task: Define Next Module

You are a Rust API designer. Your task is to define the public interface for the next pending module.

## Input

- Module Analysis: @.claude/state/modules.json
- Progress Tracking: @.claude/state/skeleton-progress.json
- Project context from CLAUDE.md (auto-loaded)

## Preconditions

Before proceeding, verify:
1. `.claude/state/modules.json` exists
2. `.claude/state/skeleton-progress.json` exists (run `/skeleton:init` first if not)

## Your Process

### Step 1: Determine Next Module

1. Read `skeleton-progress.json` to get `defined_modules` list
2. Read `modules.json` to get `dependency_order` array
3. Find the first module in `dependency_order` that is NOT in `defined_modules`
4. This is the **target module**

**If all modules are defined**: Inform the user that skeleton generation is complete. Suggest next steps (e.g., running tests, starting implementation).

### Step 2: Verify Dependencies

Get the target module's `dependencies` from `modules.json`.

Verify ALL dependencies are in `defined_modules`. If not, there is a bug in `dependency_order` - report this error and stop.

### Step 3: Read Module Specification

From `modules.json`, extract for the target module:
- `id`: Module identifier
- `name`: Human-readable name
- `description`: What this module does
- `responsibilities`: List of what this module handles
- `public_interface.types`: Types to define
- `public_interface.traits`: Traits to define
- `public_interface.functions`: Functions to define
- `dependencies`: Other modules this depends on

### Step 4: Generate Module Content

Replace the placeholder content in `src/<module_id>.rs` (or `src/<module_id>/mod.rs`) with full definitions.

#### 4.1 Module Header

```rust
//! <module.name>
//!
//! <module.description>
//!
//! # Responsibilities
//!
//! <list each responsibility as bullet>

use crate::<dependency>::*;  // For each dependency

4.2 Type Definitions

For each type in public_interface.types:

/// <Inferred description based on type name and module context>
///
/// # Usage
///
/// <Brief usage context from responsibilities>
#[derive(Debug, Clone)]  // Add appropriate derives based on type purpose
pub struct TypeName {
    // Fields inferred from module responsibilities
    // Use appropriate Rust idioms
}

Or if it should be an enum:

/// <Description>
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EnumName {
    /// <Variant description>
    Variant1,
    /// <Variant description>
    Variant2,
}

4.3 Trait Definitions

For each trait in public_interface.traits:

/// <Trait description based on module responsibilities>
///
/// # Implementors
///
/// <Which types are expected to implement this>
pub trait TraitName {
    /// <Method description>
    fn method_name(&self, param: Type) -> Result<ReturnType, Error>;
}

4.4 Function Stubs

For each function in public_interface.functions:

/// <Function description>
///
/// # Arguments
///
/// * `param` - <description>
///
/// # Returns
///
/// <What it returns>
///
/// # Errors
///
/// <When it can fail>
pub fn function_name(param: Type) -> Result<ReturnType, Error> {
    todo!("Implement in phase X")  // Reference task-plan if available
}

4.5 Private Implementation Stub (if needed)

If the module has traits, provide a default implementor stub:

/// Default implementation of <TraitName>
pub struct <ModuleName>Impl;

impl TraitName for <ModuleName>Impl {
    fn method_name(&self, _param: Type) -> Result<ReturnType, Error> {
        todo!("Implement")
    }
}

Step 5: Verify Compilation

Run cargo check to ensure the module compiles.

If it fails:

1. Read the error message
2. Fix type mismatches, missing imports, or syntax errors
3. Re-run cargo check
4. Repeat until it passes

Step 6: Update Progress

Update .claude/state/skeleton-progress.json:

{
  "initialized": true,
  "defined_modules": ["types", "events", "<new_module>"],
  "last_module": "<new_module>",
  "last_updated": "<ISO timestamp>"
}

Output Summary

After completion, provide:

✓ Defined module: <module_id> (<module_name>)

  Types:    <count> defined
  Traits:   <count> defined  
  Functions: <count> stubbed

  Progress: <defined_count>/<total_count> modules

  Next: <next_module_id> (<next_module_name>)
        Run /skeleton:module to continue

If this was the last module:

✓ Skeleton generation complete!

  All <total_count> modules have been defined.
  
  Recommended next steps:
  1. Review generated code for accuracy
  2. Run cargo test (tests should compile but may not pass)
  3. Begin implementation with /spec <first_task_id>

Important Notes

• Every public item MUST have documentation comments
• Use todo!() macro for all function bodies
• Prefer Result<T, E> over panics for fallible operations
• Use module-specific error types where appropriate (or a shared Error type)
• Derive common traits: Debug, Clone, and PartialEq where sensible
• Keep types minimal - only fields clearly implied by responsibilities
• When uncertain about a type's structure, prefer flexibility (e.g., use generics or trait objects)