Commit Messages
Every section update in Supaspec creates a versioned commit with structured metadata. Good commit messages make version history useful and searchable.
Three Fields
required
message
A concise summary of the change, similar to a git commit subject line.
✓ “Add database schema for user auth”
✓ “Fix caching strategy for API calls”
✗ “Updated the file”
✗ “Changes”
optional
description
Extended context about what changed and why. Use this for details that don't fit in a single-line message.
optional
prompt
For AI agent changes, this documents the original user request. Answers the question: “Why did the agent make this change?”
How It Looks in the UI
Revision logs display entries like:
v4Claude Code“Add caching strategy for API calls”
Prompt: “Review the API section and add a caching strategy”
Added Redis caching layer for frequently accessed endpoints with 5-minute TTL.
Human vs Agent Edits
Human edits (web UI)
- • Message (from commit dialog)
- • Description (optional)
- • No prompt field
Agent edits (MCP tools)
- • Message (from agent)
- • Description (from agent)
- • Prompt (user's original request)
Best Practices
- ✓Be specific. Describe what changed, not that something changed. "Add API rate limiting" not "Update API."
- ✓Use imperative mood. "Add", "Fix", "Update", "Remove" — like git commit conventions.
- ✓Include prompts for agent changes. When agents edit specs, the prompt field creates a clear audit trail.
- ✓Keep messages under 72 characters. The first line should be scannable in the revision log.
- ✓Use description for details. Anything beyond a one-line summary belongs in the description field.