review-gha-migration

Quick Reference

Fetch and read the cheat sheet before starting. Do NOT use WebFetch — it summarizes and drops critical details. Instead, use Bash to run rwx docs pull and read stdout directly:

rwx docs pull /docs/rwx/migrating/gha-cheat-sheet

Review Procedure

You are reviewing an RWX config that was generated from a GitHub Actions workflow migration. Your job is to catch problems the implementer missed. Approach this as a skeptical reviewer, not as someone defending prior work.

Step 1: Identify the files

The user provides the RWX config path as $ARGUMENTS. If no path is provided, list the files in .rwx/ and ask the user which config to review.

Then locate the corresponding source GitHub Actions workflow. Look for clues:

• •Comments in the RWX config referencing the source file
• •Filename correspondence (e.g., .rwx/ci.yml likely came from .github/workflows/ci.yml)
• •Ask the user if the source is ambiguous

Read both files in full.

Step 2: Inventory the source workflow

Build a checklist from the GitHub Actions workflow. For each item, you will verify it was correctly translated. Extract:

• •Every job and its needs: dependencies
• •Every step within each job (name + what it does)
• •All triggers and their configurations (branches, paths, event types)
• •Every secret referenced
• •Every environment variable (workflow, job, and step level)
• •Matrix strategies and their dimensions
• •Services (databases, caches, etc.)
• •Artifact upload/download pairs
• •Caching steps
• •Composite action references
• •Reusable workflow calls
• •Conditional logic (if: expressions)
• •Timeout and concurrency settings

Step 3: Verify behavioral equivalence

Go through your checklist item by item and verify each one is accounted for in the RWX config. For each item, classify it as:

• •Correct — properly translated to the RWX equivalent
• •Missing — not present in the RWX config and no TODO comment explaining why
• •Wrong — translated but with a semantic difference that changes behavior
• •Degraded — works but lost important properties (e.g., a parallel job became sequential)

Pay special attention to:

• •Steps that were silently dropped during migration
• •if: conditionals that were lost or simplified incorrectly
• •Environment variables that were not carried over
• •Secrets that are referenced but not mapped
• •Matrix dimensions that were flattened or lost
• •Service containers that have no equivalent
• •Artifact passing between jobs that was not preserved

Step 4: Verify RWX optimizations

If you don't already have the reference documentation in context, fetch it now. Do NOT use WebFetch — it summarizes and drops critical details. Instead, use Bash to run rwx docs pull for each doc and read stdout directly. Run both in a single turn as parallel Bash calls:

• •rwx docs pull /docs/rwx/migrating/rwx-reference — full RWX config syntax
• •rwx docs pull /docs/rwx/migrating/gha-reference — GHA-to-RWX concept mapping

If you encounter a question not covered by these references, use rwx docs search "<query>" to find the relevant documentation page, then rwx docs pull the result.

Using the reference documentation, check whether the config takes full advantage of RWX capabilities:

• •DAG structure: Are tasks that can run in parallel actually parallel, or are there unnecessary sequential dependencies?
• •Content-based caching: Are cache keys content-based (not hash-based) where possible?
• •Package substitution: Are there run: steps installing tools that have RWX package equivalents?
• •Task granularity: Could large monolithic tasks be split into parallel subtasks?
• •Trigger optimization: Are triggers using path filters and branch filters effectively?

Step 5: Validate structure

Check the RWX config for structural issues:

• •Required fields are present
• •YAML is well-formed
• •Task ordering reflects the DAG (independent tasks first)
• •No orphaned use references
• •Run rwx lint .rwx/<name>.yml and review the diagnostics

Step 6: Produce the review

Output a structured review with these sections:

Summary: One-line verdict — is this migration correct and ready, or does it need changes?

Issues (if any): A numbered list of problems found, each with:

• •Severity: blocking (must fix before using) or suggestion (improvement opportunity)
• •What's wrong
• •Where in the RWX config it occurs
• •What the fix should be

Checklist: A markdown checklist showing each source workflow item and whether it was correctly translated:

- [x] Job: build — correctly translated as task `build`
- [ ] Job: deploy — missing, no TODO comment
- [x] Trigger: push to main — correctly mapped
- [ ] Secret: DEPLOY_KEY — referenced but not in secrets mapping

Optimization opportunities: Any RWX-specific improvements not yet applied.

If you find blocking issues, offer to fix them directly.