Final polish: stronger hook, improved example impact, actionable outputs

Author: Sai Shyam

README.md

@@ -4,8 +4,8 @@
 ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
-When a Salesforce deployment fails, this tool identifies the root cause in seconds — not hours.
-It feeds deployment errors, coverage data, and PMD violations into Claude and returns a ranked diagnosis: exactly what broke, which component caused it, and what to fix first.
+Debug Salesforce deployment failures in seconds — Claude analyses your errors, coverage gaps, and PMD violations together and pinpoints the root cause instantly.
+No more manually reading logs across three tools — get a ranked, component-level diagnosis with exact fixes, ready to act on.
 
 > Salesforce's CLI tools produce structured JSON output that no open source tool currently cross-correlates into a ranked diagnosis. This project fills that gap — there is no equivalent in the Salesforce ecosystem today.
 
@@ -21,6 +21,18 @@ When a deployment fails, engineers read raw logs, pull coverage reports, and run
 
 ---
 
+## How This Differs from Standard DevOps Tools
+
+| | Traditional tools | This project |
+|---|---|---|
+| Output | Raw logs, metrics, violation counts | Root cause, ranked recommendations |
+| Signal handling | One tool per signal, no cross-referencing | All three signals correlated in one pass |
+| Next step | Engineer manually interprets and prioritises | Fix order is explicit — P0 first |
+
+Standard tools report faithfully. This tool reasons — it tells you which signal caused the others and what to fix first.
+
+---
+
 ## Why Claude
 
 Salesforce CLI, PMD, and coverage tools each report one signal in isolation — they show *what* happened, not *why*, and have no awareness of each other.
@@ -176,10 +188,19 @@ A deployment fails during a sprint release. The engineer has three data points:
 }
 ```
 
+### What this shows
+
 - **One root cause, three symptoms.** A single `@TestSetup` gap caused the exception, the 3 test failures, and the coverage drop — one fix resolves all of them.
 - **Exact fix, not general advice.** P0 recommendations name the specific call to change (`opp.Account.Name` → `opp.Account?.Name`) and exactly what to insert in the test setup.
 - **Prioritised.** Two P0 actions unblock the deployment. The P1 SOQL fix is scoped to a specific file and command.
 
+### Impact
+
+- **Without this tool:** An engineer opens the deployment log, sees a `NullPointerException`, then separately checks coverage (62% — why?), then runs PMD and gets 120 violations with no clear connection to the runtime error. Correlation is manual, slow, and easy to get wrong.
+- **With this tool:** One command surfaces that all three issues share a single root cause — a missing `Account` insert in `@TestSetup`. The fix is two lines of code, not three separate investigations.
+- **Time saved:** The manual process requires switching between three tools and reasoning about signal relationships under pressure. This tool does that step automatically and returns a prioritised fix list in seconds.
+- **Trust:** Every recommendation names the exact component, method, and code change — nothing generic, nothing to interpret before acting.
+
 ---
 
 ## Example: Multi-Component Failure — Governor Limit
@@ -277,6 +298,13 @@ Claude connected the `LimitException` to the SOQL-in-loop PMD violations — ide
 
 ---
 
+## Real-World Applicability
+
+This tool is designed to integrate directly into Salesforce DX workflows and CI/CD pipelines — the input schema maps to the JSON output of `sf project deploy` and `sf scanner run`, so deployment logs and static analysis results can be piped in automatically rather than collected manually.
+Native pipeline integration (GitHub Actions, Jenkins, Copado) is on the roadmap; the current CLI interface is the foundation for that.
+
+---
+
 ## Project Structure
 
 ```

sample_outputs/failure_output.json

@@ -38,11 +38,11 @@
       "priority": "P0 - Immediate"
     },
     {
-      "action": "Run 'sf scanner run --category Performance --target force-app/main/default/classes/OpportunityService.cls' — move all SOQL calls above loop bodies into a single Map<Id, SObject> query before the next production release",
+      "action": "Run 'sf scanner run --category Performance --target force-app/main/default/classes/OpportunityService.cls' — move all SOQL calls above loop bodies into a single typed query: Map<Id, Account> accountMap = new Map<Id, Account>([SELECT Id, Name FROM Account WHERE Id IN :accountIds])",
       "priority": "P1 - High"
     },
     {
-      "action": "Add 'sf scanner run --severity-threshold 2' and a minimum 80% coverage check to the CI pipeline — add both as required status checks on pull requests so regressions are caught before deployment",
+      "action": "Add two CI gates on pull requests: (1) 'sf scanner run --severity-threshold 2 --target force-app' to block on critical PMD violations; (2) parse 'sf project deploy start --test-level RunLocalTests --json' output and fail the build if result.numberTestsCompleted / result.numberTestsTotal falls below 0.80",
       "priority": "P2 - Medium"
     }
   ]

sample_outputs/healthy_output.json

@@ -3,24 +3,24 @@
   "risk_level": "Low",
   "risks": [
     {
-      "issue": "5 minor PMD violations remaining — no critical patterns detected",
+      "issue": "5 minor PMD violations remaining — no critical patterns detected, no deployment risk",
       "severity": "Low",
       "component": "Overall Org"
     }
   ],
   "root_causes": [
     {
-      "cause": "Minor PMD violations likely reflect naming conventions or style inconsistencies — no structural or governor-limit risk identified",
+      "cause": "Minor PMD violations at this score level typically indicate missing ApexDoc on public methods, naming convention deviations, or empty catch blocks — none of these patterns risk governor limits or runtime failures, but empty catch blocks silently suppress exceptions in production logs",
       "component": "Overall Org"
     }
   ],
   "recommendations": [
     {
-      "action": "Resolve remaining 5 PMD violations to achieve a fully clean static analysis baseline before the next release cycle",
+      "action": "Run 'sf scanner run --category Documentation,Style --target force-app --format json' to list the exact 5 violations — fix any empty catch blocks first (replace with System.debug(e.getMessage()) at minimum so exceptions surface in production logs), then address naming and ApexDoc violations",
       "priority": "P3 - Low"
     },
     {
-      "action": "Maintain 90%+ coverage by enforcing minimum coverage requirements in code review and CI pipeline gates",
+      "action": "Lock in the current health by adding 'sf scanner run --severity-threshold 3 --target force-app' as a required CI check on all pull requests — this prevents the 5 minor violations from growing into critical ones as new code is merged",
       "priority": "P3 - Low"
     }
   ]