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:

• Job: build — correctly translated as task build
• Job: deploy — missing, no TODO comment
• 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.