Skip to content

Macro troubleshooting

This page lists common macro expansion problems and how to diagnose them.

Troubleshooting

If a launch prompt contains an unknown #name reference, SASE warns before launch and passes the text through literally. This is non-blocking so prose hashtags can still be used, but typos such as #reviewww are visible at sase run, sase macro expand, and from the sase tui prompt bar.

If a definition file is malformed, run:

sase macro list
sase doctor -C config.macro_definitions
sase doctor -C config.macro_input_types

sase macro list and config.macro_definitions report skipped: <file>: <error> lines for macro or workflow definitions that could not be loaded. config.macro_input_types lists unknown type names, the accepted string input alias, and enum choice/default issues, keeping the Rust suggestion text in each message. Warnings are WARN, not a load failure.

If a launch fails with a directive migration error such as %wait(priority=...) has moved to %queue, run:

sase doctor -C config.macro_directives

The check locates the definition file that still uses retired directive syntax. It scans every loaded macro body and each workflow's prompt_part text for %name / %n, %tribe / %t, %time, %edit, and %wait(...) / %w(...) calls that pass runners=, capacity=, priority=, or p=, and prints each hit as <name> (<source>):<line>: <directive> — <migration hint>. Code spans, fenced blocks, and disabled regions are skipped. Findings are a WARN, so sase doctor still exits 0 unless you add -s/--strict. Remember that a personal ~/sase/macros/<name>.md or project sase/macros/ copy shadows a plugin or package macro of the same name, and sase macro show <name> reveals which definition wins.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.