validate-branch

name	validate-branch
description	Run local validation checks for ZenUML web-sequence before pushing, opening a PR, or merging. Use when the user says "validate", "check branch", "run tests", "preflight", "is this ready", or before submit-branch or ship-branch. Covers Yarn/Vite/Jest/Playwright checks, build/release risk, and spot-check plans for UI/diagram changes (see spot-check skill).

Validate Branch

Verify the current branch is locally sane before it reaches GitHub Actions.

Repo Facts

• Repository: ZenUml/web-sequence
• Base branch: master
• Package manager for local development: Yarn (yarn install, yarn dev, yarn build)
• CI currently uses pnpm in GitHub Actions, so note any Yarn/pnpm divergence instead of hiding it.
• App dev server is Vite on http://127.0.0.1:3000 (Playwright can auto-start via pnpm dev).

Workflow

1. Check Scope

Run:

git status --short --branch
git diff --name-only master...HEAD

If the worktree has unrelated local changes, do not stage or revert them. Validate the current branch changes and mention the unrelated files in the report.

2. Choose Checks

Run the smallest set that gives real confidence:

• Always: yarn build
• Unit-test changes or shared logic: yarn test
• UI behavior changes: start yarn dev, test the changed flow in browser, and run yarn test:e2e when the smoke suite is relevant.
• Release/extension changes: yarn release after yarn build
• Firebase/functions changes: inspect functions/package.json and run the relevant functions build/test/deploy dry-run command if available.
• Lint-sensitive changes: yarn lint, but if local ESLint is blocked by missing eslint-config-synacor, report that as an environment/config blocker and continue with other checks.

Do not run expensive or stateful deploy commands unless the user explicitly asks.

3. Feature spot check (UI / diagram changes)

When to skip: docs-only, CI/workflow-only, unrelated skill files.

For changes under src/components, src/style.css, src/assets/tailwind.css, vite.config.js, e2e/, or @zenuml/core integration:

3a. Write a spot check plan first

Use the spot-check skill — write the plan (behavior, target URL, assertions, method) before touching the browser or Playwright.

3b. Choose how to test

Situation	Target
Branch not deployed yet	yarn dev → http://127.0.0.1:3000
Validating staging deploy	PW_BASE_URL=https://staging.zenuml.com + Playwright
@zenuml/core / preview iframe	Assert inside #demo-frame (see spot-check skill)
Broad DSL/renderer regression	Run e2e/tests/dsl-spot-check.spec.js as a recipe (optional)

3c. Execute the plan

Follow the spot-check skill workflow. Prefer Playwright CLI for repeatability; use browser MCP for ad-hoc steps.

For each [ ] assertion: interact → observe signal → screenshot diagram/preview when visual proof matters.

If every assertion passes: Step 3 PASS. If any fails: FAIL — include which assertion failed and evidence path; fix code, then re-run from §2.

Common gotchas: see spot-check skill (iframe scope, loginAndsaveMessageSeen, third-party console noise). Branch-specific:

• Dev vs CI package manager: local yarn build, CI pnpm build — run pnpm build if the change touches lockfile or Vite resolution.
• Empty preview canvas with passing text poll: capture render-diagram-* screenshot; layout/CSS regressions need visual evidence.

4. Report

Use this shape:

Validation: PASS|FAIL|PARTIAL
- Build: ...
- Tests: ...
- Browser smoke: ...
- Skipped: ... (reason)
- Unrelated local changes: ...

FAIL means a required check failed. PARTIAL means useful checks passed but one check could not run because of environment, credentials, missing config, or an intentionally skipped scope.

Rules

• Never mark validation PASS if a required check was skipped or blocked.
• Never clean, revert, or stage unrelated local files.
• Prefer fixing reproducible local failures before suggesting CI retry.
• Preserve the exact failing command and the important error lines in the final report.