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

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.
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.
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

bash

# 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:

bash

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.:

bash

# 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.

text

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.

platform-architecture-analyze

NPX Install

Tags

SKILL.md Content

Analyzing Architecture (Well-Architected Review)

Capability resolution

The rubric (read these first)

Workflow

Step 1 — Scope the project

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

Step 3 — Score each observable sub-pillar

Step 4 — Emit the manual checklist

Step 5 — Report

Examples

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

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

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

Failure modes

Rules