Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/change-management-and-training

change-management-and-training

Verified

Use this skill when planning user adoption, structuring Salesforce training materials, drafting release communications, or running a change impact assessment for a Salesforce rollout or update. Triggers: user adoption plan, training materials, release announcement, change impact, go-live communication, communication plan, training plan by persona, adoption metrics, LoginHistory adoption report, PromptAction, training sandbox, go-live checklist, post-go-live feedback, super user program, pilot group. NOT for org deployment mechanics or sandbox promotion — use admin/change-management-and-deployment. NOT for adoption of an Agentforce or Einstein AI feature — use admin/ai-adoption-change-management. NOT for configuring the in-app prompts themselves — use admin/in-app-guidance-and-walkthroughs.

scripts/check_change_management_and_training.py

View on GitHub
#!/usr/bin/env python3
"""Lint a change-management plan artefact (change-plan.yaml).

The artefact shape is demonstrated in ``references/worked-examples.md`` section 3.
This checker enforces the parts of it that silently rot when a plan is written by
hand or generated by an LLM:

1. ``change_plan`` header  -- id, deploy_date, owner and an allowed status.
2. ``personas``            -- every persona has an id, an allowed training_format
                              and a named owner.
3. ``communications``      -- every message has an audience, an allowed channel,
                              a deploy-relative ``D+n`` / ``D-n`` / ``D0`` timing,
                              and a named owner.
4. ``adoption_metrics``    -- every metric has a non-empty query and an owner.
                              An adoption target with no query is an opinion.
5. Referential integrity   -- every ``audience`` resolves to a persona id (or the
                              literal ``all``); every id in the document is unique;
                              every ``reads`` repo path exists under --repo-root.

Stdlib only: the YAML subset used by the artefact (block maps, block lists of
maps, block lists of scalars, quoted and bare scalars) is parsed here rather than
depending on PyYAML.

Usage:
    python3 check_change_management_and_training.py --file change-plan.yaml
    python3 check_change_management_and_training.py --file change-plan.yaml --repo-root .
    python3 check_change_management_and_training.py --manifest-dir project/plans

Exit code 0 when clean, 1 when any ISSUE is reported.
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

ALLOWED_STATUS = {"planned", "in-progress", "complete", "blocked", "cancelled"}

ALLOWED_TRAINING_FORMAT = {
    "hands-on-lab",
    "live-demo",
    "self-paced-video",
    "in-app-guidance",
    "trailhead-trail",
    "quick-reference",
    "none",
}

ALLOWED_CHANNEL = {
    "email",
    "chatter",
    "chatter-group",
    "slack",
    "in-app-guidance",
    "town-hall",
    "manager-cascade",
    "intranet",
    "survey",
}

WHEN_RE = re.compile(r"^D(0|[+-]\d+)$")

PLAN_GLOBS = ("*change-plan*.yaml", "*change-plan*.yml", "*adoption-plan*.yaml")


# --------------------------------------------------------------------------- #
# Minimal YAML-subset parser
# --------------------------------------------------------------------------- #


def _scalar(raw: str):
    """Convert a bare or quoted YAML scalar to a Python value.

    Quoted scalars keep everything between the quotes (so a SOQL string may hold
    ``:`` and ``#``); bare scalars lose any trailing ``  # comment``.
    """
    text = raw.strip()
    if text[:1] in ("'", '"'):
        closing = text.find(text[0], 1)
        if closing != -1:
            return text[1:closing]
        return text[1:]
    text = re.split(r"\s+#", text, maxsplit=1)[0].strip()
    if text in ("null", "~", ""):
        return None
    if text in ("true", "false"):
        return text == "true"
    if re.fullmatch(r"-?\d+", text):
        return int(text)
    return text


def _significant_lines(text: str) -> list[tuple[int, str, int]]:
    """Return (indent, content, line_number) for every non-blank, non-comment line."""
    out: list[tuple[int, str, int]] = []
    for number, raw in enumerate(text.splitlines(), start=1):
        if "\t" in raw:
            raw = raw.replace("\t", "  ")
        stripped = raw.strip()
        if not stripped or stripped.startswith("#"):
            continue
        indent = len(raw) - len(raw.lstrip(" "))
        out.append((indent, stripped, number))
    return out


def _parse_block(lines: list[tuple[int, str, int]], idx: int, indent: int):
    """Parse one block starting at lines[idx]; return (value, next_index)."""
    if idx >= len(lines):
        return None, idx

    if lines[idx][1].startswith("- ") or lines[idx][1] == "-":
        items: list = []
        while idx < len(lines):
            line_indent, content, _ = lines[idx]
            if line_indent != indent:
                break
            if not (content.startswith("- ") or content == "-"):
                break
            inner = content[2:].strip() if content.startswith("- ") else ""
            child_indent = indent + 2
            if inner == "":
                idx += 1
                if idx < len(lines) and lines[idx][0] > indent:
                    value, idx = _parse_block(lines, idx, lines[idx][0])
                else:
                    value = None
                items.append(value)
            elif ":" in inner and not inner[0] in ("'", '"'):
                sub: list[tuple[int, str, int]] = [(child_indent, inner, lines[idx][2])]
                idx += 1
                while idx < len(lines) and lines[idx][0] >= child_indent:
                    sub.append(lines[idx])
                    idx += 1
                value, _ = _parse_block(sub, 0, child_indent)
                items.append(value)
            else:
                items.append(_scalar(inner))
                idx += 1
        return items, idx

    mapping: dict = {}
    line_numbers: dict = {}
    while idx < len(lines):
        line_indent, content, number = lines[idx]
        if line_indent < indent:
            break
        if line_indent > indent:
            idx += 1
            continue
        if content.startswith("- ") or content == "-":
            break
        if ":" not in content:
            idx += 1
            continue
        key, _, rest = content.partition(":")
        key = key.strip()
        rest = rest.strip()
        line_numbers[key] = number
        idx += 1
        if rest:
            mapping[key] = _scalar(rest)
        elif idx < len(lines) and lines[idx][0] > line_indent:
            value, idx = _parse_block(lines, idx, lines[idx][0])
            mapping[key] = value
        else:
            mapping[key] = None
    mapping["__lines__"] = line_numbers
    return mapping, idx


def parse_yaml_subset(text: str) -> dict:
    lines = _significant_lines(text)
    if not lines:
        return {}
    value, _ = _parse_block(lines, 0, lines[0][0])
    return value if isinstance(value, dict) else {}


# --------------------------------------------------------------------------- #
# Checks
# --------------------------------------------------------------------------- #


def _rows(document: dict, key: str) -> list[dict]:
    value = document.get(key)
    if not isinstance(value, list):
        return []
    return [row for row in value if isinstance(row, dict)]


def _text(row: dict, key: str) -> str:
    value = row.get(key)
    return str(value).strip() if value is not None else ""


def check_header(document: dict) -> list[str]:
    issues: list[str] = []
    header = document.get("change_plan")
    if not isinstance(header, dict):
        return ["No 'change_plan:' block. The artefact needs a header with id, deploy_date, owner and status."]
    for field in ("id", "deploy_date", "owner"):
        if not _text(header, field):
            issues.append(f"change_plan is missing '{field}'.")
    status = _text(header, "status")
    if status and status not in ALLOWED_STATUS:
        issues.append(
            f"change_plan status '{status}' is not one of {sorted(ALLOWED_STATUS)}."
        )
    elif not status:
        issues.append("change_plan is missing 'status'.")
    return issues


def check_personas(document: dict) -> list[str]:
    issues: list[str] = []
    personas = _rows(document, "personas")
    if not personas:
        return ["No 'personas:' rows. A change plan with no personas cannot target training or comms."]
    for index, persona in enumerate(personas, start=1):
        label = _text(persona, "id") or f"personas[{index}]"
        if not _text(persona, "id"):
            issues.append(f"{label}: missing 'id'.")
        training_format = _text(persona, "training_format")
        if not training_format:
            issues.append(
                f"{label}: missing 'training_format'. Use 'none' to record a persona "
                f"deliberately left untrained."
            )
        elif training_format not in ALLOWED_TRAINING_FORMAT:
            issues.append(
                f"{label}: training_format '{training_format}' is not one of "
                f"{sorted(ALLOWED_TRAINING_FORMAT)}."
            )
        if not _text(persona, "owner"):
            issues.append(f"{label}: missing 'owner'. A persona with no owner has no trainer.")
        status = _text(persona, "status")
        if status and status not in ALLOWED_STATUS:
            issues.append(f"{label}: status '{status}' is not one of {sorted(ALLOWED_STATUS)}.")
    return issues


def check_communications(document: dict) -> list[str]:
    issues: list[str] = []
    messages = _rows(document, "communications")
    if not messages:
        return ["No 'communications:' rows. Every change plan needs at least one message."]
    for index, message in enumerate(messages, start=1):
        label = _text(message, "id") or f"communications[{index}]"
        if not _text(message, "id"):
            issues.append(f"{label}: missing 'id'.")
        if not _text(message, "audience"):
            issues.append(f"{label}: missing 'audience'.")
        channel = _text(message, "channel")
        if not channel:
            issues.append(f"{label}: missing 'channel'.")
        elif channel not in ALLOWED_CHANNEL:
            issues.append(f"{label}: channel '{channel}' is not one of {sorted(ALLOWED_CHANNEL)}.")
        when = _text(message, "when")
        if not when:
            issues.append(f"{label}: missing 'when'. Use a deploy-relative offset such as D-10, D0 or D+14.")
        elif not WHEN_RE.match(when):
            issues.append(
                f"{label}: when '{when}' is not deploy-relative. Use D-10, D0 or D+14 so the "
                f"schedule survives a slipped deploy date."
            )
        if not _text(message, "owner"):
            issues.append(f"{label}: missing 'owner'. A message with no owner is a message nobody sends.")
        status = _text(message, "status")
        if status and status not in ALLOWED_STATUS:
            issues.append(f"{label}: status '{status}' is not one of {sorted(ALLOWED_STATUS)}.")
    return issues


def check_adoption_metrics(document: dict) -> list[str]:
    issues: list[str] = []
    metrics = _rows(document, "adoption_metrics")
    if not metrics:
        return [
            "No 'adoption_metrics:' rows. Without them there is no way to tell adoption "
            "from optimism after go-live."
        ]
    for index, metric in enumerate(metrics, start=1):
        label = _text(metric, "id") or f"adoption_metrics[{index}]"
        if not _text(metric, "id"):
            issues.append(f"{label}: missing 'id'.")
        if not _text(metric, "query"):
            issues.append(
                f"{label}: missing 'query'. An adoption metric that cannot be expressed as a "
                f"SOQL query or a report definition will not be measured."
            )
        if not _text(metric, "owner"):
            issues.append(f"{label}: missing 'owner'.")
    return issues


def check_references(document: dict, repo_root: Path | None) -> list[str]:
    issues: list[str] = []
    personas = _rows(document, "personas")
    persona_ids = {_text(p, "id") for p in personas if _text(p, "id")}

    for section in ("communications", "feedback_loop"):
        for index, row in enumerate(_rows(document, section), start=1):
            audience = _text(row, "audience")
            label = _text(row, "id") or f"{section}[{index}]"
            if audience and audience != "all" and audience not in persona_ids:
                issues.append(
                    f"{label}: audience '{audience}' does not match any persona id "
                    f"({sorted(persona_ids)}) and is not 'all'."
                )

    seen: dict[str, str] = {}
    for section in ("personas", "communications", "adoption_metrics", "feedback_loop"):
        for row in _rows(document, section):
            row_id = _text(row, "id")
            if not row_id:
                continue
            if row_id in seen:
                issues.append(
                    f"Duplicate id '{row_id}' in '{section}' (already used in '{seen[row_id]}')."
                )
            else:
                seen[row_id] = section

    if repo_root is not None:
        for section in ("personas", "adoption_metrics"):
            for index, row in enumerate(_rows(document, section), start=1):
                label = _text(row, "id") or f"{section}[{index}]"
                reads = row.get("reads")
                if not isinstance(reads, list):
                    continue
                for entry in reads:
                    if not isinstance(entry, str):
                        continue
                    if not (repo_root / entry).exists():
                        issues.append(
                            f"{label}: reads '{entry}' does not exist under {repo_root}."
                        )
    return issues


def check_plan_file(path: Path, repo_root: Path | None) -> list[str]:
    try:
        text = path.read_text(encoding="utf-8")
    except OSError as error:
        return [f"Could not read {path}: {error}"]

    document = parse_yaml_subset(text)
    if not document:
        return [f"{path}: no parseable YAML content found."]

    issues: list[str] = []
    issues.extend(check_header(document))
    issues.extend(check_personas(document))
    issues.extend(check_communications(document))
    issues.extend(check_adoption_metrics(document))
    issues.extend(check_references(document, repo_root))
    return [f"{path.name}: {issue}" for issue in issues]


def collect_plan_files(args: argparse.Namespace) -> tuple[list[Path], list[str]]:
    if args.file:
        path = Path(args.file)
        if not path.exists():
            return [], [f"Plan file not found: {path}"]
        return [path], []

    directory = Path(args.manifest_dir)
    if not directory.exists():
        return [], [f"Manifest directory not found: {directory}"]

    found: list[Path] = []
    for pattern in PLAN_GLOBS:
        found.extend(sorted(directory.rglob(pattern)))
    unique = sorted(set(found))
    if not unique:
        return [], [
            f"No change-plan artefact found under {directory}. Expected a file matching "
            f"one of {list(PLAN_GLOBS)} — see references/worked-examples.md section 3."
        ]
    return unique, []


def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Lint a Salesforce change-management plan artefact (change-plan.yaml).",
    )
    parser.add_argument(
        "--file",
        help="Path to a single change-plan YAML artefact.",
    )
    parser.add_argument(
        "--manifest-dir",
        default=".",
        help="Directory to search for change-plan artefacts (default: current directory).",
    )
    parser.add_argument(
        "--repo-root",
        help="Repo root used to resolve 'reads:' paths. Omit to skip path resolution.",
    )
    return parser.parse_args(argv)


def main(argv: list[str] | None = None) -> int:
    args = parse_args(argv)

    repo_root: Path | None = None
    if args.repo_root:
        repo_root = Path(args.repo_root)
        if not repo_root.exists():
            print(f"ISSUE: repo root not found: {repo_root}")
            return 1

    paths, issues = collect_plan_files(args)
    for path in paths:
        issues.extend(check_plan_file(path, repo_root))

    if not issues:
        checked = ", ".join(p.name for p in paths)
        print(f"No issues found ({checked}).")
        return 0

    for issue in issues:
        print(f"ISSUE: {issue}")
    return 1


if __name__ == "__main__":
    sys.exit(main())
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall