dev-workflow-validate-change

name	dev-workflow-validate-change
description	Visually validate code changes by analyzing the git diff, identifying affected screens, and capturing screenshots via Maestro. Delegates to maestro-take-screenshots and maestro-explore skills. Use when the user says "validate change", "visual check", "screenshot my changes", "validate the app", or wants to see what their code changes look like on a device.

Validate Change

Analyze the current branch's diff against its base, determine which screens are affected, navigate to each one on a live device via Maestro, and capture screenshots for visual validation.

All captured screenshots and assets are saved to ./maestro/assets/<branchname>/.

Prerequisites

• A device/simulator must be running with the current build installed (the build should include the changes being validated)
• Maestro CLI installed

Workflow

Step 1: Analyze Diff — Screens and Accounts

Analyze the git diff to identify which screens are affected and which test accounts are needed.

BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
ASSETS_DIR="./maestro/assets/${BRANCH_NAME}"
mkdir -p "${ASSETS_DIR}"
git diff main...HEAD --name-only

If on a branch created from another feature branch, detect the parent (see dev-workflow-create-pr for parent-branch detection logic) and diff against that instead.

1a. Map files to screens

Changed file pattern	Affected screen
src/features/<area>/screens/<Screen>.tsx	That screen directly
src/features/<area>/components/*	Screens in that feature area
src/features/<area>/hooks/*	Screens in that feature area
src/shared/components/**	Any screen using that component — grep for imports to narrow down
src/shared/hooks/**	Any screen using that hook — grep for imports to narrow down
src/features/navigation/*	Dashboard (landing screen) + any restructured routes
GraphQL/query files	Screens that use those queries — grep for query name imports
Style/theme files	Dashboard as a representative sample

Feature area → tab mapping (for navigation):

Feature area	Tab / entry point
dashboard	Dashboard tab (landing)
portfolio	Portfolio tab (id: portfolio-screen-tab)
account, profile	Profile tab (id: profile-screen-tab)
contributions	Profile tab → plan details / contributions
auth	Login screen (pre-auth)
onboarding	Onboarding flow (special entry)

If more than 5 screens are affected, prioritize:

1. Directly changed screen files
2. Screens in the same feature area as changed components
3. Skip shared-component consumers unless the change is visually significant

1b. Determine test accounts

Pick the test account(s) by examining which data shapes / account types the changed code touches. Also check existing maestro flows for the affected screens — they already specify the right DEFAULT_USERNAME.

# Find existing flows for the affected screens and extract their test accounts
grep -r 'DEFAULT_USERNAME' maestro/flows/<feature-area>/

Test account reference:

Account	Username	Use when
Single 401k (Defcon)	[e-mail]	Default for most screens
Multiple 401k (Defcon)	[e-mail]	Multi-plan 401k logic, account switcher
Multiple account types	[e-mail]	Account chooser, mixed account views
Personal IRA	[e-mail]	IRA-specific screens, IRA contributions
SEP IRA	[e-mail]	SEP IRA plan details
IRA + HSA	[e-mail]	Mixed unsupported account handling
Defcon + HSA	[e-mail]	HSA-related dashboard views
Defcon + Cash	[e-mail]	Cash account dashboard views
Year-in-review	[e-mail]	Annual statements

Selection heuristics:

• If the diff touches IRA-specific code (file paths contain ira, Ira, or IRA type checks), use [e-mail]
• If the diff touches account switching, account selectors, or multi-account layouts, use [e-mail]
• If the diff touches SEP IRA, use [e-mail]
• If the diff is generic / shared UI, use [e-mail] (the default)
• If the change affects rendering that varies by account type, capture with multiple accounts to cover the most variation in one login

When multiple account types are needed (e.g., a shared component that renders differently per account type), plan separate capture passes — one login per account type.

Step 2: Confirm Targets and Accounts

Present the identified screens and test accounts using AskQuestion:

• Title: "Screens to Validate"
• Question: "Based on the diff, here's the capture plan:\n\nScreens:\n[list of screens]\n\nTest account(s):\n[account(s) and why]\n\nOutput directory: ./maestro/assets/<branchname>/\n\nHow should I proceed?"
• Options:
  • id: "all", label: "Screenshot all of them"
  • id: "adjust", label: "Let me adjust the list"
  • id: "skip", label: "Skip validation"

If "adjust": ask the user conversationally which screens to add/remove and which accounts to use. If "skip": end the workflow.

Step 3: Capture Screenshots

For each target screen, delegate to the existing maestro skills:

3a. If a clear navigation path is known

Use the maestro-take-screenshots skill. Provide it:

• Target: the screen name
• Capture type: screenshot
• Output name: validate-<screen-name>
• Output directory: ./maestro/assets/<branchname>/

3b. If the navigation path is unclear

Use the maestro-explore skill first to find the screen, then take the screenshot once found.

3c. Capture sequence

Process screens in navigation-efficient order to minimize backtracking:

1. Group by tab (dashboard screens first, then portfolio, then profile)
2. Within a tab, capture shallow screens before deep ones
3. Login once; reuse the session across all captures

Step 4: Present Results

After all screenshots are captured, summarize:

Visual Validation Results:

Screen                    | Status
--------------------------|--------
DashboardScreen           | Captured
PortfolioScreen           | Captured
SettingsScreen            | Captured (via maestro-explore)
PlanDetailScreen          | Skipped — couldn't navigate

Screenshots saved to maestro/assets/<branchname>/.

Show each screenshot to the user inline (the maestro skills will handle displaying them).

If any screens couldn't be reached, note them and suggest the user check manually.

Ensure maestro/assets/ is added to .gitignore so captured screenshots are not committed to the repository.

Step 5: Offer to Create Maestro Test File

After presenting results, ask the user whether to save the full validation flow as a reusable Maestro test file using AskQuestion:

• Title: "Save as Maestro Test?"
• Question: "Want me to create a Maestro test file that replays this entire validation flow (login, navigate to each screen, take screenshots)?"
• Options:
  • id: "yes", label: "Yes, create the test file"
  • id: "no", label: "No, I'm done"

If "yes":

1. Build a single .yml flow file that reproduces the full validation run:
   • Login with the test account and backend used during validation
   • Navigate to each captured screen in order
   • Take a screenshot at each screen (takeScreenshot: validate-<screen-name>)
2. Name the file based on the branch or ticket: maestro/flows/validate/<branch-or-ticket-name>.yml
   • Create the maestro/flows/validate/ directory if it doesn't exist
3. Add the ignore tag so it won't run in CI test suites
4. Use relative paths for utility flow references (e.g., ../../utils/login.yml)
5. Show the user the created file path

Example output:

appId: com.guideline.mobile
tags:
  - ignore
---
- runFlow:
    file: ../../utils/login.yml
    env:
      USERNAME: [e-mail]
      BUILD_ENV: staging
- takeScreenshot: validate-dashboard
- tapOn:
    id: portfolio-screen-tab
- waitForAnimationToEnd
- takeScreenshot: validate-portfolio

If "no": end the workflow.

Notes

• This skill is an orchestrator — all device interaction is handled by maestro-take-screenshots and maestro-explore.
• The build on the device must include the changes. If the user hasn't rebuilt, remind them to run npm run ios:release or npm run android:release first.
• For non-visual changes (refactors, test-only, CI config), suggest skipping validation entirely.