Devlog System

Devlogs provide persistent memory across Claude Code sessions. They document work done on services - features, bugfixes, deployments, incidents, and research. Use devlogs to record what you did so future sessions have context.

When to Create Devlogs

Create a devlog when you:

• Complete a feature or significant change
• Fix a bug
• Deploy an application
• Investigate an incident
• Complete research or a spike
• Make configuration changes
• Want to record any notable work

Rule of thumb: If future you (or another agent) would benefit from knowing this happened, create a devlog.

Required Fields

Field	Type	Description
service_id	string	Must exist in the status page registry
log_type	enum	Category of work (see below)
title	string	Short summary of what was done
content	string	Full markdown details

Log Types

Type	When to Use	Example
feature	New functionality added	"Add user search endpoint"
bugfix	Defect corrected	"Fix null pointer in auth flow"
deployment	App deployed/redeployed	"Deploy v2.1.0 to production"
config	Configuration changes	"Update rate limits"
incident	Outage or issue response	"Database connection pool exhausted"
refactor	Code restructuring	"Extract auth into separate module"
research	Investigation, spikes, analysis	"Evaluate caching strategies"
note	General documentation	"Architecture decision record"

Severity Levels

Severity	When to Use
info	Normal documentation (default)
warning	Something concerning but not urgent
error	Problem occurred during work
critical	Major incident or breaking change

Creating a Devlog

Document a feature:

{
  "service_id": "jetta-sso",
  "log_type": "feature",
  "title": "Implement password reset flow",
  "content": "## Summary\nAdded complete password reset flow...\n\n## Changes\n- New endpoint POST /api/auth/reset\n- Email template for reset link\n- Token expiration handling\n\n## Testing\nManual testing complete, unit tests added.",
  "tags": ["authentication", "email"]
}

Document an incident:

{
  "service_id": "jetta-status",
  "log_type": "incident",
  "title": "API outage due to database connection pool",
  "content": "## Timeline\n- 14:30 UTC: Alerts fired...\n\n## Root cause\n...\n\n## Resolution\n...\n\n## Prevention\n...",
  "severity": "critical",
  "tags": ["outage", "database"]
}

Content Best Practices

Good Devlog Structure

## Summary
One-paragraph overview of what was done.

## Changes
- Specific change 1
- Specific change 2

## Technical Details
Any implementation notes, decisions made, trade-offs.

## Testing
How this was verified.

## Related
- Ticket: #123
- PR: aic-holdings/repo#45

What to Include

• What changed (be specific)
• Why it was needed (context)
• How it was implemented (key decisions)
• Verification (testing done)
• Links to tickets, PRs, or other resources

What to Avoid

• Overly brief entries ("Fixed bug")
• Implementation details without context
• Sensitive information (secrets, credentials)

User Configuration

Set your defaults so devlogs automatically use your info:

config_set key=github_username value=your-username
config_set key=author value="Your Name"

Common Patterns

After Completing a Ticket

1. Finish the work
2. Create devlog summarizing what was done
3. Mark ticket complete

Session Handoff

When ending a session with work in progress:

{
  "service_id": "current-service",
  "log_type": "note",
  "title": "Session handoff: Feature X in progress",
  "content": "## Status\n...\n\n## Next steps\n...\n\n## Open questions\n...",
  "tags": ["handoff", "in-progress"]
}