Automatically maintains project documentation including CHANGELOG.md, README files, inline code documentation, and cross-references. Use proactively after implementing features, fixing bugs, making API changes, or completing significant work. Updates CHANGELOG.md with Conventional Commit format, adds README sections for new features, generates inline documentation for new functions/structs/components, and ensures documentation cross-references are up-to-date. Covers Rust doc comments, TypeScript JSDoc, Conventional Commits (feat/fix/docs/refactor/test/chore), and multi-level README organization.
This skill proactively maintains project documentation as you work, ensuring that changes are properly documented across CHANGELOG.md, README files, and inline code comments.
Automatically trigger this skill (proactively offer to use it) after:
Do NOT trigger for:
Location: Root /Users/cam/Developer/muni/CHANGELOG.md
Format: Conventional Commits with semantic versioning
Entry Structure:
## [Unreleased]
### Added
- New feature description with reference to files changed (e.g., bvr/firmware/crates/control/src/lib.rs:150-180)
- Another feature with link to relevant documentation
### Changed
- Modified behavior with migration notes if breaking
- Updated API with before/after examples
### Fixed
- Bug fix description with issue reference if applicable (#123)
### Deprecated
- Feature scheduled for removal with timeline
### Removed
- Removed feature with migration path
### Security
- Security fix (never include vulnerability details)
Conventional Commit Prefixes:
feat: New feature (user-facing)fix: Bug fixdocs: Documentation onlyrefactor: Code restructuring (no behavior change)perf: Performance improvementtest: Add/update testschore: Tooling, dependencies, build configstyle: Code style (formatting, no logic change)ci: CI/CD changesbuild: Build system changesKey Points:
## [Unreleased] until versioned#123### Changed with migration notesExample Entry:
## [Unreleased]
### Added
- Safety watchdog with 500ms timeout in `bvr/firmware/crates/control/src/lib.rs` to automatically transition to Idle mode when commands stop arriving
- E-stop state machine transitions in `bvr/firmware/crates/state/src/lib.rs` requiring explicit release before resuming operation
- LED feedback for rover modes: green pulse (teleop), cyan pulse (autonomous), red flash (e-stop)
### Fixed
- CAN bus frame parsing now includes bounds checking in `bvr/firmware/crates/can/src/vesc.rs:167-191` to prevent panics on malformed frames (#42)
See: changelog-format.md for complete formatting guide.
Strategy: Update appropriate README based on scope of change.
README Hierarchy:
/README.md # Project overview, quick start
/bvr/README.md # BVR rover-specific
/bvr/firmware/README.md # Firmware development guide
/bvr/cad/README.md # CAD system usage
/depot/README.md # Depot services overview
/depot/console/README.md # Console frontend development
/mcu/README.md # MCU firmware guide
What to Update:
README Update Rules:
Example README Addition:
### Safety Features
#### Watchdog Timer
The control system includes a command watchdog that monitors teleop connection health. If no commands are received for 500ms, the rover automatically transitions to Idle mode and stops all motors.
Configuration in `bvr/firmware/config/bvr.toml`:
```toml
[control]
command_timeout_ms = 500
See bvr/firmware/crates/control/src/lib.rs for implementation details.
### 3. Inline Documentation
**Rust Documentation Comments**:
**Module-level** (`//!` at top of `lib.rs`):
```rust
//! State machine and mode management for bvr.
//!
//! This module implements the rover's operational modes (Disabled, Idle, Teleop,
//! Autonomous, EStop, Fault) with safety-critical transition logic. The state
//! machine ensures that e-stop requires explicit release and that invalid
//! transitions are rejected.
//!
//! # Examples
//!
//! ```
//! let mut sm = StateMachine::new();
//! sm.handle(Event::Enable);
//! assert_eq!(sm.mode(), Mode::Idle);
//! ```
//!
//! # Safety
//!
//! E-stop transitions are one-way and require explicit `EStopRelease` event.
//! Always check `is_driving()` before sending motor commands.
Function-level (///):
/// Handles a state machine event and transitions to a new mode if valid.
///
/// # Arguments
///
/// * `event` - The event to process (Enable, Disable, EStop, etc.)
///
/// # Examples
///
/// ```
/// let mut sm = StateMachine::new();
/// sm.handle(Event::Enable);
/// assert_eq!(sm.mode(), Mode::Idle);
/// ```
///
/// # Safety
///
/// E-stop events are accepted from any mode but require explicit release.
pub fn handle(&mut self, event: Event) {
// ...
}
Struct/Enum-level:
/// Represents the rover's current operational mode.
///
/// The mode determines which operations are permitted. Use `is_driving()`
/// to check if motor commands should be sent, and `is_safe()` to check
/// if configuration changes are allowed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
/// Motors disabled, awaiting initialization
Disabled,
/// Ready state, motors enabled but stationary
Idle,
/// Under human control via teleop
Teleop,
/// Autonomous navigation active
Autonomous,
/// Emergency stop, requires explicit release
EStop,
/// Error state, requires fault clear
Fault,
}
TypeScript/React Documentation (JSDoc):
Function/Component:
/**
* Manages WebSocket connection to rover for real-time teleoperation.
*
* Handles binary protocol encoding/decoding, automatic reconnection with
* exponential backoff, and connection state management.
*
* @param address - WebSocket address (e.g., "ws://rover:4850")
* @returns Connection state and send function
*
* @example
* ```typescript
* const { connected, send } = useRoverConnection();
* if (connected) {
* send(encodeTwist({ linear: 1.0, angular: 0.0, boost: false }));
* }
* ```
*/
export function useRoverConnection(address: string) {
// ...
}
Interface:
/**
* Telemetry data received from rover at 20 Hz.
*
* Contains current operational mode, pose, velocity, power status,
* and temperature readings for all motors and controllers.
*/
export interface Telemetry {
/** Current operational mode (Idle, Teleop, etc.) */
mode: Mode;
/** Position and heading in world frame */
pose: Pose;
/** Current velocity command */
velocity: Twist;
/** Battery voltage and current */
power: PowerStatus;
/** Motor and controller temperatures (°C) */
temperatures: TempStatus;
}
When to Add Inline Documentation:
pub fn, TypeScript export)lib.rs)When NOT to Add:
Update cross-references when:
Files with Cross-References:
/Users/cam/Developer/muni/CLAUDE.md - Project overview (central reference)README.md files - Link to detailed docsCross-Reference Patterns:
<!-- Markdown links -->
See [firmware architecture](bvr/firmware/README.md) for details.
Refer to [safety checklist](.claude/skills/firmware-review/safety-checklist.md).
<!-- File path references -->
Implementation: `bvr/firmware/crates/state/src/lib.rs:50-120`
<!-- Code references with line numbers -->
The watchdog is implemented in bvr/firmware/crates/control/src/lib.rs:162-193
Automatically detect what needs documentation:
Check for new public APIs:
# Rust: Find pub fn without ///
grep -rn "pub fn" --include="*.rs" | grep -v "///"
# Rust: Find pub struct without ///
grep -rn "pub struct" --include="*.rs" | grep -v "///"
# TypeScript: Find export function without /**
grep -rn "export function" --include="*.ts" --include="*.tsx" | grep -v "/\*\*"
Check for missing CHANGELOG entries:
# Recent commits not in CHANGELOG
git log --since="1 week ago" --pretty=format:"%s" | grep -v "docs:" | grep -v "chore:"
Check for outdated documentation:
After completing work, identify:
Use git diff to see changes:
git diff --name-only
git diff --stat
Add entry under ## [Unreleased]:
Based on scope, update appropriate README:
For new or significantly changed code:
//! or top-level comment)If files moved or restructured:
CHANGELOG:
### Changed
- **BREAKING**: Renamed `set_mode()` to `handle_event()` in `state` crate for clarity
Migration:
```rust
// Before
sm.set_mode(Mode::Teleop);
// After
sm.handle(Event::Enable);
**README**:
Add migration guide section if significant.
### Security Fixes
**CHANGELOG** (never include vulnerability details):
```markdown
### Security
- Fixed input validation issue in teleop command handler
No public details until after coordinated disclosure.
CHANGELOG:
### Deprecated
- `old_function()` is deprecated and will be removed in v2.0. Use `new_function()` instead.
Inline Documentation:
/// Legacy function for backward compatibility.
///
/// # Deprecated
/// This function is deprecated since v1.5 and will be removed in v2.0.
/// Use [`new_function`] instead.
#[deprecated(since = "1.5.0", note = "use `new_function` instead")]
pub fn old_function() {
// ...
}
CHANGELOG Addition:
### Added
- Safety watchdog in `bvr/firmware/crates/control/src/lib.rs` monitors command reception and automatically transitions to Idle mode after 500ms timeout, preventing runaway rovers if connection is lost
README Update (bvr/firmware/README.md):
## Safety Features
### Command Watchdog
The control loop includes a command watchdog that monitors teleop connection health:
- Timeout: 500ms (configurable)
- Action: Automatic transition to Idle mode
- Reset: Fed on every valid command reception
**Configuration**:
```toml
[control]
command_timeout_ms = 500
Implementation: crates/control/src/lib.rs:162-193
**Inline Documentation**:
```rust
/// Command watchdog for safety monitoring.
///
/// Tracks the time since the last valid command was received. If the timeout
/// duration elapses without receiving commands, `is_timed_out()` returns true,
/// indicating that the rover should transition to a safe state.
///
/// # Examples
///
/// ```
/// let mut watchdog = Watchdog::new(Duration::from_millis(500));
/// assert!(watchdog.is_timed_out()); // Initially timed out
///
/// watchdog.feed(); // Reset timer
/// assert!(!watchdog.is_timed_out());
/// ```
///
/// # Safety
///
/// The watchdog timeout should be tuned to balance responsiveness with network
/// jitter. Too short causes false positives; too long delays safety response.
pub struct Watchdog {
timeout: Duration,
last_command: Option<Instant>,
}
CHANGELOG Addition:
### Fixed
- CAN bus VESC status frame parsing now validates buffer length before accessing bytes in `bvr/firmware/crates/can/src/vesc.rs:167-191`, preventing panics on malformed frames (#42)
No README change (implementation detail, not user-facing).
Inline Documentation (if not already present):
/// Parses VESC STATUS1 frame containing ERPM, current, and duty cycle.
///
/// # Arguments
///
/// * `data` - CAN frame payload (must be exactly 8 bytes)
///
/// # Returns
///
/// `Ok(())` if parsing succeeds, `Err(CanError::InvalidFrame)` if data is
/// too short or malformed.
///
/// # Safety
///
/// This function performs bounds checking before indexing into `data` to
/// prevent panics on malformed frames.
fn parse_status1(&mut self, data: &[u8]) -> Result<(), CanError> {
if data.len() < 8 {
warn!("STATUS1 frame too short: {} bytes", data.len());
return Err(CanError::InvalidFrame);
}
// ... safe indexing
}
✅ Good:
control crate with configurable max accel/decel values"❌ Bad:
✅ Good:
❌ Bad:
fn do_x())For more detailed information, see:
# Check for undocumented pub functions (Rust)
grep -rn "pub fn" bvr/firmware/crates --include="*.rs" | grep -v "///"
# Check for undocumented exports (TypeScript)
grep -rn "export function" depot/console/src --include="*.ts" --include="*.tsx" | grep -v "/\*\*"
# View recent commits for CHANGELOG
git log --since="1 week ago" --pretty=format:"%h %s"
# Check modified files
git diff --name-only HEAD~5..HEAD
下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer