Skip to main content
/pm:detour handles mid-build interruptions without losing the thread. Pass it a description of what came up — PM classifies it, either logs a quick fix or pushes the current epic onto the detour stack, and sets up the new work in its own lane. The classification step is mandatory: do not start fixing before you know which path you’re on.

​
Usage

​
Minimal detour (fast path)

A minimal detour is small, self-contained, has no design ambiguity, fits before the next compaction, and doesn’t reshape the current proposal. If it passes all those tests, fix it immediately — no stack entry, no new epic. The flow is: fix the issue → test → commit → record the detour so it leaves a trail:
This appends a timestamped line plus the current commit SHA to .conductor/detours.log. Then resume the paused work as normal. Quote the text (0.44.0). The log is append-only, so the engine refuses a line it would record wrong rather than writing it: an unquoted word shaped like a flag is refused (log-detour fixed --no-verify usage → conductor: unknown flag --no-verify for log-detour — it accepts: --force, then If '--no-verify' is part of the text, quote the whole value.), and --help anywhere after the verb prints help instead of appending. --force is never part of the text: log-detour fixed it --force records fixed it. If you invoke /pm:detour --minimal "<what>", PM takes exactly this path and stops — no classification prompt, no push.

​
Substantial detour (full flow)

A detour is substantial when it needs its own design, changes shared behavior, or is multi-step. It becomes its own epic in the appropriate lane and is worked through that lane’s full workflow. When a detour is substantial, follow these steps before building anything:
  1. Make the current epic’s tasks.md reflect reality and commit so nothing is left uncommitted.
  2. Register the detour epic first, then run push-detour <parent> --detour <new-id> --reason "<why>" (--reconcile | --no-reconcile). The verb IS the transition — never hand-edit .conductor/state.json to push or pop a frame, because the verb is what supplies the validation, the write-conflict guard, the read-back and the Honcho line.
  3. That one write sets the parent’s status to paused and pushes a stack frame holding pausedEpic, pausedAt, reason, spawnedDetour, and reconcileOnResume (say --reconcile unless you are certain the detour touches nothing the paused epic depends on — exactly one of the two flags is required and there is no default).
  4. Create the detour as a new epic with role: detour at P0 by default, in the appropriate lane.
  5. Record cross-links: the detour gets a resolves-blocker-for link pointing to the parent; the parent gets a may-invalidate link pointing to the detour.
  6. Set the detour epic as active, then create its OpenSpec proposal and build through the normal propose → review → apply → review → commit → archive loop.
Example: You’re mid-build on api-gateway (openspec, P1) when you discover webhook HMAC verification is broken in production. That’s substantial — it needs its own spec, and its fix will change the shared request-validation path the api-gateway work depends on. PM pauses api-gateway, pushes a stack frame, and creates webhook-hmac-fix (P0, role: detour), then opens a fresh proposal for it.
  • --reconcile writes reconcileOnResume: true onto the parent’s may-invalidate link to this detour — the ARMED record /pm:resume’s record-reconcile must later answer, and the only thing that arms one (a link supplied by hand with --link is written false). --no-reconcile writes false on a link it creates and never lowers an existing true. Pushing --reconcile again to a detour already answered re-arms it: the earlier verdict moves to superseded and a new one is owed.
  • A --no-reconcile push never cancels an earlier obligation. The parent’s reconcileNeeded is ORed, not overwritten, so pausing an epic that still owes a verdict says so instead of claiming there is nothing to reconcile:
    and the later pop prints the RECONCILE GATE for d rather than a Honcho line saying no reconcile was required.
  • While the parent owes, its record is protected. update-epic <parent> --clear-links (including the one-write clear-and-re-supply repair) and remove-epic <detour> are refused until the verdict is recorded, because each would strip the link the verdict must name:
    remove-epic is for a detour registered in error, and even then it waits for the verdict. Correcting a link’s reason with a same-target --link keeps its arming record and any verdict.

​
When the paused epic is not coming back — drop-detour (0.46.0)

/pm:resume is for the epic that WILL resume: it pops the top frame, reactivates the epic and runs the reconcile gate. drop-detour is for the epic that is NOT coming back — the pause has to end, but there is nothing to reconcile and nobody to resume.
It is the inverse push-detour never shipped, and it is deliberately not pop-detour --force: the two differ in every observable way — which frame is selected, whether the active pointer moves, whether the status changes, and whether an obligation is armed or ended. It:
  • selects the frame by epic, not by position — it ends the frame naming <pausedEpicId> wherever it sits in the stack. A LIFO-only drop would leave a buried frame stuck, which is the jam it exists to clear;
  • never resumes the epic, never moves the active pointer, never changes its status;
  • accepts an epic that is already archived — that is the state every existing jam is already in, and the state the archive-drift heal can still produce;
  • requires a non-empty --reason, and refuses, writing nothing, when no frame pauses that epic (naming pop-detour as the verb for the epic at the top of the stack).
Ending an obligation is not answering it. No reconcile verdict is written. The paused epic’s may-invalidate link is disarmed and kept, carrying a drop stamp (droppedAt + the reason), so the record distinguishes dropped from reconciled and the evidence that an obligation existed survives the obligation ending. reconcileNeeded is then recomputed by the same rule a verdict transition uses — an earlier detour still unanswered keeps the obligation; the drop ends only its own. The interactive archive verb refuses an epic a live frame still pauses, and names this verb as one remedy (alongside resuming it). That refusal and this verb are one fix: an exit reachable only when the jam is absent is no exit, so neither ships without the other. Unlike push and pop, drop-detour writes no Honcho line: a drop ends an obligation rather than moving work between epics, and it already records itself durably on the disarmed link.

​
Rows the commit hook writes for you — and retract-detour (0.45.0)

commit-nudge runs after every Bash call, on success (PostToolUse) and on failure (PostToolUseFailure). It reads HEAD’s reflog from the position it recorded last time and reports every commit that landed since, oldest first — including one followed by a checkout in the same call, and every commit of a call that made several.
  • When it logs a row. While a detour is live it writes DETOUR-COMMIT against the detour epic. With no detour but an active epic, a small (≤3 files) fix:/chore: commit that does not name the active epic is logged as AUTO-DETOUR — a minimal detour nobody declared.
  • When it does not (0.52.0, #213). A commit is also left out of the detour trail when the record ties it to the active epic: it is already attributed to an epic, its subject names the active epic’s id, or every path it changed was already changed by a commit attributed to the active epic (that last rule needs two or more changed paths, and a commit made while a detour is open is never suppressed). A commit another epic already holds is no longer offered for attribution again. The hook reports at most 50 commits per run and says how many remain.
  • When it does not. A commit touching any of the active epic’s own artifacts (openspec/changes/<id>/, its plan path, its spec path) is that epic’s work, not a detour; a commit confined to a paused epic’s own artifacts writes no DETOUR-COMMIT. A commit touching only pm’s own generated files (state.json, PROJECT.md, render-stamp.json, the observation record) is bookkeeping — in a nested conductor too, because paths are compared from the conductor root. A commit reachable from no branch is named as rewritten or abandoned and gets no row and no attribution command. A commit that already has a row is never given a second one, whatever that row’s sha length.
  • Provenance. Every report says the commits landed since the last observation — this call, another terminal, or a parallel call; the hook cannot tell which. It never claims the call made them, so a commit from another terminal can still be logged against the active epic.
  • An amend replaces. When a commit --amend leaves the replaced commit on no branch, the engine retracts that commit’s automatic row (reason amended into <new sha>) and, for each epic whose attributedCommits holds it, prints update-epic <id> --withdraw-commit <replaced> --withdrawal-reason "…" before any attribution command. It never withdraws anything itself. An undone amend replaces nothing.
A wrong automatic row is corrected with the verb, never by editing the log — detours.log is git-ignored while the PROJECT.md it renders is tracked, so a hand-removal leaves the false row in what gets committed:
It appends one RETRACTED row covering every AUTO-DETOUR and DETOUR-COMMIT row of that commit (matched by prefix, whatever the row’s abbreviation length), removes nothing, and re-renders PROJECT.md without them. <sha> is a commit sha, not a ref — HEAD is refused, so run git rev-parse <ref> first; a sha whose commit has been pruned must be at least 7 hex characters and match one commit’s rows. It refuses, naming the reason and writing nothing: no matching row, a MINIMAL-only row (a declaration, not retractable), an already-retracted commit, a missing or empty --reason, and a detached tree. There is no un-retract — re-declare with log-detour.

​
Honcho memory

After a substantial detour push, preserve the context pivot for Honcho so it survives across repos and compactions:
This prints a formatted paused <parent> for <reason> memory line and appends a timestamped copy to .conductor/honcho-memories.log. Paste the printed line into your Honcho MCP memory tool. The engine only formats and logs the string — it never calls Honcho itself.

​
After the detour

When the detour epic is archived and its work is committed, run /pm:resume to pop the stack frame and run the mandatory reconcile gate. Do not skip the gate — it is the structured re-entry that checks whether the detour’s changes affect the paused plan.
When in doubt, treat it as substantial. A needless stack entry is cheaper than re-deriving a lost context after compaction.