diff --git a/pkg/mining/circuit_breaker.go b/pkg/mining/circuit_breaker.go
index f107efa..b3fb8bc 100644
--- a/pkg/mining/circuit_breaker.go
+++ b/pkg/mining/circuit_breaker.go
@@ -42,7 +42,8 @@ type CircuitBreakerConfig struct {
 	SuccessThreshold int
 }
 
-// DefaultCircuitBreakerConfig returns sensible defaults
+// cfg := DefaultCircuitBreakerConfig()
+// cb := NewCircuitBreaker("github-api", cfg)
 func DefaultCircuitBreakerConfig() CircuitBreakerConfig {
 	return CircuitBreakerConfig{
 		FailureThreshold: 3,
@@ -70,7 +71,7 @@ type CircuitBreaker struct {
 // if err == ErrCircuitOpen { /* fallback to cached result */ }
 var ErrCircuitOpen = NewMiningError(ErrCodeServiceUnavailable, "circuit breaker is open")
 
-// NewCircuitBreaker creates a new circuit breaker
+// cb := NewCircuitBreaker("github-api", DefaultCircuitBreakerConfig())
 func NewCircuitBreaker(name string, config CircuitBreakerConfig) *CircuitBreaker {
 	return &CircuitBreaker{
 		name:          name,
@@ -80,7 +81,7 @@ func NewCircuitBreaker(name string, config CircuitBreakerConfig) *CircuitBreaker
 	}
 }
 
-// State returns the current circuit state
+// if cb.State() == CircuitOpen { return nil, ErrCircuitOpen }
 func (cb *CircuitBreaker) State() CircuitState {
 	cb.mu.RLock()
 	defer cb.mu.RUnlock()
@@ -203,7 +204,7 @@ func (cb *CircuitBreaker) recordSuccess(result interface{}) {
 	}
 }
 
-// Reset manually resets the circuit breaker to closed state
+// cb.Reset() // force closed state after maintenance window
 func (cb *CircuitBreaker) Reset() {
 	cb.mu.Lock()
 	defer cb.mu.Unlock()
@@ -216,7 +217,7 @@ func (cb *CircuitBreaker) Reset() {
 	})
 }
 
-// GetCached returns the cached result if available
+// if result, ok := cb.GetCached(); ok { return result, nil }
 func (cb *CircuitBreaker) GetCached() (interface{}, bool) {
 	cb.mu.RLock()
 	defer cb.mu.RUnlock()