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
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
. If no path is provided,
list the files in
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., likely came from
)
- 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 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 ( 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
- 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
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
rwx docs pull /docs/rwx/migrating/gha-reference
If you encounter a question not covered by these references, use
rwx docs search "<query>"
to find the relevant documentation page, then
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 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 references
- Run 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: (must fix before using) or (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.