Salesforce Learning Brief

Salesforce Learning Brief

Use this skill after evidence has been gathered and classified. The brief teaches a bounded Salesforce outcome without flattening product guarantees, recommendations, org assumptions, preview features, and practitioner judgment into one authoritative voice.

Input Gate

A valid input must provide:

• learner role, current level, and concrete learning outcome;
• an evidence or research packet with claim-to-source mapping;
• release/API/product context for changing behavior;
• visible gaps, contradictions, and claims that must not be taught as fact.

When evidence is missing, do not fill the lesson from memory. Route to architect/salesforce-learning-research, remain explicitly source-bounded, or return a partial brief whose unsupported sections are marked.

Brief Shape

Do not reproduce the entire research packet. The packet is evidence; the brief is instruction.

Role-Aware Teaching

Adjust examples and vocabulary without changing the facts.

State the assumed level—foundation, practitioner, or advanced—and define unfamiliar terms at first use. Do not oversimplify away load-bearing Salesforce constraints.

Claim-to-Teaching Rules

Every numeric limit, lifecycle date, feature status, command option, and release-sensitive behavior requires a nearby citation. Stable conceptual explanations can share citations at the paragraph or section level when the mapping remains unambiguous.

Explain in Layers

Use a consistent learning progression:

1. Definition — what the capability is, in official/current terminology.
2. Purpose — which problem it solves and which problem it does not solve.
3. Mental model — the few relationships the learner must keep straight.
4. Decision points — what changes the correct approach.
5. Procedure or pattern — the safe sequence to use.
6. Example — one scenario with explicit assumptions.
7. Failure modes — the two or three mistakes most likely to mislead this learner.
8. Verification — how to prove the learner's interpretation or configuration.

For advanced learners, compress definitions and deepen tradeoffs, evidence, and exceptions. For beginners, reduce branching but retain safety and context.

Examples Without Fabrication

A worked example must state:

• scenario and learner role;
• target product/release assumptions;
• object, metadata, or code names that are illustrative rather than claimed to exist;
• expected behavior;
• verification step;
• limits of what the example proves.

Use sample API names such as Priority_Reason__c only when clearly labeled illustrative. Never imply that a field, permission set, package, license, or org feature exists unless the evidence packet proves it.

For procedural lessons, show a dry-run, preview, scratch-org, or read-only verification path before any write. A learning brief does not authorize production mutation.

Knowledge Checks

Prefer questions that expose misconceptions:

• distinguish two neighboring concepts;
• choose an approach under a changed constraint;
• identify which statement is a guarantee versus a recommendation;
• identify missing org/release evidence;
• predict a failure mode and verification step.

Provide answers separately so the learner can self-test. Do not write trivia about UI label location unless the UI path is the learning outcome.

Recommended Workflow

1. Validate the packet and learner context with architect/salesforce-learning-research; preserve claim IDs and confirm role, level, outcome, time budget, and source boundary.
2. Select and sequence concepts from mental model to decision points to application, deferring neighboring topics that do not support the outcome.
3. Draft with claim discipline by mapping every material statement to evidence and retaining release, product, edition/license, API, org, and lifecycle qualifiers.
4. Demonstrate transfer with one worked example, explicit assumptions, failure modes, and a safe verification path.
5. Assess and practice with changed-constraint knowledge checks, answers, and one bounded practice task with acceptance checks and a stop condition.
6. Expose uncertainty and validate by listing unsupported/context-dependent claims under Do not teach as fact, running the bundled checker, and reviewing that every citation supports the claim attached to it.

Completion Checklist

• One measurable learner outcome is stated
• Role, level, time budget, and product/release context are explicit
• Prerequisites and official terminology are clear
• Facts, recommendations, inferences, assumptions, and unknowns remain distinguishable
• Release-sensitive and numeric claims have nearby citations
• One example declares assumptions and verification
• Security, permissions, limits, and target identity remain visible where relevant
• Knowledge checks test application and misconceptions
• A bounded practice task is included
• Unsupported claims are omitted or listed under Do not teach as fact
• The brief does not authorize or perform production changes

Output and Validation

Draft with templates/salesforce-learning-brief-template.md, then run:

python3 skills/admin/salesforce-learning-brief/scripts/check_salesforce_learning_brief.py --input path/to/learning-brief.md

The checker validates structure and citation signals; a human or independent reviewer must still confirm that each citation supports the associated claim.

Related Skills

• architect/salesforce-learning-research — required evidence acquisition, freshness, and contradiction handling.
• Domain skill for the topic — supplies practitioner workflow and Salesforce-specific gotchas after source verification.
• architect/salesforce-decision-analysis — use when the learner's real need is to choose among viable approaches rather than understand one topic.
• Agent output-format skills — convert a completed brief to other artifacts without changing its claims.

See the bundled references for beginner/advanced variants, teaching gotchas, and LLM failure modes.