Skip to content

armelhbobdad/bmad-module-ultracode-goal / skills/ucg-status

ucg-status

Verified

Read-only status view over an ultracode-goal run, rendered from the files that run already wrote - the heartbeat snapshot, the decision-log tail, the deferred-work ledger, the escalation sidecars, and an index of known run folders. Launches nothing, attaches to nothing, writes nothing. Use when an operator asks "what is this run doing", wants to check on a long or headless run, asks which runs exist or whether one is still live, or runs `/ucg-status`.

UCG Status

Overview

/ucg-status answers "what is this run doing" from artifacts alone. It is the read side over what the spine already produces: it starts no run, attaches to no session, resumes nothing, and writes nothing. Everything it shows was on disk before it ran.

That read-only property is the whole point, not a limitation. A status view is most useful against a run that is currently going, and a reader that touched the run's artifacts would be changing the thing it claims to describe. So this skill has exactly one move: run the renderer and show what came back.

Conventions

  • This skill ships no scripts/ or customize.toml of its own: the renderer (status_render.py), customize.toml, and references/ all live in the parent ultracode-goal module. {ucg-root} names that module directory — {project-root}/_bmad/ucg/ultracode-goal in an installed project, or {project-root}/skills/ultracode-goal in a source checkout of the module itself. Resolve it once (first of those two that exists) and qualify every script path with it, so {ucg-root}/scripts/… and {ucg-root}/customize.toml resolve from any cwd. It is deliberately not {skill-root}: this is a top-level skill, so {skill-root} would resolve to this skill's own directory, which holds none of those files.
  • {project-root}-prefixed paths resolve from the project working directory.
  • {workflow.implementation_artifacts} and {workflow.deferred_work_path} resolve from the parent module's customize.toml workflow block (the same scalars the autonomous run reads).
  • Of the [workflow] block's three universal defaults, this skill loads {workflow.persistent_facts} (read-only context, and this skill runs cold) and executes neither {workflow.activation_steps_prepend} nor {workflow.activation_steps_append}. Those are operator-configured actions, and running one here would break the promise below. ucg-formalize and ucg-resolve state the same split.
  • This skill writes nothing, including no decision-log entry. A status read is not an event in the run's history, and recording every glance at a run would bury the decisions the log exists to carry.

On Activation

/ucg-status normally runs cold - outside the session that owns the run, which is exactly the situation where nobody can see the transcript any more. Resolve the scalars the renderer needs before calling it, against the parent module, so they are the same paths the autonomous run wrote to. Run uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow (on failure, merge {ucg-root}/customize.toml → {project-root}/_bmad/custom/ultracode-goal.toml → {project-root}/_bmad/custom/ultracode-goal.user.toml, scalars override / arrays append).

If a scalar cannot be resolved, do not pass an unresolved {…} token to the renderer: say which scalar failed and stop. A render rooted at a path nobody resolved would describe some other run, or no run, while looking exactly like a real answer.

1. Run the renderer

uv run {ucg-root}/scripts/status_render.py --impl-artifacts {workflow.implementation_artifacts} --deferred-work {workflow.deferred_work_path} --runs-root {project-root}/_bmad-output/ultracode-goal --repo {project-root}

--deferred-work carries the scalar Conventions told you to resolve. The two paths are independent in the parent customize.toml, and the renderer defaults the ledger to deferred-work.md inside --impl-artifacts when the flag is absent — so omitting it on a project that moved the ledger renders n/a, or a different checkout's ledger, while looking exactly like a clean read. Pass it and the render reads the same ledger the gate writes, the same way {ucg-root}/references/finalize.md threads that scalar to mem_observation.py.

--run-dir <the run folder> is what makes the decision-log tail render at all, so the invocation above - which omits it - always renders that row n/a. Do not ship that as the normal answer:

  • When the operator named a run, pass it. The runs index in the render lists the folders available to name.
  • When the operator named none, resolve it: pass the run folder whose Epic matches the heartbeat's epic row, so the default read carries the log of the run it is describing. If no folder matches, or more than one does, leave the flag off and say the tail is unscoped - otherwise n/a reads as "this run has an empty log" when it means "nobody told the renderer which log to read".

The two halves can disagree, and the render does not say so. The heartbeat is a single project-level file that whichever run ran last overwrote, while run folders are per-Epic siblings; naming a run other than the one the heartbeat describes yields a header, stories, escalations and ledger belonging to the latest run above a decision-log tail belonging to the named one. When they differ, say which is which above the render, because nothing in the render itself distinguishes them.

Pass --runs-root <dir> when the operator named a different runs root - runs kept under a non-default output root, or another checkout's runs read from here. The invocation above spells out the module's default, and no customize.toml scalar carries it, so this flag is where an operator whose runs live elsewhere says so. Only the runs index moves.

--impl-artifacts is required and the renderer refuses to run without it (exit 2, nothing rendered). Every source it reads is optional: an absent, empty or unparseable file renders n/a and the render continues. That split is deliberate and matches the rest of the module; status_render.py carries the reasoning behind it.

Pass --impl-artifacts <dir> yourself when the operator names an isolated-track run, taking the dir that run recorded in its .decision-log.md ({ucg-root}/references/ingest-and-scope.md, the cross-file/colliding-epic rule). The configured scalar is the shared track's: rooted there, the render reads the shared track's heartbeat, escalations and baselines and presents them as the answer about a different run.

2. Show what came back

Print the render. Do not re-derive, re-order, or re-judge any row: the renderer read the files, and a second opinion formed here would be a second, later reading of artifacts that may have moved on since.

Three things are worth saying out loud alongside it:

  • The [machine-derived] suffix is exclusive. Only two rendered fields carry it: the gate's own reason strings, copied across unedited from the gate result the spine last read, and the turn counter the Stop hook maintains. Every other row is copied from an artifact a model wrote - except the runs index's live / terminal word, which the renderer derives from the files on disk, not from anything a model maintained.
  • no run: means no heartbeat file, not a broken read. The runs index still renders below it, so a reader who is simply pointed at the wrong artifacts directory can see which runs do exist.
  • live means no run report is on disk yet, not that a process is attached. A run whose session died mid-flight renders live for good. The one recency signal is the heartbeat's Updated row, and it belongs to the run that wrote the heartbeat rather than to every row of the index - so when the operator asked whether a run is still going, quote that timestamp (with Phase) alongside the index row instead of reading live as the answer.

What the render carries

rowwhat it is
epic / story / position / phasewhere the spine is, from the heartbeat snapshot
last verdictthe gate's most recent verdict word
last reason(s)the gate's reason strings, verbatim [machine-derived]
budget usedturns spent against the per-story ceiling [machine-derived]
re-loops this runhow many times this run re-entered a story, from the heartbeat
profilethe profile the run is on, from the heartbeat
updatedwhen the heartbeat was last written: this with phase is how a reader judges liveness
storiesone row per in-scope story: phase, verdict, attempts, re-loops; a story that still owes its gate evidence commit or a re-gate says so (see below)
escalationsone block per escalation on disk (see below)
deferred workevery row of the ledger, across every run it has accumulated
decision log tailthe run's own account of itself, last lines - only when --run-dir was passed (§1)
runs indexevery known run folder, terminal once it holds a run report, else live

Escalations render from the typed sidecar where one exists. Where no readable one does, the block carries one of two lines, and they mean different things:

  • escalation (unpromoted: no gate verdict yet, or the session ended before Execute promoted it): only the Stop hook's raw marker is on disk, for a story that has not advanced. Execute promotes that marker only when the story's gate escalates it on its turn count, so while the gate has not ruled this is the expected state; otherwise it is the residual of a session that died before Execute promoted it, and the only evidence that the escalation happened at all. Report it as an escalation that may be pending (the gate may not have ruled yet) whose typed record is not written yet, and leave the marker alone.
  • escalation (typed record present but unreadable) - the escalation-<story>.json named on the - source: line was written and then would not parse, which is the half-written file a session killed mid-write leaves. "Never promoted" would be the opposite of what happened: report it as a typed record that needs repair, because /ucg-resolve reads that same file to reconstruct the pending decision and cannot parse it either.

A raw marker for a story the gate advanced is not an escalation at all: the gate decided completion and the overrun is a sizing note in the decision log. A story counts as advanced when its heartbeat entry's verdict is advance or defer, or when its sprint-status.yaml row reads done (a later invocation's heartbeat no longer lists it). It renders under stories as turn ceiling reached; the story advanced at its gate, so this is a sizing note and nothing is pending, on that story's row, or on a line of its own when the heartbeat no longer lists it, and not under escalations.

A marker and an unreadable sidecar can both be on disk for one story, and the marker wins the render, so an unpromoted block is worth one directory check before you report the typed record as never written.

A story that still owes its gate evidence commit says so on its row. When a repo commit hook rejects the gate's evidence commit in a way the gate may not answer, the gate escalates the story as evidence-commit-rejected and writes .evidence-owed-<story_id> beside the sidecar, listing the paths it left staged. /ucg-resolve deletes the sidecar when it closes that escalation and leaves the marker, which a resume removes once it has made the commit, or once it finds the listed paths committed already, by the operator or by a run that stopped between its commit and that removal. The story renders under stories as gate evidence commit owed when its marker was written, after a commit hook rejected it: a resume makes the commit, or removes the marker when it finds the paths committed already, with the marker's name and its paths, on that story's row, or on a line of its own when the heartbeat no longer lists it. Report the story as advanced at its gate with its evidence commit owed when the marker was written: while its evidence-commit-rejected block still renders under escalations, /ucg-resolve closes it first, and once the block is gone one resume of the run makes the commit, or finds it made and removes the marker without one. The render does not read git, so it does not say whether the paths are still staged. While this line renders the Epic is not finished, even when every story reads done and escalations read n/a: it is the state in which drive_epic.py stops evidence-owed rather than all-done.

A story that owes a re-gate says so on its row too. When /ucg-resolve closes an operator-evidence-owed escalation, it deletes the sidecar and writes .regate-<story_id>, holding sha= the assessed commit and decision= the closed id, and the gate deletes that marker once the story's next verdict is logged. Until then nothing renders under escalations for the story, and a row the heartbeat still lists keeps the verdict that escalated it, so the story renders under stories as re-gate owed: its operator-evidence-owed escalation was closed, and no gate verdict was logged since, with the marker's name, its sha= and its decision=, on that story's row, or on a line of its own when the heartbeat no longer lists it. Report the story as waiting on a gate the next resume of the run runs: while the sha= commit is still HEAD, the resume re-gates that commit against the operator's records, and once a later commit has moved HEAD past it those records are stale and the resume routes the story as if the marker were absent. The render does not read HEAD, so it does not say which of the two holds.

Optional diff-viewer affordance

When hunk is on PATH, each story that recorded a baseline commit gains copy-paste hunk show <commit> lines, so a reader can go straight from a story row to its diff: one line per commit in the story's range (its implementation commit, the gate's test backfill commit when automate made one, and the gate's evidence commit) when the repository is readable, else one line for the story's recorded end commit, or for its baseline when no end commit was recorded. When it is not on PATH, nothing about it is rendered and the render is otherwise unchanged.

It is an affordance, never a dependency, and it is confined to stdout. The probe's result never reaches an artifact: the run's gate artifacts and its headless envelope are byte-identical whether or not the viewer is installed.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall