Operations Logger Skill

Purpose

Central logging service for all Claude Code operations. Maintains comprehensive audit trail of all system activities, skill invocations, and state changes.

Tier

Tier 0 - Pre-Launch Foundation

When to Use

• Automatically invoked by all skills
• Manual logging of important events
• Debugging and troubleshooting
• Audit trail requirements
• Performance monitoring

Log Structure

Log Entry Format

{
  "timestamp": "2025-11-06T10:30:45.123Z",
  "level": "INFO|WARN|ERROR|DEBUG",
  "skill": "skill-name",
  "operation": "operation-type",
  "task_id": "task-001",
  "sprint_id": "sprint-001",
  "epic_id": "epic-001",
  "event": "descriptive-event-name",
  "details": {
    "custom": "fields",
    "as": "needed"
  },
  "duration_ms": 1234,
  "status": "success|failure|partial",
  "error": null,
  "artifacts": ["file1.py", "file2.md"],
  "metrics": {
    "lines_changed": 45,
    "tests_run": 8,
    "coverage": 85.5
  }
}

Log Levels

• DEBUG: Detailed diagnostic information
• INFO: General informational messages
• WARN: Warning conditions that should be reviewed
• ERROR: Error conditions requiring attention

Operation Types

Skill Operations

task.started: Task execution begins
task.completed: Task finished successfully
task.failed: Task execution failed
task.blocked: Task cannot proceed
task.retrying: Retrying failed task

skill.invoked: Skill execution starts
skill.completed: Skill finished
skill.error: Skill encountered error

test.started: Test execution begins
test.passed: Test passed
test.failed: Test failed
test.skipped: Test skipped

context.gathered: Context collection complete
context.saved: Context saved to disk
context.loaded: Context loaded from disk

System Operations

sprint.started: Sprint begins
sprint.completed: Sprint ends
milestone.reached: Milestone achieved
epic.started: Epic work begins
epic.completed: Epic finished

deployment.started: Deployment initiated
deployment.succeeded: Deployment successful
deployment.failed: Deployment failed
deployment.rollback: Rollback executed

regression.started: Regression suite starts
regression.completed: All tests complete
regression.failures: Tests with failures

Log Storage

Primary Log File

ai-state/operations.log

Rotating Logs

ai-state/logs/
├── operations-2025-11-06.log
├── operations-2025-11-05.log
├── errors-2025-11-06.log
└── performance-2025-11-06.log

Log Retention

• Operations logs: 30 days
• Error logs: 90 days
• Performance logs: 7 days
• Audit logs: 1 year

Integration Points

• Called by: All skills automatically
• Writes to: ai-state/operations.log
• Reads by: Monitoring, debugging, audit tools
• Triggers: Alerts on errors

Logging Standards

What to Log

✅ All task state changes ✅ Skill invocations and results ✅ Test executions and outcomes ✅ Deployment operations ✅ Error conditions ✅ Performance metrics ✅ Security events ✅ User actions

What NOT to Log

❌ Passwords or secrets ❌ Personal identifying information ❌ Large data payloads ❌ Verbose debug in production ❌ Redundant information

Query Interface

Recent Operations

tail -f ai-state/operations.log

Filter by Task

grep "task-001" ai-state/operations.log

Error Summary

grep "ERROR" ai-state/operations.log | tail -20

Performance Analysis

grep "duration_ms" ai-state/operations.log | analyze

Metrics Tracking

Performance Metrics

• Task execution duration
• Skill invocation time
• Test suite runtime
• Deployment duration
• API response times

Quality Metrics

• Test pass rate
• Code coverage
• Error frequency
• Retry attempts
• Rollback frequency

Business Metrics

• Tasks completed per sprint
• Milestone achievement rate
• Epic completion time
• Sprint velocity
• Deployment frequency

Alert Conditions

Critical Alerts

• ERROR level logs
• Task failures > 3
• Deployment rollbacks
• Security violations
• System crashes

Warning Alerts

• Performance degradation
• High retry rates
• Low test coverage
• Approaching deadlines
• Resource constraints

Example Log Entries

Task Execution

{
  "timestamp": "2025-11-06T10:30:45.123Z",
  "level": "INFO",
  "skill": "execute-tasks",
  "operation": "task.started",
  "task_id": "task-001",
  "sprint_id": "sprint-001",
  "event": "Starting payment form implementation",
  "details": {
    "orchestrator": "frontend-orchestrator",
    "estimated_hours": 8
  },
  "status": "success"
}

Test Failure

{
  "timestamp": "2025-11-06T11:15:22.456Z",
  "level": "ERROR",
  "skill": "test-orchestrator",
  "operation": "test.failed",
  "task_id": "task-001",
  "event": "Payment validation test failed",
  "details": {
    "test": "test_credit_card_validation",
    "expected": "valid",
    "actual": "invalid",
    "file": "tests/test_payment.py"
  },
  "error": "AssertionError: Card validation incorrect",
  "status": "failure"
}

Sprint Completion

{
  "timestamp": "2025-11-06T17:00:00.000Z",
  "level": "INFO",
  "skill": "sprint-completion-hook",
  "operation": "sprint.completed",
  "sprint_id": "sprint-001",
  "event": "Sprint 1 completed successfully",
  "metrics": {
    "tasks_completed": 12,
    "tasks_carried": 2,
    "velocity": 38,
    "test_coverage": 82.3,
    "bugs_fixed": 5
  },
  "status": "success"
}

Performance Considerations

• Asynchronous logging to prevent blocking
• Batch writes for efficiency
• Log rotation to manage disk space
• Compression for archived logs
• Indexing for quick searches

Security

• No sensitive data in logs
• Encrypted log transmission
• Access control on log files
• Audit trail for log access
• Compliance with regulations

Troubleshooting

Missing Logs

1. Check skill integration
2. Verify file permissions
3. Check disk space
4. Review log configuration
5. Test manual logging

Performance Issues

1. Check log volume
2. Review log level settings
3. Verify async logging
4. Check disk I/O
5. Consider log sampling