Trailblaze Author

Author a trail from a demonstration bundle

A human demonstrated a flow on a live device. Every interaction was captured with evidence. Your job is to produce a trail that runs on its own: deterministic where possible, resilient where the screen is dynamic, and proven by you actually running it before you call it ready. You are not transcribing clicks; you are authoring a test that validates what the human said they were validating.

Work in explicit phases, in order. Do not skip the audit passes and do not claim ready without a passing verification run.

The demonstration bundle

The launching prompt gives you the bundle directory. A bundle holds ONE platform's demonstration - bundles are keyed by platform (the directory is named like demos/iphone/, demos/android/, demos/android-tablet/), and sibling platform bundles from earlier sessions may sit beside it. Inside:

Working method

Prefer the Trailblaze CLI and its MCP tools over shell spelunking. To learn what a target supports or how a selector resolves, drive the CLI (and the MCP device tools) and read this skill's references/, rather than grepping the framework source. When you do need to explore the codebase or read many files at once, hand that read-only legwork to a cheaper-model subagent and keep the authoring and verification on yourself.

After every change you make to a trail file, emit a trail_output so the Trailblaze App can show the current file. Tool calls that need a human decision pause in Trailblaze App until the human approves them, so a slow tool call is waiting on a person, not hung; keep working the plan and it will resume once approved.

Phase 1 - Understand

1. Read demo.yaml and all of actions.ndjson first. Reconstruct the story in one or two sentences: where the flow starts, what the human did, what the objective says it validates.
2. Read the start-state-hierarchy.txt and the before/after hierarchy of each step action. You need these to ground selectors and to pick assertions later; do not author from screenshots alone.
3. If event streams exist, slice them per step by timeMs and note which steps fired meaningful app events. These tell you what the app itself considered to have happened; use them to decide what is worth asserting on screen.
4. List the proof points: the on-screen facts that, if visible, prove the objective was met. A trail that taps every button but asserts nothing has validated nothing.

Phase 2 - Author

Write a unified-format trail: config: + trailhead: + trail:. Read one existing unified trail from the library for the exact schema before writing yours. The trailhead is a first-class block, never an ordinary first step.

Trailhead:

• If demo.yaml names a picked trailhead, use it verbatim (name + args) as the trailhead: recording for the demonstrated platform.
• If positioning was manual, inspect the setup actions. Prefer a durable route: if the target's trailmap has a deeplink-style or bootstrap trailhead tool that reaches the observed start state, use it (check the toolbox before naming any tool - never invent one). Only if nothing durable exists, write the trailhead as a descriptive step ("Start at <screen>") so agent-mode execution can reach it, and say so in your final summary - it is a weakness the human should know about.

One trail step per demonstrated action, plus assertions:

• Step text is a natural-language direction a human could follow ("Tap the Pay button", not "tapOnElementBySelector ..."). This is the cross-platform source of truth and the agent-mode fallback.
• The recording: for the demonstrated platform's classifier comes from the action's recorded tool YAML and ranked selector candidates. Apply the selector rules below; do not blindly copy the default.
• Coalesce noise: a mis-tap the human immediately corrected, or a scroll that was purely exploratory, does not deserve a step. The trail is the intended flow, not the raw motion log.
• Insert verify: true steps at the checkpoints where the objective is actually proven (usually after the last action, often mid-flow too). Each verify step asserts a proof point from Phase 1, grounded in an element you saw in the captured hierarchy - typically a recorded visibility assertion on that element plus step text that states the expectation in plain language.

Selector rules (durability order):

1. Semantic and unique: visible text, content description, or resource/accessibility id that appears exactly once in the captured hierarchy. Prefer these; they survive layout changes.
2. Structural (child/containment patterns) only when nothing semantic is unique.
3. Index-based only as a last resort, with a comment-worthy reason.
4. Raw coordinates: never, unless the ranked candidates offer nothing else at all - and then flag it in your summary as fragile.

• Selector strings match the WHOLE property value: Save matches only a node whose text is exactly Save. To match a substring write the regex explicitly: .*Save.*.
• Dynamic content (prices, dates, counters, usernames) must not be pinned exactly. Use a pattern that captures the stable part: .*\$\d+\.\d\d.* style regex, or assert the stable neighboring label instead.
• Keep any \Q...\E escaping the recorder emitted; it exists because the value contains regex metacharacters.