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
3. 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)
4. 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)
5. 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)
4. 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	axis_1_bug	Stays axis_1 (user-facing data loss)
Data loss on error	axis_1_bug	Stays axis_1
Missing feedback after save	axis_1_bug	Stays axis_1
Field written but not read	axis_3_smelly	Reclassify to axis_1_bug ONLY if a user feature depends on the field (check feature flags and view usage)
Field read but not written	axis_3_smelly	Reclassify to axis_1_bug if feature claims the field is set
Field exists but unwired end-to-end	axis_3_smelly	Reclassify to axis_1_bug if a user action should write it
Round-trip path opaque (cannot be traced from UI to persistence)	axis_2_scatter	Stays axis_2 — data flow is correct but impossible to verify
Inconsistent serialization across paths (CSV, backup, CloudKit)	axis_1_bug	Stays axis_1 — ONE path loses user data
Serialization paths duplicated across multiple managers	axis_2_scatter	Stays axis_2 — correct but hard to maintain
Serialization call reaches a dead branch (e.g., guard always true)	axis_3_dead_code	Stays axis_3

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 correctly serializes room"

If any hop cannot be found (e.g., "no persistence call in this workflow"), the path entry documents the gap:

path:
  - AddItemView.swift:120 (user taps Save)
  - AddItemViewModel.swift:85 (validate inputs)
  - [GAP: no modelContext.insert found for this workflow in scope]
result: "round-trip path INCOMPLETE; finding classified as axis_2_scatter (opaque flow)"

Required checks before emission

1. Full-path trace (MANDATORY for every finding) — walk UI → manager → model → persistence → UI. Log every hop.
2. Pattern citation lookup (MANDATORY) — find an existing correct round-trip pattern in the same codebase and cite it by file:line in better_approach.
3. Whole-file scan (MANDATORY when claiming a field is "not serialized") — scan the ENTIRE serializer file (CSV import/export, backup encode/decode, CloudKit mapper) for the field name. If found, it IS serialized — the finding is probably about a different code path (reclassify as axis_2_scatter if the serialization is scattered).
4. Multi-path comparison (MANDATORY for serialization findings) — a field may be serialized in one path (backup) but not another (CSV). Check ALL known serialization paths before claiming "missing." Stuffolio has at least 4: CSV export, CSV import, backup (JSON), CloudKit (CKRecordMapper).

Schema gate

Per radar-suite-core.md, a finding is REJECTED if:

• axis field is missing
• before_after_experience is missing or incomplete
• better_approach lacks a file:line citation matching the pattern shape
• verification_log lacks a pattern_citation_lookup entry

Rejected findings are NOT silently dropped: downgrade confidence to possible, mark as coaching incomplete, and increment rejected_no_citation in the handoff's axis_summary.

Axis summary block

At the end of every roundtrip-radar handoff:

axis_summary:
  axis_1_bug: [count]              # data loss, missing feedback, broken serialization paths
  axis_2_scatter: [count]          # opaque flows, duplicated serialization
  axis_3_dead_code: [count]        # unreachable serialization branches
  axis_3_smelly: [count]           # unwired fields with no user feature dependency
  rejected_no_citation: [count]

---

Pre-Scan Startup (MANDATORY — before any workflow scan)

1. Known-intentional suppression: Run the protocol in radar-suite-core.md § Known-Intentional Suppression. Core owns this — do not restate the steps here.

2. Pattern reintroduction detection: Run the protocol in radar-suite-core.md § Pattern Reintroduction Detection. Core owns this.

---

Step 0: Workflow Discovery

Run first if workflows are unknown or have changed.

Scan the codebase and identify all user-facing workflows.

What Counts as a Workflow

A workflow is a multi-step user action that:

• Spans 2+ screens or states (not a single tap)
• Involves data creation, modification, deletion, or transfer
• Has a distinct entry point and completion state

How to Find Them

1. Search for navigation entry points:
   • .sheet, .fullScreenCover, .navigationDestination
   • NavigationLink, TabView tabs
   • Button actions that trigger multi-step flows
2. Search for data operations:
   • modelContext.insert, modelContext.delete, context.save
   • Import/export, backup/restore, sync operations
   • API calls, file I/O
3. Search for state machines:
   • Enums with cases like .idle, .processing, .complete
   • Multi-step @State progressions
   • isProcessing, isImporting, isSaving patterns

Output

List each workflow with:

#	Workflow	Entry Point	Key Files	Complexity	Data Risk
1	[Name]	[Where user starts it]	[2-4 main files]	Low/Med/High	None/Read/Write/Delete

Complexity Criteria

• Low — 1-2 files, linear flow, no branching
• Medium — 3-4 files, some branching, error handling
• High — 5+ files, async operations, multiple outcomes, data transformation

Data Risk Criteria

• None — Display only
• Read — Fetches but doesn't modify
• Write — Creates or updates data
• Delete — Removes data or replaces state

Priority Recommendation

After listing all workflows, recommend which to audit first based on:

• High complexity + Write/Delete data risk = audit first
• Medium complexity + Write risk = audit second
• Everything else = audit if time permits

Do NOT write a report file. Output the table directly.

---

Step 1: Per-Workflow Audit

One workflow per prompt. Run as a separate agent or conversation per workflow to prevent context exhaustion.

Audit the [WORKFLOW NAME] workflow for bugs, data-safety issues, performance problems, and data round-trip completeness.

Before Starting (First Workflow Only)

All setup questions were captured during the Skill Introduction call (USER_EXPERIENCE, FIX_MODE, DELIVERY, PRESENCE_MODE). Do NOT re-ask any of them. Show the one-line settings reminder from § Skill Introduction and proceed to the audit.

If any of the four variables is missing for some reason (e.g., session-prefs file deleted mid-session), re-run the full Skill Introduction call before continuing — never partially re-ask, since the questions are interdependent (Question 4 overrides Question 2).

Permission Modes

Normal Mode

• Read any file without asking.
• Edit files listed in "Files to Read" and their corresponding test files freely.
• For files outside that list, edit only if directly required by a P0-P1 fix. Note which external files were changed in your output.
• Build and run tests without asking.
• If a fix breaks the build, restore the original code and document the finding as "Documented" instead of "Fixed".

Hands-Free Mode

Guarantees no blocking prompts. The skill will ONLY use these tools:

• Read — read file contents
• Grep — search file contents
• Glob — find files by pattern

It will NOT use:

• Bash — no shell commands (grep via Grep tool instead)
• Edit / Write — no file modifications
• AskUserQuestion — no interactive prompts

Precedence rules (load-bearing — Hands-Free wins all ties):

1. Hands-Free overrides FIX_MODE. Even if Question 2 was answered Auto-fix safe items or Batch mode, no fixes are applied in Hands-Free mode. All findings are emitted with Status: Deferred (hands-free) in the Issue Rating table. The Fix Plan is still produced (so the user can act on it on return), but no Wave 1-5 fix application runs.
2. Hands-Free suppresses the next-wave AskUserQuestion. The "BLOCKING — progress banner + next-wave prompt" rule under § Progress Banner applies in Normal and Pre-Approved modes only. In Hands-Free mode, the progress banner still prints (so the user can see what was audited), but the AskUserQuestion call is omitted and replaced by the completion message below.
3. Hands-Free does not suppress handoff writes. Writing .agents/ui-audit/roundtrip-radar-handoff.yaml and .radar-suite/ledger.yaml uses Edit/Write — which Hands-Free forbids. To resolve: in Hands-Free mode, the skill emits the handoff and ledger content inline in the conversation as fenced YAML blocks so the user can persist them on return. Inline emission does not count as a write.

When the audit completes (or hits a step that needs restricted tools), it prints:

⏱ Hands-free audit complete through Step [N].
  Steps requiring action: [list]
  Findings deferred: [count] (no fixes applied — Hands-Free mode)
  Handoff YAML + ledger entries: emitted inline above; copy to .agents/ui-audit/ and .radar-suite/ when you return
  Reply to continue with supervised steps.

Pre-Approved Mode

Full speed, no restrictions. Assumes you've set up permissions. See below.

Permission Setup (for unattended runs)

To avoid permission prompts during audits, pre-allow these read-only patterns in your Claude Code settings. These are safe to auto-approve — they cannot modify your codebase:

# Already safe by default (no setup needed):
Read, Grep, Glob — always auto-approved

# Add these for unattended Bash scans:
Bash(find:*)
Bash(wc:*)
Bash(stat:*)

Do NOT auto-approve (keep these prompted — they modify state):

Edit, Write — file modifications
Bash(rm:*), Bash(git:*) — destructive operations

Tip: Hands-free mode can complete workflow discovery (Step 0) and the full per-workflow audit (Step 1) read-only. Only fix application needs write access.

Freshness

Base all findings on current source code only. Do not read or reference files in .agents/, scratch/, or prior audit reports. Ignore cached findings from auto-memory or previous sessions. Every finding must come from scanning the actual codebase as it exists now.

Context Budget

If context is running low, prioritize in this order:

1. Finish verifying Suspects
2. Complete any in-progress fixes
3. Emit the Fix Plan for what you've found so far
4. Skip remaining exploratory checks

Never start a new check you can't finish.

Experience-Level Adaptation

Adjust ALL output based on the user's experience level:

• Beginner: Plain language, real-world analogies, define terms on first use ("a model context — the database connection SwiftUI uses to save data"). Explain why each finding matters. Use compact 4-column tables with prose explanations below.
• Intermediate: Standard SwiftUI terminology without defining basics, but explain non-obvious patterns (e.g., why a Task.sleep workaround indicates a broken refresh path). Full 9-column tables with brief descriptions.
• Experienced (default): Concise findings, no definitions. "Missing modelContext.save() after batch delete in BulkEditViewModel.swift:142". Full tables, terse text.
• Senior/Expert: Minimal prose. File:line + one-line description only. Findings table IS the output. Skip design principle citations and category explanations.

Fix Threshold

• Fix: Data loss, data corruption, crashes, infinite loops, broken user flows (P0-P1)
• Document only: Performance, UI polish, code style, missing features (P2+)
• Defer with explanation: P0-P1 issues that require multi-file migration, schema changes, or affect core models used outside this workflow. Mark as "P1 - Deferred (reason)" in the table.

Suspects (verify these first, then explore beyond)

[One per line. Include file name, approximate line, and the specific question to answer.]

Example:

• BackupDataSheet.swift ~line 351: decryptAndRestore(replaceExisting: false) — is the user's replace choice preserved through the password prompt?

[If no suspects: "No prior suspects — full exploratory audit."]

Recent Changes (verify these are correct)

[One per line. Include file, what changed, and what to verify.]

Example:

• CloudSyncManager.swift: Added maxRetries=3 retry limit — verify counter resets on all terminal paths (success, non-retryable errors)

[If none: "None"]

Files to Read

• Must read: [2-4 files central to this workflow]
• Read if relevant: [1-2 supporting files, with the condition that makes them relevant]
• Skip: [files that look related but are low-value]
• Tests: Find by searching Tests/ for [WORKFLOW_KEYWORD]

What to Check

1. Data safety enumerate-required — destructive operations, transaction boundaries, edge cases
2. Error handling mixed — missing catches, silent failures, user-facing error messages
3. Concurrency mixed — @MainActor compliance, Task isolation, ModelContext thread safety
4. Performance grep-sufficient — @Query without predicates, O(n²) loops, main-thread blocking
5. Contract mismatches grep-sufficient — constants vs hardcoded strings, keys defined in one file but consumed in another
6. Round-trip completeness enumerate-required — does data survive a full create → export → import/restore cycle?
7. Interruption paths enumerate-required — dismiss mid-operation, app backgrounding, rotation, cancel
8. Collection narrowing enumerate-required — collections silently reduced to single elements at handoff points (see detection guide below)
9. Tests enumerate-required — update broken tests, add tests for P0-P1 fixes where logic is testable
10. Bridge parity enumerate-required — multiple consumers of the same model type must read the same fields (see detection guide below)

Verification Template (MANDATORY per workflow)

Before grading a workflow, produce this table showing what was actually traced:

| Step | Action | File Read | Lines | Receipt | Finding |
|------|--------|-----------|-------|---------|---------|
| 1. Create | [what happens] | [file:line] | [range] | [evidence] | [ok / issue] |
| 2. Save | [what happens] | [file:line] | [range] | [evidence] | [ok / issue] |
| 3. Export | [what happens] | [file:line] | [range] | [evidence] | [ok / issue] |
| 4. Import | [what happens] | [file:line] | [range] | [evidence] | [ok / issue] |

Rules:

• Every step in the workflow must have a File Read entry
• Steps without a file read cannot produce findings tagged "verified"
• The table IS the audit — the findings are just a summary of what the table reveals

Collection Narrowing Detection Guide

What it is: A [T] (array) enters a handoff point but only a T (single element) exits -- silently discarding the rest. The flow works, types are correct, and the user gets a result -- but with degraded quality because most of the input data was dropped.

Why it matters: This bug class is invisible to type checking, navigation audits, and UX flow audits. The flow completes successfully with no errors. Only the quantity of data is wrong, which degrades results without any signal to the user.

Detection patterns:

Pattern	Code Signature	Likely Bug?
Array-to-first	array.first or array[0] passed where [T] is accepted	Yes -- receiver can handle the full array
Init narrowing	init(item: T) called by a site holding [T] when init(items: [T]) exists	Yes -- wrong init chosen
Wrapper narrowing	Class/struct stores T but is created from [T] context	Yes -- wrapper designed for single item, not updated for multi
Loop-break narrowing	for item in items { ...; break } or if let first = items.first without processing rest	Maybe -- check if intentional (preview thumbnail)

Distinguish intentional from accidental:

• Accidental (flag it): The receiving function/init accepts [T] but the caller passes .first. The API was designed for multiple items.
• Accidental (flag it): A wrapper class stores single T but is created in a context where [T] is available and the downstream service accepts [T].
• Intentional (skip it): The receiver only accepts T and there's no [T] alternative. Example: displaying a single thumbnail preview from an array.
• Intentional (skip it): The narrowing is guarded by UI that shows the user only one item is being used (e.g., "Using first photo as cover image").

How to check during a workflow audit:

1. At each handoff point in the Verification Template, note the cardinality of data passed:
   • [4 images] → [4 images] = ok
   • [4 images] → [1 image] = flag as collection narrowing
2. When a function receives an array, trace what it passes downstream -- does the full array reach the endpoint?
3. When an init accepts single T, check if a multi-item init exists on the same type
4. In the Verification Template, add a "Cardinality" note to the Receipt column when collections are involved

Origin: Found in Stuffolio Apr 2026 -- user selected 4 photos for AI analysis, but AIAnalysisTask only accepted first image, and Stuff Scout sheet passed productImages?.first to a view that had a multi-image init. Flow worked, types were correct, results were degraded.

Bridge Parity Detection Guide

What it is: Multiple functions consume the same model type but read different subsets of its fields -- one was updated when new fields were added, the others were not. The outdated consumer silently drops data.

Why it matters: This bug class is invisible to single-path tracing. Each consumer works correctly in isolation -- types match, no crashes, no errors. The bug only appears when you compare consumers against each other and notice one reads fewer fields. It survives code review because reviewers follow one path at a time.

Detection method -- relative comparison, not absolute counting:

1. Enumerate all consumers of a given model type. A "consumer" is any function that reads fields from the type to build output (notes, prefill data, export, display). Search for:

   • Functions with parameters of the type (func build(_ session: ScoutSession))
   • Functions that access properties of the type (session.aboutItem, session.historicalContext)
   • Bridge structs with init(from:) or conversion methods (toItem(), toPrefillData())

2. For each consumer, record which fields it reads. Build a field-access matrix:

   | Field            | ConsumerA | ConsumerB | ConsumerC |
   |------------------|-----------|-----------|-----------|
   | era              | ✓         | ✓         | ✓         |
   | aboutItem        | ✓         | ✓         | ✓         |
   | historicalContext | ✓         |           | ✓         |
   | collectorNotes   | ✓         |           | ✓         |
   | researchTips     | ✓         |           | ✓         |
   

3. Flag asymmetries. If N consumers exist and one reads strictly fewer fields than the others, it is the outlier. The comparison is relative -- you do not need to know the "correct" field count. The mismatch itself is the finding.

Ranking the finding:

Signal	Confidence
One consumer reads < 50% of fields that others read	Almost certain bug -- flag immediately
One consumer misses 1-2 fields that all others include	Probable bug -- verify with git blame (was the field added after this consumer was written?)
Consumers read different but overlapping sets (no strict subset)	Possible intentional -- different consumers may legitimately need different fields (e.g., summary view vs. detail export). Check if the omitted fields are relevant to the consumer's purpose.

Distinguish intentional from accidental:

• Accidental (flag it): Two consumers serve the same purpose (e.g., both build "notes" text from scout data) but one includes 3 more sections. The simpler one was written first and never updated.
• Accidental (flag it): A consumer was copied from another and trimmed, but the trimming removed fields that matter for its context.
• Intentional (skip it): A summary consumer intentionally shows only key fields (e.g., a list row shows title + era but not full historical context). The consumer's purpose justifies the subset.
• Intentional (skip it): A consumer explicitly documents why fields are excluded (comment or design doc).

How to check during a workflow audit:

1. When you encounter a bridge or conversion function, search for OTHER functions that consume the same source type
2. Build the field-access matrix for all consumers found
3. If an asymmetry exists, add a "Bridge Parity" note to the Verification Template Receipt column
4. In the Issue Rating table, tag bridge parity findings as verified (you read the code of all consumers) with blast radius = number of consumers that need updating

Cross-cutting accumulator integration: After finding a bridge parity issue, add the model type to the cross-cutting pattern accumulator. In subsequent workflows, automatically check any new consumer of that type against the established field matrix.

Origin: Found in Stuffolio Apr 2026 -- ScoutSession had 3 consumers building notes. ScoutMergeView and StuffScoutBridge included all 6 narrative fields. ExistingItemScoutFlow.buildNotesFromScout() included only 3. The outlier was written before the other fields were added and never updated. No type error, no crash, no test failure -- users simply lost Historical Context, Collector Notes, and Research Tips when saving via that code path.

Issue Rating Criteria

For every finding, use this table format sorted by Urgency (descending), then ROI:

#	Finding	Confidence	Urgency	Risk: Fix	Risk: No Fix	ROI	Blast Radius	Fix Effort	Status

Column Definitions

Column	Meaning
Confidence	verified (code read + confirmed), probable (agent reported, not independently verified), needs-runtime (requires running the app to confirm)
Urgency	How time-sensitive — must it be fixed before release?
Risk: Fix	What could break when making the change
Risk: No Fix	Cost of leaving it — crash, data loss, user-visible bug
ROI	Return on effort (inverted — 🟠 = excellent, 🔴 = poor)
Blast Radius	Number of files the fix touches (e.g., 🟢 3 files, ⚪ 1 file). Do not use <br> tags. Count by grepping for callers/references before rating.
Fix Effort	Trivial / Small / Medium / Large
Status	Fixed / Documented / Deferred (reason)

Finding Dependencies and Fingerprints

When creating findings, populate these optional fields where relationships are obvious:

• depends_on/enables: Workflow findings often chain -- a data loss at step 2 enables a corrupt display at step 5. If one fix must come before another, populate with finding IDs.
• pattern_fingerprint/grep_pattern/exclusion_pattern: Assign fingerprints for generalizable anti-patterns (e.g., silent_data_narrowing, missing_error_recovery, unguarded_concurrent_write).

Indicator Scale

Indicator	General meaning	ROI meaning
🔴	Critical / high concern	Poor return — reconsider
🟡	High / notable	Marginal return
🟢	Medium / moderate	Good return
⚪	Low / negligible	—
🟠	Pass / positive	Excellent return

Urgency Scale

• 🔴 CRITICAL — pre-launch blocker OR data loss / crash risk
• 🟡 HIGH — user-visible or stability risk; fix before release
• 🟢 MEDIUM — real issue; acceptable to schedule
• ⚪ LOW — nice-to-have; minimal impact

Do not use prose for ratings. Every finding gets a row in this table.

Output

Fix Plan

After all findings, generate a Fix Plan grouped into these sections:

1. Safe fixes (contained, only touching one or two files) Changes contained within the audited files. No behavioral changes outside the workflow.

#	Finding	Files Changed	Urgency	ROI	Fix Effort

2. Cross-cutting fixes (touch shared code) Changes that affect models, protocols, or utilities used by other features. Review for unintended side effects before approving.

#	Finding	Files Changed	Urgency	ROI	Fix Effort	Side Effects

3. Requires design decision Multiple valid approaches. Needs user input before proceeding.

#	Finding	Options	Urgency

4. Deferred (no action needed now) Documented for future reference. No plan step generated.

#	Finding	Urgency	Why Deferred

5. Shared utility extraction When multiple code paths duplicate the same logic, extract to a shared utility.

#	Finding	Proposed Utility	Files Affected

6. Out of scope Issues discovered here that belong to a different workflow. List them with the affected workflow name so they can be fed into that workflow's audit.

#	Finding	Affected Workflow	Urgency

Verification (auto-fix mode only)

After applying Safe fixes:

1. Build the project — if it fails, revert and move the fix to Cross-Cutting
2. Run tests touching modified files — if any fail, fix the test or revert the code fix
3. Report pass/fail counts in the Fix Plan output

Then

• If user chose Auto-fix safe items: apply Section 1 fixes, run Verification, then present Sections 2-3 for approval.
• If user chose Review first: present all sections for approval, then ask if the user wants to proceed with fixes.

Delivery

• If user chose Display only: output all tables in the conversation.
• If user chose Report only: write all tables to .agents/research/[DATE]-[WORKFLOW]-audit.md. Show only a one-line summary in the conversation (e.g., "Audit complete: 3 critical, 5 high, 2 medium. Report written to .agents/research/2026-03-06-backup-audit.md").
• If user chose Display and report: output all tables in the conversation AND write to file.

Deferred Items Registry

After each workflow audit, append deferred findings to .agents/research/roundtrip-radar-deferred.md. This accumulates across workflows so Step 2 rollup can consume them without re-reading all audit output.

Format:

## [Workflow Name] — [Date]
| # | Finding | Urgency | Why Deferred |
|---|---------|---------|--------------|
| 1 | ... | 🟡 HIGH | Needs design decision |

---

Fix Application Workflow

After presenting the Fix Plan, apply fixes in waves. Each wave is a phase from the Fix Plan. After each wave (including commits), always print the progress banner and auto-prompt for the next wave.

Waves

Wave	Fix Plan Section	Est. Time	Description
1 — Quick fixes	Safe fixes + tests	~10-15 min	Small, contained fixes (one or two files each). Applied automatically. Tests written for each fix.
2 — Shared code fixes	Cross-cutting fixes + tests	~15-25 min	Fixes that touch code used by other features. Presented for your review first. Tests written for each fix.
3 — Your call	Design decisions	~5-15 min	Multiple valid approaches. You pick the direction for each item.
4 — Same bug elsewhere	Pattern Sweep	~5 min	Search the whole codebase for the same bugs found in this workflow.
5 — Wrap up	Build + Test + Commit	~5 min	Build both platforms, run tests, stage, commit.

Every fix must have a test. Do not move to the next wave until tests for the current wave's fixes are written and compiling. The test verifies the fix works; without it, the fix is unverified code.

Skip empty waves (e.g., if no design decisions, go straight from Wave 2 to Wave 4).

If a "cross-cutting fix" turns out to need a design decision during implementation, reclassify it — ask the user via AskUserQuestion with the options, don't proceed without input.

Wave 4: Pattern Sweep (after fixes, before commit)

After fixing findings in a workflow, scan the entire codebase for the same anti-pattern. This catches all instances at once instead of rediscovering them workflow-by-workflow.

For each pattern found and fixed in this workflow:

1. Build a grep query (e.g., Double( for raw price parsing, hashValue for unstable IDs)
2. Search all Sources/ files
3. Report: "Pattern X found in N additional files: [list]"
4. If fixes are trivial and isolated, apply them now. Otherwise, note for the next workflow.

Progress Banner (CRITICAL — BLOCKING requirement)

This is a BLOCKING requirement in Normal and Pre-Approved modes. After EVERY wave and EVERY commit, your NEXT output MUST be the progress banner followed by the next-wave AskUserQuestion. Do not output anything else first. Do not wait for user input. Do not leave a blank prompt.

Hands-Free mode exception: In Hands-Free mode, the progress banner still prints, but the next-wave AskUserQuestion call is suppressed (per the Hands-Free Mode precedence rules above). Replace the AskUserQuestion with the Hands-Free completion message instead.

After completing each wave, always print:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Fix batch [N] of [total] complete: [plain description]
   [X] findings fixed, [Y] remaining, [Z] deferred

⏱  Next: Batch [N+1] — [plain description] (~[time estimate])
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then immediately ask: "Ready for the next batch?" with options:

• Proceed (Recommended) — Start the next batch of fixes
• Commit first — Commit current changes before continuing
• Stop here — End for now, resume later
• Explain more — Describe what the next batch will do before starting

Between Workflows (MANDATORY transition)

After committing all fixes for a workflow, follow this exact sequence:

1. Print the Workflow-Level Scorecard:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Roundtrip Radar Progress
   Workflows: [N]/[total] | Fixed: [X] | Deferred: [Y] | Patterns: [Z]
   Last: [workflow name] ([N] fixed)
   Next: [workflow name] (~[time estimate])
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. Immediately ask: "Ready for the next workflow?" with options:

   • Proceed (Recommended) — Audit the next highest-priority workflow
   • Stop here — End session, save progress to memory
   • Final rollup (Step 2) — Cross-cutting analysis across all audited workflows

3. If user proceeds, show the one-line settings reminder (see Skill Introduction) then start the audit. Do NOT re-ask the 4 setup questions.

Never leave the user with a blank prompt between workflows.

Pipeline Mode Behavior (Tier 2/3)

When running inside a Tier 2 or Tier 3 pipeline (detected via tier field in .radar-suite/session-prefs.yaml):

1. On skill start: Emit the pipeline-level progress banner (see radar-suite-core.md Pipeline UX Enhancements #1). If this is the first skill in the pipeline OR experience_level is Beginner/Intermediate, also emit the audit-only statement.
2. On skill completion: Emit a per-skill mini rating table marked "PRELIMINARY" (see Pipeline UX Enhancements #2). Then emit the pipeline-level progress banner showing this skill as complete.
3. Within-skill workflow banners (above) are still emitted normally in addition to the pipeline-level banners.

short_title Requirement (v2.1)

Every finding MUST include a short_title field (max 8 words). This is the human-scannable label used in pipeline banners, pre-capstone summaries, and ledger output.

Example: short_title: "Backup drops attachment external storage"

All finding ID references in output (tables, banners, summaries) use the format: RS-NNN (short_title).

---

Step 2: Roll-Up

Run after all per-workflow audits are complete.

Data Sources (read these — do NOT ask the user to paste)

1. .agents/research/roundtrip-radar-deferred.md — the accumulator written by every per-workflow audit (see § Deferred Items Registry). Contains every deferred finding across the session.
2. .radar-suite/ledger.yaml — filter to entries where skill: roundtrip-radar AND the session timestamp is in this rollup's scope (default: all sessions since the last Step 2 rollup ledger entry, or all sessions if none).
3. Each per-workflow handoff's axis_summary block — load from the in-memory session state for the current run.

Identify cross-cutting patterns across the loaded entries.

Output

1. List any pattern that appears in 2+ workflows (e.g., @Query without predicates, hash-based IDs)
2. For each pattern, state which workflows are affected and whether a shared fix exists
3. Rank the top 5 remaining deferred items by impact using the Issue Rating table format

Deliver results according to the user's output preference from Step 1.

---

Cross-Skill Handoff

Roundtrip Radar complements data-model-radar (model layer), ui-path-radar (navigation paths), ui-enhancer-radar (visual quality), and capstone-radar (ship readiness). Findings from one skill inform the others.

On Completion — Write Handoff

After completing a workflow audit (or Step 2 rollup), write/update .agents/ui-audit/roundtrip-radar-handoff.yaml:

source: roundtrip-radar
date: <ISO 8601>
project: <project name>
workflows_audited: <count>

# File timestamps — enables staleness detection by consuming skills
# If a file changed after the audit, affected issues may need re-verification
file_timestamps:
  <file path>: "<ISO 8601 mod date>"
  # one entry per unique file referenced in issues

for_ui_path_radar:
  # Data issues that may have navigation/entry-point implications
  suspects:
    - entry_point: "<button/link that triggers this workflow>"
      finding: "<data safety issue found>"
      file: "<file:line>"
      question: "<does the UI reflect this data issue?>"
      group_hint: "<optional, e.g. 'data_loss', 'silent_failure'>"

for_ui_enhancer_radar:
  # Dead code, orphaned UI, or views with broken data backing
  suspects:
    - view: "<view file>"
      finding: "<data issue that affects this view>"
      action: "verify data binding or remove dead UI"
      group_hint: "<optional batching suggestion>"

for_capstone_radar:
  # Critical/high findings that affect ship readiness
  blockers:
    - finding: "<description>"
      urgency: "<CRITICAL|HIGH>"
      workflow: "<workflow name>"
      group_hint: "<optional batching suggestion>"

cross_cutting_patterns:
  # Patterns found across multiple workflows — useful for all skills
  - pattern: "<e.g., Double() price parsing>"
    workflows_affected: ["Backup", "Edit Item", "CSV Import"]
    status: "fixed" | "deferred"
    group_hint: "<optional, e.g. 'price_parsing', 'id_handling'>"
  # Example: collection narrowing pattern
  # - pattern: "array.first passed to multi-item API"
  #   workflows_affected: ["Add Item (Photo)", "Stuff Scout"]
  #   status: "fixed"
  #   group_hint: "collection_narrowing"
  # Example: bridge parity pattern
  # - pattern: "ScoutSession consumed by 3 functions, 1 reads 3/6 fields"
  #   workflows_affected: ["Stuff Scout", "Add Item (Photo)"]
  #   status: "fixed"
  #   group_hint: "bridge_parity"

File Timestamps

For each unique file path referenced across all issues, record its modification date at audit time:

# Get file mod date (macOS)
stat -f "%Sm" -t "%Y-%m-%dT%H:%M:%SZ" "<file path>"

This enables consuming skills to detect staleness — if a file changed after the audit, affected issues may need re-verification before acting on them.

Group Hints

Optional field suggesting how consuming skills might batch related issues:

• Issues with the same group_hint are candidates for a single fix task
• Consuming skills are free to ignore hints and group differently
• Common hints: data_loss, silent_failure, round_trip_gap, error_handling, concurrency, collection_narrowing, bridge_parity

Automatic: This file is always written so other audit skills can pick up where this one left off. No user action needed.

End-of-Run Directory Cleanup (MANDATORY)

Per the Artifact Lifecycle rules in radar-suite-core.md, before returning from this skill:

1. List files in .radar-suite/ (and .agents/research/ if used).
2. Move any stale single-use handoffs (RESUME_PHASE_*.md, RESUME_*.md except NEXT_STEPS.md, *-v[0-9]*.md) to .radar-suite/archive/superseded/.
3. Confirm Class 1 persistent-state files (ledger.yaml, session-prefs.yaml) are in-place rewrites — not dated or versioned.
4. Confirm Class 2 handoff files are overwrites, not appends.

This prevents .radar-suite/ from accumulating stale prose artifacts across runs.

Write to Unified Ledger (MANDATORY)

After writing the handoff YAML, also write findings to .radar-suite/ledger.yaml following the Ledger Write Rules in radar-suite-core.md:

1. Read existing ledger (or initialize if missing)
2. Record this session (timestamp, skill name, build)
3. For each finding: check for duplicates, assign RS-NNN ID if new, set impact_category, compute file_hash
4. Write updated ledger

Impact category mapping for roundtrip-radar findings:

• Data loss on round-trip (fields dropped, values corrupted) → data-loss
• Silent failure (error swallowed, operation appears to succeed but doesn't) → data-loss
• Crash on workflow completion → crash
• Workflow dead end or broken promise → ux-broken
• Degraded workflow (works but lossy or confusing) → ux-degraded
• Cross-cutting patterns (e.g., price parsing) → classify per finding

On Startup — Read Ledger & Handoffs (MANDATORY)

Before Step 0 (or Step 1 if skipping discovery), read the unified ledger and ALL companion handoff YAMLs:

Read .radar-suite/ledger.yaml (if exists) — check for existing findings to avoid duplicates
Read .agents/ui-audit/data-model-radar-handoff.yaml (if exists)
Read .radar-suite/time-bomb-radar-handoff.yaml (if exists)
Read .agents/ui-audit/ui-path-radar-handoff.yaml (if exists)
Read .agents/ui-audit/ui-enhancer-radar-handoff.yaml (if exists)
Read .agents/ui-audit/capstone-radar-handoff.yaml (if exists)

Ledger check: If the ledger contains findings for workflows you're about to audit, note their RS-NNN IDs. When you find the same issue, update the existing finding instead of creating a new one.

Regression check: For any fixed findings in the ledger whose file_hash no longer matches the current file, flag for re-verification per the Regression Detection protocol in radar-suite-core.md.

Parse for_roundtrip_radar sections. Each companion can direct findings to this skill. Look for:

• for_roundtrip_radar.suspects[] — workflows or data paths another skill flagged as potentially broken
• for_roundtrip_radar.priority_workflows[] — workflows another skill wants audited first

If found, incorporate as priority targets in workflow selection. These are not pre-confirmed findings — verify each one independently.

What each companion provides:

• data-model-radar — model gaps that may cause data loss in specific workflows
• ui-path-radar — dead ends and broken promises suggest workflows to prioritize
• ui-enhancer-radar — visual issues in views that may have data backing problems
• capstone-radar — priority workflows from ship readiness grading

Specific incorporation rules:

• Dead-end buttons from ui-path-radar → check the workflow behind that button
• Orphaned views from ui-path-radar → verify the data path exists
• Views flagged by ui-enhancer → check if the data binding is correct before suggesting visual changes
• Model gaps from data-model-radar → trace through the workflow that creates/edits that model

If not found, proceed normally.

---

End Reminder

After every wave/commit/workflow: print progress banner → AskUserQuestion → never blank prompt.