Improve docs

CHANGELOG.md

@@ -2,15 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [TODO]
 
 ## [1.5.0] - 2025-08-21
 
 ### Changes
-- !BREAKING! Revamp CMDx for clarity, transparency, and higher performance
+- BREAKING - Revamp CMDx for clarity, transparency, and higher performance
 
 ## [1.1.2] - 2025-07-20
 

LLM.md

@@ -587,6 +587,7 @@ end
 result = CalculateShipping.execute(destination: "New York, NY")
 
 CreateShippingLabel.execute(result)
+```
 
 ---
 
@@ -697,6 +698,7 @@ chain.outcome #=> "success"
 chain.results.each_with_index do |result, index|
   puts "#{index}: #{result.task.class} - #{result.status}"
 end
+```
 
 ---
 
@@ -1082,41 +1084,47 @@ CMDx provides robust exception handling that differs between the `execute` and `
 
 ## Exception Handling
 
+> [!IMPORTANT]
+> When designing tasks, try not to `raise` your own exceptions directly. Instead, use skip! or fail! to signal intent clearly. skip! communicates that the task was intentionally bypassed, while fail! marks it as an expected failure with proper handling. This keeps workflows observable, predictable, and easier to debug.
+
 ### Non-bang execution
 
 The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
 
 ```ruby
-class ProcessDocument < CMDx::Task
+class CompressDocument < CMDx::Task
   def work
-    raise UnsupportedFormat, "document format not supported"
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
-result = ProcessDocument.execute
+result = CompressDocument.execute(document_id: "unknown-doc-id")
 result.state    #=> "interrupted"
 result.status   #=> "failed"
 result.failed?  #=> true
-result.reason   #=> "[UnsupportedFormat] document format not supported"
-result.cause    #=> <UnsupportedFormat>
+result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
+result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
 ### Bang execution
 
 The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
 
 ```ruby
-class ProcessDocument < CMDx::Task
+class CompressDocument < CMDx::Task
   def work
-    raise UnsupportedFormat, "document format not supported"
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
 begin
-  ProcessDocument.execute!
-rescue UnsupportedFormat => e
+  CompressDocument.execute!(document_id: "unknown-doc-id")
+rescue ActiveRecord::NotFoundError => e
   puts "Handle exception: #{e.message}"
 end
+```
 
 ---
 
@@ -1371,6 +1379,7 @@ result
   .on_complete { |result| send_upload_notification(result) }
   .on_interrupted { |result| cleanup_temp_files(result) }
   .on_executed { |result| log_upload_metrics(result) }
+```
 
 ---
 
@@ -1440,6 +1449,7 @@ result
 result
   .on_good { |result| update_message_stats(result) }
   .on_bad { |result| track_delivery_failure(result) }
+```
 
 ---
 
@@ -1780,6 +1790,7 @@ end
 
 # Attributes passed as original attribute names
 ScheduleMaintenance.execute(scheduled_at: DateTime.new(2024, 12, 15, 2, 0, 0))
+```
 
 ---
 

docs/interruptions/exceptions.md

@@ -10,39 +10,44 @@ CMDx provides robust exception handling that differs between the `execute` and `
 
 ## Exception Handling
 
+> [!IMPORTANT]
+> When designing tasks, try not to `raise` your own exceptions directly. Instead, use skip! or fail! to signal intent clearly. skip! communicates that the task was intentionally bypassed, while fail! marks it as an expected failure with proper handling. This keeps workflows observable, predictable, and easier to debug.
+
 ### Non-bang execution
 
 The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
 
 ```ruby
-class ProcessDocument < CMDx::Task
+class CompressDocument < CMDx::Task
   def work
-    raise UnsupportedFormat, "document format not supported"
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
-result = ProcessDocument.execute
+result = CompressDocument.execute(document_id: "unknown-doc-id")
 result.state    #=> "interrupted"
 result.status   #=> "failed"
 result.failed?  #=> true
-result.reason   #=> "[UnsupportedFormat] document format not supported"
-result.cause    #=> <UnsupportedFormat>
+result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
+result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
 ### Bang execution
 
 The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
 
 ```ruby
-class ProcessDocument < CMDx::Task
+class CompressDocument < CMDx::Task
   def work
-    raise UnsupportedFormat, "document format not supported"
+    document = Document.find(context.document_id)
+    document.compress!
   end
 end
 
 begin
-  ProcessDocument.execute!
-rescue UnsupportedFormat => e
+  CompressDocument.execute!(document_id: "unknown-doc-id")
+rescue ActiveRecord::NotFoundError => e
   puts "Handle exception: #{e.message}"
 end
 ```