Roundtrip Radar

Roundtrip Radar

This skill audits application workflows for bugs, data-safety issues, performance problems, and data round-trip completeness. It operates in three primary steps plus two targeted entry points:

• Step 0 — Discover all workflows (run once, or when workflows change)
• Step 1 — Deep audit one workflow at a time (one prompt per workflow)
• Step 2 — Roll-up cross-cutting patterns across all audited workflows
• Trace — Audit a specific user journey described in natural language (see § Trace Command)
• Diff — Compare findings against the previous audit's ledger entries (see § Diff Command)

Usage

| Command | Description | |---------|-------------| | /roundtrip-radar | Start with Step 0 (discover), then prompt for Step 1 | | /roundtrip-radar discover | Run Step 0 only — find all workflows | | /roundtrip-radar [WORKFLOW] | Run Step 1 for a specific workflow | | /roundtrip-radar rollup | Run Step 2 — cross-cutting analysis | | /roundtrip-radar trace "A → B → C" | Trace a specific user flow path (see below) | | /roundtrip-radar diff | Compare findings against previous audit | | --show-suppressed | Show findings suppressed by known-intentional entries | | --accept-intentional | Mark current finding as known-intentional (not a bug) |

---

Trace Command

Targeted flow tracing — trace a specific user journey described in natural language.

Usage

/roundtrip-radar trace "Dashboard → Add Item → Photo → Save"
/roundtrip-radar trace "Settings, Export, CSV, Email"

How It Works

1. Parse the path — Split on →, ->, or , into discrete steps
2. Identify code locations — For each step, search for:

• View names matching the step
• Sheet triggers, navigation actions
• Button labels, action handlers

1. Trace step by step — For each transition:

• File and line number
• State changes (sheet presentations, navigation, @State mutations)
• Data transformations (what model fields are read/written)

1. Check for issues at each step:

• Is data preserved between steps? (Round-trip completeness)
• Are collections preserved or silently narrowed? (Collection narrowing)
• Are there error paths that lose context? (Error handling)
• Is the user's intent preserved? (Data safety)
• Are there race conditions? (Concurrency)

1. Output — Issue Rating Table for findings + step-by-step trace with receipts

Output Format

Trace: Dashboard → Add Item → Photo → Save

| Step | Action | File | Lines | Data In | Data Out | Finding |
|------|--------|------|-------|---------|----------|---------|
| 1 | Dashboard tap "Add" | DashboardView.swift | 142-145 | — | activeSheet = .addItem | ok |
| 2 | Add Item sheet presents | AddItemView.swift | 1-50 | Item.draft | item.title, item.category | ok |
| 3 | Photo picker | PhotoPicker.swift | 23-89 | item.id | PhotoAttachment | ⚠️ orientation lost |
| 4 | Save item | ItemViewModel.swift | 112-134 | item + attachments | modelContext.save() | ok |

Issues Found:
| # | Finding | Urgency | Risk: Fix | Risk: No Fix | ROI | Blast Radius | Fix Effort | Status |

When to Use

• Debugging a specific user report — "When I add a photo and save, the orientation is wrong"
• Verifying a fix — Trace the exact path to confirm data flows correctly
• Pre-release spot check — Trace critical paths without a full audit

---

Diff Command

Compare findings against the previous roundtrip-radar audit — surface what regressed, what got fixed, and what's new since the last run.

Usage

/roundtrip-radar diff
/roundtrip-radar diff --since 2026-04-01
/roundtrip-radar diff --workflow Backup

Source of Truth

The diff reads from .radar-suite/ledger.yaml — the only authoritative cross-session store of roundtrip-radar findings. Per-workflow handoff YAMLs (.agents/ui-audit/roundtrip-radar-handoff.yaml) are overwritten each run, so they cannot serve as a diff baseline.

The "previous audit" is defined as the most recent ledger session entry with skill: roundtrip-radar that is strictly older than the current session. If no prior session exists, the diff command MUST refuse with:

> "No prior roundtrip-radar audit found in .radar-suite/ledger.yaml. Run a workflow audit first to establish a baseline."

Do not invent a baseline. Do not fall back to memory or .agents/research/ markdown reports.

How It Works

1. Identify the baseline session — read .radar-suite/ledger.yaml, find the most recent prior session entry with skill: roundtrip-radar. With --since YYYY-MM-DD, use the latest entry on or after that date instead.
2. Identify the current session — either the in-progress session (if the user just ran an audit and is asking for the diff) or the most recent completed session.
3. Bucket every finding from the union of baseline + current into one of four categories by RS-NNN ID:

• Fixed — present in baseline with status: open, present in current with status: fixed
• Regressed — present in baseline with status: fixed, present in current with status: open (also flag if file_hash changed since the fix, per the Regression Detection protocol in radar-suite-core.md)
• New — RS-NNN ID is in current but not baseline
• Persistent — present in both with the same status (open or deferred)

1. Apply optional filters: --workflow [NAME] restricts to findings whose workflow field matches.

Output Format

Diff: 2026-04-15 → 2026-05-12 (27 days, 4 sessions)

✅ Fixed (3)
| RS-NNN | short_title | Workflow | Fixed in |
|--------|-------------|----------|----------|
| RS-042 | Backup drops attachment storage | Backup | 2026-04-22 |
...

🔴 Regressed (1)
| RS-NNN | short_title | Workflow | Was fixed | file_hash changed? |
|--------|-------------|----------|-----------|--------------------|
| RS-019 | CSV import loses Room field | CSV Import | 2026-04-18 | yes (CSVImportManager.swift) |

🆕 New (5)
| RS-NNN | short_title | Workflow | Urgency |
|--------|-------------|----------|---------|

📌 Persistent (12)
[collapsed by default; pass --verbose to expand]

When to Use

• Pre-PR review — confirm the changes in this PR didn't reintroduce any previously-fixed bug
• Post-release retrospective — what got fixed this release cycle, what slipped
• Suspecting a regression — --workflow [NAME] narrows to one user journey

Refusal cases

• No prior ledger session: refuse with the message above
• --since date is in the future: refuse with "Date is in the future; no audits to compare"
• --workflow [NAME] matches no findings in either baseline or current: print "No findings in workflow [NAME] across either session" (not a refusal — a legitimate empty result)

---

Skill Introduction (MANDATORY — run before anything else)

This section replaces radar-suite-core.md § Session Setup for the roundtrip-radar entry point. Do NOT also run core's 4-question Session Setup — its questions are consolidated below. All four setup questions go in ONE AskUserQuestion call on first invocation. Step 1's per-workflow flow reuses these answers and never re-asks them.

Question 1: "What's your experience level with Swift/SwiftUI?"

• Beginner — New to Swift. Plain language, analogies, define terms on first use.
• Intermediate — Comfortable with SwiftUI basics. Standard terms, explain non-obvious patterns.
• Experienced (Recommended) — Fluent with SwiftUI. Concise findings, no definitions.
• Senior/Expert — Deep expertise. Terse, file:line only, skip explanations.

Question 2: "How should fixes be handled?"

• Auto-fix safe items (Recommended) — Apply isolated, low-blast-radius fixes automatically. Present cross-cutting fixes and design decisions for approval first.
• Review first — Present all findings with ratings, then ask before making any changes. Fixes still happen — you just approve each wave first.
• Batch mode — Approve all fixes in each wave at once.

IMPORTANT: All three modes lead to fixes. "Review first" means the user sees the plan before code changes — it does NOT mean "skip fixes and jump to handoff." After presenting findings, ALWAYS offer to fix them regardless of which mode was selected. (Exception: Hands-Free mode overrides this — see Question 4.)

Question 3: "How should results be delivered?"

• Display only (Recommended) — Show findings in the conversation. No file written.
• Report only — Write findings to .agents/research/[DATE]-[WORKFLOW]-audit.md. Minimal conversation output. Before writing, per Artifact Lifecycle (Class 3) in radar-suite-core.md, archive any existing .agents/research/*-[WORKFLOW]-audit.md matching the same workflow to .agents/research/archive/superseded/.
• Display and report — Show findings in the conversation AND write to file.

Question 4: "Will you be stepping away during the audit?"

• I'll be here (Recommended) — Normal mode. Permission prompts may appear for writes/edits.
• Run the full analysis without stopping to ask — no code changes — Hands-Free mode. Restricts to read-only tools (Read, Grep, Glob). No Bash, no Edit, no Write — nothing that triggers a permission prompt. Hands-Free overrides Question 2: all fixes are deferred regardless of FIX_MODE. The progress banner still prints, but the AskUserQuestion next-wave prompt is suppressed; the skill emits the "audit complete through Step N" completion message instead (see Hands-Free Mode below).
• Pre-approved — You have already configured Claude Code permissions for this session (see Permission Setup below). Run at full speed without restriction.

Store as: USER_EXPERIENCE, FIX_MODE, DELIVERY, PRESENCE_MODE. Apply to ALL output for session, per radar-suite-core.md § Experience-Level Output Rules. Also persist to .radar-suite/session-prefs.yaml per radar-suite-core.md § Session Persistence.

Question 5 (optional follow-up): "Would you like a brief explanation of what this skill does?"

• No, let's go (Recommended) — Skip explanation, proceed to audit.
• Yes, explain it — Show a 3-5 sentence explanation adapted to the user's experience level (see below), then proceed.

Experience-adapted explanations for Roundtrip Radar:

• Beginner: "Roundtrip Radar follows your data through complete user journeys — like tracking a package from warehouse to doorstep and back. For example, it checks: if you create an item, back it up, delete it, and restore — does everything come back exactly? It finds bugs where data gets lost, corrupted, or silently dropped along the way. It audits one workflow at a time (backup, add item, sync, etc.) so nothing gets missed."

• Intermediate: "Roundtrip Radar audits individual workflows end-to-end for data safety, error handling, concurrency, and round-trip completeness. It traces data through create → modify → export → import cycles, checks transaction boundaries, verifies error recovery paths, and identifies where data is silently lost. Works one workflow at a time to stay thorough."

• Experienced: "Per-workflow code audit: data safety, error handling, concurrency, performance, contract mismatches, and round-trip completeness. Discovers workflows, audits each with issue rating tables and fix plans, then rolls up cross-cutting patterns."

• Senior/Expert: "Workflow-scoped audit: data safety + error paths + concurrency + round-trip completeness. Rating tables + fix plans + cross-workflow rollup."

Store the experience level as USER_EXPERIENCE and apply to ALL output for the session.

User impact explanations: Can be toggled at any time with --explain / --no-explain. When enabled, each finding gets a 3-line companion explanation (what's wrong, fix, user experience before/after). See the shared rating system doc for format and rules. Store as EXPLAIN_FINDINGS (default: false).

Experience-level auto-apply: If USER_EXPERIENCE = Beginner, auto-set EXPLAIN_FINDINGS = true and default sort to impact. If Senior/Expert, default sort to effort. Apply all output rules from Experience-Level Output Rules table in radar-suite-core.md.

Subsequent workflows: Do NOT re-ask the full setup questions. Instead, show a one-line reminder before each workflow:

Using: [Experienced] mode, [Auto-fix safe items], [Display only], [I'll be here]. Type "adjust" to change, or press Enter to continue.

The four bracketed values map to USER_EXPERIENCE, FIX_MODE, DELIVERY, PRESENCE_MODE set during the Skill Introduction. If the user types "adjust", re-ask only the question(s) they want to change. Users may want to adjust experience level after a few workflows (beginner explanations may feel too simple, expert too terse).

---

Shared Patterns

See radar-suite-core.md for: Tier System, Pipeline UX Enhancements, Table Format, Plain Language Communication, Work Receipts, Contradiction Detection, Finding Classification, Audit Methodology, Context Exhaustion, Progress Banner, Issue Rating Tables, Handoff YAML schema, Known-Intentional Suppression, Pattern Reintroduction Detection, Experience-Level Output Rules, Implementation Sort Algorithm, short_title requirement.

Axis Classification Protocol (MANDATORY — before emitting any finding)

Every roundtrip-radar finding must be classified on the 3-axis framework and pass the schema gate in radar-suite-core.md before emission. The framework is defined in skills/radar-suite-axis-classification/SKILL.md.

Roundtrip-specific axis mapping

roundtrip-radar's findings are organized by what part of the round-trip path is broken. Each finding category maps to a default axis, with reclassification rules based on verification checks.

| Finding category | Default axis | Reclassification rule | |---|---|---| | Data loss on cancel | axis1bug | Stays axis1 (user-facing data loss) | | Data loss on error | axis1bug | Stays axis1 | | Missing feedback after save | axis1bug | Stays axis1 | | Field written but not read | axis3smelly | Reclassify to axis1bug ONLY if a user feature depends on the field (check feature flags and view usage) | | Field read but not written | axis3smelly | Reclassify to axis1bug if feature claims the field is set | | Field exists but unwired end-to-end | axis3smelly | Reclassify to axis1bug if a user action should write it | | Round-trip path opaque (cannot be traced from UI to persistence) | axis2scatter | Stays axis2 — data flow is correct but impossible to verify | | Inconsistent serialization across paths (CSV, backup, CloudKit) | axis1bug | Stays axis1 — ONE path loses user data | | Serialization paths duplicated across multiple managers | axis2scatter | Stays axis2 — correct but hard to maintain | | Serialization call reaches a dead branch (e.g., guard always true) | axis3deadcode | Stays axis3 |

Full-path verification rule (roundtrip-specific)

Every finding must cite the full roundtrip path in its verification_log. The path is the sequence of file:line hops from UI entry point to persistence and back to UI. If the path cannot be traced end-to-end, the finding is axis_2_scatter regardless of its category (the data flow is opaque even if correct).

Example verification_log for a roundtrip finding:

verification_log:
  - check: full_path_trace
    path:
      - ImportCSVView.swift:142 (user taps Import)
      - CSVImportManager.swift:420 (parse loop)
      - Item.swift:58 (Item init with room: nil  ← MISSING FIELD)
      - ModelContext (save)
      - ItemListView.swift:84 (Query fetches items)
      - ItemRowView.swift:29 (displays room, which is nil)
    result: "path traced end-to-end; room field is dropped at CSVImportManager.swift:420 and displayed as nil downstream"
  - check: pattern_citation_lookup
    result: "found existing round-trip pattern at Sources/Managers/BackupManager.swift:NNN which

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Terryc21](https://github.com/Terryc21)
- **Source:** [Terryc21/radar-suite](https://github.com/Terryc21/radar-suite)
- **License:** Apache-2.0
- **Homepage:** https://github.com/Terryc21/radar-suite

Install and usage instructions live in the source repository linked above.