Analyzing Architecture (Well-Architected Review)

Grade a Salesforce DX project against the Salesforce Well-Architected framework and produce an honest, evidence-backed report: a pillar-scored table for what's observable in code and metadata, plus a human checklist for the governance/process concerns a local repo can't reveal.

This skill is an orchestrator. It does not re-implement static analysis — it drives the analysis skills the plugin already ships and maps their output onto the Well-Architected pillars. It is read-only: it grades and recommends; it never edits, deploys, or deletes.

It also backs the architecture-review agent, which runs this exact workflow as a dedicated read-only reviewer. Invoke the agent for an end-to-end review; use this skill directly when you want the workflow inline in the current session.

Capability resolution

1. Skill-orchestrated review (this skill) — runs the observable checks by delegating to existing skills/MCP tools, scores each sub-pillar, and emits the manual checklist.
2. Direct CLI / grep — used only for the lightweight structural signals the rubric names (sharing keywords, legacy-tech file types, deploy strategy). Fine standalone, but skips the pillar scoring and the governance checklist this skill provides.
3. API — not applicable.

The rubric (read these first)

Before scoring, read the three reference files — they are the source of truth:

• references/well-architected-rubric.md — the full pillar → sub-pillar → criteria tree, each criterion tagged [observable] or [manual].
• references/observable-checks.md — each [observable] criterion mapped to its detection (skill / MCP tool / grep pattern) and the anti-pattern it flags.
• references/manual-review-checklist.md — the [manual] criteria as a copy-pasteable governance checklist.

Workflow

Step 1 — Scope the project

# Package directories + API version
cat sfdx-project.json

Establish:

• Package dirs (from packageDirectories[].path) — where the source lives.
• Inventory — count Apex classes, triggers, LWC bundles, Aura, Flows, objects:

  find <pkgdir> -name '*.cls' | wc -l
  find <pkgdir> -name '*.trigger' | wc -l
  find <pkgdir> -name '*.js-meta.xml' | wc -l   # LWC bundles
  

• Tooling signals — does the repo have tests (*Test.cls, __tests__/), CI (.github/workflows/), linting (.eslintrc*, .prettierrc*), a package.xml vs source/package strategy?
• Org connection — sf org display --json succeeds → org-dependent checks (OWD, permission sets) are in play; otherwise mark them manual.

Record the scope line for the report header.

Step 2 — Run the observable checks (delegate; don't re-scan)

Work through references/observable-checks.md. For the heavy lifting, delegate:

• Apex security + performance → dx-code-analyzer-run. It runs sf code-analyzer and classifies findings by severity. Map its rules onto the rubric:
  • ApexSOQLInjection, ApexCRUDViolation, ApexInsecureEndpoint, ApexBadCrypto → Secure
  • ApexSharingViolations → Secure (sharing) / Composable (separation)
  • OperationWithLimitsInLoop, OperationWithHighCostInLoop → Reliable / Automated
  • AvoidDebugStatements → Automated
• Inline SOQL parse + selectivity, compile-level diagnostics → platform-lsp-integrate (apex_diagnostics, lwc_diagnostics, check_soql_selectivity) when lsp_health is green → Reliable / Automated.
• OWD / sharing model / permission sets → platform-metadata-retrieve + sf org inspection, only if an org is connected → Secure.

For the lightweight structural signals, grep directly (patterns in references/observable-checks.md), e.g.:

# Secure — classes missing a sharing keyword
grep -rLE 'with(out)? sharing|inherited sharing' --include='*.cls' <pkgdir>

# Intentional — legacy tech still present
find <pkgdir> -name '*.workflow-meta.xml' -o -name '*.flowDefinition-meta.xml'
grep -rl '@future' --include='*.cls' <pkgdir>

# Composable — deploy strategy
ls manifest/package.xml 2>/dev/null            # package.xml-driven (anti-pattern past PoC)
grep -l '"path"' sfdx-project.json             # source/package strategy

# Composable — runtime config in custom settings vs CMT
find <pkgdir> -path '*objects*' -name '*.object-meta.xml' | xargs grep -l 'CustomSetting' 2>/dev/null

Collect every finding with file:line evidence. A check with no evidence is not a pass and not a fail — it's "not observable" and moves to the manual checklist.

Step 3 — Score each observable sub-pillar

Assign ✅ / ⚠️ / ❌ per sub-pillar using the thresholds in references/observable-checks.md:

• ✅ no anti-patterns found in the observable checks for that sub-pillar.
• ⚠️ low/moderate findings, or only some criteria observable.
• ❌ critical/high findings (e.g. SOQL injection, FLS bypass, SOQL-in-loop at scale).

Then roll the sub-pillar verdicts up to a pillar verdict (worst-of, with a note).

Step 4 — Emit the manual checklist

Copy the [manual] criteria from references/manual-review-checklist.md into the report as unchecked items, grouped by pillar. Label the section clearly: "not auto-graded — assess with your team." Do not guess at these; the point is to hand the developer a structured governance checklist, not to fake a score.

Step 5 — Report

Produce one report using the format below. Lead with pillar verdicts, then observable findings (Trusted/Secure first — never bury security under style), then the manual checklist, then recommended next steps that name the skill which would apply each fix.

Well-Architected Review — <project name>
Scope: <pkg dirs>, <N classes / M triggers / K LWC>, tests: <y/n>, CI: <y/n>, org: <connected alias / none>

PILLAR VERDICTS
  🛡️ Trusted     <✅|⚠️|❌>  (Secure …, Compliant …, Reliable …)
  ⚡ Easy         <✅|⚠️|❌>  (Intentional …, Automated …, Engaging …)
  🔁 Adaptable    <✅|⚠️|❌>  (Resilient …, Composable …)

OBSERVABLE FINDINGS  (graded from code + metadata)
  Sub-pillar | Verdict | Finding | Evidence (file:line / tool)

MANUAL REVIEW  (not auto-graded — assess with your team)
  [ ] <item>  …

RECOMMENDED NEXT STEPS
  - <highest-signal fix> → via `<skill>`

Examples

Example 1 — "Is this project well-architected?"

Scope the project, run all observable checks (delegating Apex analysis to dx-code-analyzer-run), score all three pillars, emit the full manual checklist, and report. This is the default full review.

Example 2 — "Review my project's security and governor-limit risk"

Narrow to the Secure and Reliable/Automated sub-pillars: run dx-code-analyzer-run with a security + performance selector, use platform-lsp-integrate check_soql_selectivity for selectivity, grep for missing sharing keywords. Score those sub-pillars; still emit the Secure/Compliant manual items (security matrix, encryption strategy). Skip the Adaptable deep-dive unless asked.

Example 3 — "Run a Well-Architected check before we package this for release"

Full review, weighting Composable (packageability — CMT vs custom settings, loose coupling, LATEST aliasing, no package.xml-driven deploys) and Resilient (source-tracked, CI, no failed deploys). Lead the report with the packageability readiness verdict.

Failure modes

Symptom	Cause	Recovery
dx-code-analyzer-run reports the analyzer isn't installed	Code Analyzer v5 missing	Note it in the report; fall back to grep-based structural checks for Apex and mark PMD-only criteria "not observable".
sf org display fails	No org connected	Mark OWD / permission-set / org-metadata criteria as manual; grade only file-based criteria.
LSP tools return lsp_disabled / no_apex_workspace	LSP off or no workspace	Skip the LSP-grounded checks; rely on dx-code-analyzer-run + grep. Note the gap.
No sfdx-project.json	Not an SFDX project	Stop — this skill reviews SFDX projects. Tell the developer.
Huge repo, scan is slow	Project-wide PMD + graph build	Scope dx-code-analyzer-run to the package dir; note that cross-file (sfge) findings may be partial.

Rules

• Read the three references/*.md files before scoring — the rubric is the source of truth.
• Delegate observable detection to existing skills/MCP tools; grep only for the lightweight structural signals the rubric names.
• Every observable finding carries file:line (or tool-result) evidence. No evidence → manual checklist, not the scored table.
• Never score a [manual] governance criterion from inference — list it for human review.
• Read-only: recommend fixes and name the skill that applies them (platform-apex-generate for Apex authoring / trigger refactoring); never edit, deploy, or delete.
• Lead with Trusted/Secure findings; don't bury security under style nits.
• Surface zero-finding sub-pillars briefly ("no issues found in observable checks") rather than omitting them.