Final README rewrite for clarity, impact, and stronger positioning

Author: Sai Shyam

README.md

@@ -4,33 +4,45 @@
 ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
-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.
+**Debug Salesforce deployment failures in seconds using AI-powered root cause analysis with Claude.**
+When a deployment fails, engineers waste time switching between logs, coverage reports, and static analysis tools to manually piece together what went wrong — this tool does that correlation automatically and tells you exactly what to fix first.
 
 > 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.
 
 ---
 
 ## Problem
 
-When a deployment fails, engineers read raw logs, pull coverage reports, and run PMD scans — then manually piece together why it broke across three disconnected tools.
+When a Salesforce deployment fails, the information you need is split across three tools that have no awareness of each other:
 
-- Deployment logs show *what* failed, not *why*
-- Coverage gaps and code violations have no visible connection to the error
-- Correlating all three manually is slow, error-prone, and blocks every release
+- The deployment log tells you `OpportunityService` threw a `NullPointerException` — but not why
+- The coverage report shows 62% — but has no connection to the exception
+- PMD flags 120 violations — but doesn't tell you which ones caused the failure
+
+An engineer must open all three, read each output, reason about the connections under pressure, and decide what to fix first. That process is slow, error-prone, and entirely manual.
+
+---
+
+## Solution
+
+This tool accepts your deployment metrics as a single JSON payload, sends them to Claude with a strict schema contract, and returns a structured diagnosis:
+
+- **Risks** — each issue ranked by severity with the specific component named
+- **Root causes** — the technical reason per component, not a restatement of the error
+- **Recommendations** — ordered P0 → P3, with exact fixes ready to act on
+
+Unlike traditional DevOps tools that surface logs and metrics, this system provides actionable insights and prioritizes fixes using LLM-based reasoning across all three signals simultaneously.
 
 ---
 
-## How This Differs from Standard DevOps Tools
+## How It 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
@@ -99,25 +111,27 @@ python main.py --input input.json --live
 
 ## Risk Scoring
 
-Coverage below 75% is a hard Salesforce platform blocker with no override — so it carries the highest weight. Active runtime failures block the pipeline immediately. Critical PMD violations are serious but do not prevent deployment on their own.
+Risk is derived from three dimensions that reflect Salesforce deployment reality:
 
-| Dimension | Max Points | Trigger |
+| Dimension | Max Points | Why it matters |
 |---|---|---|
-| Code coverage | +4 | < 75% — no override possible |
-| Deployment failures | +3 | Runtime errors (+2) and failed tests (+1) stack |
-| Critical PMD violations | +2 | SOQL in loops, hardcoded IDs — governor limit risk |
+| Code coverage | +4 | Below 75% is a hard platform blocker — no override possible |
+| Deployment failures | +3 | Runtime errors (+2) and failed tests (+1) stack — pipeline stops immediately |
+| Critical PMD violations | +2 | SOQL in loops, hardcoded IDs — governor limit failures under production load |
 
 | Score | Risk Level |
 |---|---|
 | 0–2 | 🟢 Low — deployment can proceed |
 | 3–5 | 🟡 Medium — quality issues, no blockers |
 | 6–10 | 🔴 High — at least one active blocker |
 
+Coverage carries the highest weight because it is the only signal that unconditionally blocks deployment with no workaround.
+
 ---
 
 ## Example: Debugging a Failed Salesforce Deployment
 
-A deployment fails during a sprint release. The engineer has three data points: coverage is below threshold, `OpportunityService` threw an exception, and the static analyser flagged violations.
+A deployment fails mid-sprint. The engineer has three data points — coverage below threshold, a `NullPointerException` in `OpportunityService`, and 120 PMD violations — with no obvious connection between them.
 
 ### Input
 
@@ -146,60 +160,58 @@ A deployment fails during a sprint release. The engineer has three data points:
   "risk_level": "High",
   "risks": [
     {
-      "issue": "Code coverage at 62% — 13 points below the 75% Salesforce deployment threshold",
+      "issue": "Code coverage at 62% — 13 points below the 75% deployment threshold, hard blocker",
       "severity": "Critical",
       "component": "Overall Org"
     },
     {
-      "issue": "NullPointerException in OpportunityService — all 3 dependent test methods failing, pipeline blocked",
+      "issue": "NullPointerException in OpportunityService — 3 test methods failing, pipeline cannot proceed",
       "severity": "Critical",
       "component": "OpportunityService"
     },
     {
-      "issue": "15 critical PMD violations — SOQL-in-loop patterns will trigger governor limit failures under production load",
+      "issue": "15 critical PMD violations — SOQL-in-loop and hardcoded record IDs confirmed, governor limit failures will occur under bulk record processing",
       "severity": "High",
       "component": "OpportunityService"
     }
   ],
   "root_causes": [
     {
-      "cause": "OpportunityService calls opp.Account.Name without a null-guard — Account is null because @TestSetup creates Opportunity records without inserting a parent Account first",
+      "cause": "OpportunityService accesses opp.Account.Name without a null-guard — Account is null because @TestSetup inserts Opportunity records without a parent Account, so every method that traverses the relationship throws at runtime",
       "component": "OpportunityService"
     },
     {
-      "cause": "The same @TestSetup gap suppresses execution of every method that traverses the Account relationship — this is why coverage dropped to 62%, not a separate coverage problem",
+      "cause": "The @TestSetup gap suppresses execution of all methods that depend on related Account data — coverage dropped to 62% as a direct consequence of the test failures, not as a separate problem",
       "component": "Overall Org"
     }
   ],
   "recommendations": [
     {
-      "action": "In OpportunityService, replace opp.Account.Name with opp.Account?.Name — the safe navigation operator prevents the NullPointerException when Account is not loaded",
+      "action": "In OpportunityService, replace opp.Account.Name with opp.Account?.Name — the safe navigation operator prevents the NullPointerException when Account is not populated on the record",
       "priority": "P0 - Immediate"
     },
     {
-      "action": "In OpportunityServiceTest @TestSetup, insert an Account record and set AccountId on each Opportunity before any test method runs — this unblocks all 3 failing tests and recovers coverage above 75% automatically",
+      "action": "In OpportunityServiceTest @TestSetup, insert an Account record first and assign its Id to AccountId on each Opportunity — this unblocks all 3 failing tests and recovers coverage above 75% automatically",
       "priority": "P0 - Immediate"
     },
     {
-      "action": "Run 'sf scanner run --category Performance --target force-app/main/default/classes/OpportunityService.cls' and move all SOQL calls outside loop bodies 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 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"
     }
   ]
 }
 ```
 
-### 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.
+- **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 under release pressure.
 - **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.
+- **What Claude identified beyond the raw input:** The input only states `"error": "NullPointerException"` and `"failed_tests": 3`. Nothing in the payload mentions `@TestSetup`, parent records, or the Account relationship. The causal link between the exception and the coverage drop was inferred — not extracted from the data.
+- **Time saved:** The manual correlation step — switching tools, reading outputs, reasoning about signal relationships — is eliminated. The fix list is ready before the editor is opened.
 
 ---
 
@@ -301,7 +313,8 @@ 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.
+Deployment logs and static analysis results are already captured by most pipeline configurations; this tool adds the reasoning layer on top of data teams already have.
+Native pipeline integration (GitHub Actions, Jenkins, Copado) is on the roadmap — the current CLI interface is the foundation for that.
 
 ---