marathon/.serena/memories/task_completion_checklist.md

Task Completion Checklist

When completing a task in Aspen, follow these steps to ensure code quality and consistency.

Pre-Commit Checklist

1. Code Formatting

cargo fmt

• Formats all code according to rustfmt.toml
• Must pass before committing
• Check with: cargo fmt -- --check

2. Linting

cargo clippy --all-targets --all-features

• Checks for common mistakes and anti-patterns
• Address all warnings
• For strict mode: cargo clippy -- -D warnings

3. Type Checking & Compilation

cargo check
cargo build

• Ensure code compiles without errors
• Check both debug and release if performance-critical:

  cargo build --release
  

4. Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run integration tests
cargo test --test sync_integration

• All existing tests must pass
• Add new tests for new functionality
• Integration tests for cross-component features

5. Platform-Specific Testing

iOS Simulator

cargo xtask ios-run

• Test on iOS Simulator (default: iPad Pro 12.9-inch M2)
• Verify Apple Pencil interactions if applicable
• Check logging output for errors

Physical Device (if iOS changes)

cargo xtask ios-device

• Test on actual iPad if Apple Pencil features are involved
• Verify Developer Mode is enabled

macOS Desktop

cargo run --package app --features desktop

• Test desktop functionality
• Verify window handling and input

6. Documentation

cargo doc --open

• Add doc comments to public APIs
• Update module-level documentation if structure changed
• Verify generated docs render correctly
• Update RFCs if architectural changes were made

Specific Checks by Change Type

For New Features

• Write RFC if architectural change (see docs/rfcs/README.md)
• Add public API documentation
• Add examples in doc comments
• Write integration tests
• Test on both macOS and iOS if cross-platform
• Update relevant memory files if workflow changes

For Bug Fixes

• Add regression test
• Document the bug in commit message
• Verify fix on affected platform(s)
• Check for similar bugs in related code

For Performance Changes

• Run benchmarks before and after

  cargo bench
  

• Document performance impact in commit message
• Test on debug and release builds

For Refactoring

• Ensure all tests still pass
• Verify no behavioral changes
• Update related documentation
• Check that clippy warnings didn't increase

For Dependency Updates

• Update Cargo.toml (workspace or specific crate)
• Run cargo update
• Check for breaking changes in changelog
• Re-run full test suite
• Test on both platforms

Before Pushing

Final Validation

# One-liner for comprehensive check
cargo fmt && cargo clippy --all-targets && cargo test && cargo xtask ios-run

Git Checks

• Review git diff for unintended changes
• Ensure sensitive data isn't included
• Write clear commit message (see code_style_conventions.md)
• Verify correct branch

Issue Tracking

• Update issue status (use GitHub issue templates)
• Link commits to issues in commit message
• Update project board if using one

Platform-Specific Considerations

iOS Changes

• Test on iOS Simulator
• Verify Info.plist changes if app metadata changed
• Check Entitlements.plist if permissions changed
• Test with Apple Pencil if input handling changed
• Verify app signing (bundle ID: G872CZV7WG.aspen)

Networking Changes

• Test P2P connectivity on local network
• Verify gossip propagation with multiple peers
• Check CRDT merge behavior with concurrent edits
• Test with network interruptions

Persistence Changes

• Test database migrations if schema changed
• Verify data integrity across app restarts
• Check SQLite WAL mode behavior
• Test with large datasets

UI Changes

• Test with debug UI enabled
• Verify on different screen sizes (iPad, desktop)
• Check touch and mouse input paths
• Test accessibility if UI changed

Common Issues to Watch For

Compilation

• Missing feature flags for conditional compilation
• Platform-specific code not properly gated with #[cfg(...)]
• Incorrect use of async/await in synchronous contexts

Runtime

• Panics in production code (should return Result instead)
• Deadlocks with locks (use parking_lot correctly)
• Memory leaks with Arc/Rc cycles
• Thread spawning without proper cleanup

iOS-Specific

• Using println! instead of tracing (doesn't work on iOS)
• Missing tracing-oslog initialization
• Incorrect bundle ID or entitlements
• Not testing on actual device for Pencil features

When Task is Complete

1. Run final validation:

   cargo fmt && cargo clippy && cargo test && cargo xtask ios-run
   

2. Commit with good message:

   git add .
   git commit -m "Clear, descriptive message"
   

3. Push to remote:

   git push origin <branch-name>
   

4. Create pull request (if working in feature branch):

   • Reference related issues
   • Describe changes and rationale
   • Note any breaking changes
   • Request review if needed

5. Update documentation:

   • Update RFCs if architectural change
   • Update memory files if workflow changed
   • Update README if user-facing change