mutagen-status - SKILL.md Agent Skill

name: mutagen-status description: Explicit invocation only. Read-only report on the mutagen workflow: upstream docs, April readiness, Shredder validation, pipeline mode, queue progress, active slice, heartbeat/gate telemetry, open escalations, recent reviews.

$mutagen-status — report on the workflow

Strictly read-only. Collect state, report concisely, recommend the next action.

Fast path

Run bash "$MUTAGEN_ROOT/scripts/status.sh" --format markdown.
If it succeeds, use that as the primary status report.
Fall back to the manual collection steps below only when the helper fails, when a required file is malformed, or when you need to augment the helper with extra context it could not derive.

Collect

Upstream documents. For each of PRD / ADR / DDD / ISC / DSD, find the instantiated file (check docs/ conventions and repo root) and read its status line. Report path, status (Draft / In Review / Approved / Accepted / Missing), Last reviewed date if present, count of <TBD> markers.
April's Readiness Brief. Read .mutagen/state/readiness-brief.json if present. Report date, per-document status, Shredder readiness projection (green / yellow / red), recommendation. If present, trust it over re-computing from raw docs. If absent, fall back to step 1.
Elicitation checkpoint. Read .mutagen/state/elicitation.jsonl if present. Each line is one April turn. Report:
- total_turns and last_turn number.
- last_mode (kickoff / gap-fill / iteration / resume), last_ts, last_user_message_summary.
- unanswered_questions — questions present in any prior questions_asked but not yet present in any later answers_recorded[].q.
- open_tbds from the latest record.
- Whether the latest record set readiness_brief_emitted: true.
- malformed_lines count if any line failed to parse — flag as a recoverability gap that must be repaired before the next April turn. The checkpoint is what makes a fresh April spawn resumable. Its presence with no upstream docs yet means an interview is in progress, not stalled.
Shredder's Validation Report. Read .mutagen/state/validation-report.json if present. Report date, bundle_ready, summarise readiness_issues and validation_findings. Flag as stale if the bundle has been edited since.
Pipeline mode. Read .claude/workflow.json. Report mode (full / lightweight), review.max_retries, heartbeat thresholds. Absent = default full, default retries = 2.
Slice queue. Prefer slices/queue.json; fall back to slices/slicemap.md when JSON is missing, and only then to legacy slices/queue.md if needed. Report:
- Total slices, grouped by layer.
- Per-status counts: pending, in_progress, completed, refused, escalated, blocked_retry.
- Next pending slice: ID, assigned agent, layer, one-line objective, attempts, review_required (in lightweight mode).
Queue validation. Read .mutagen/state/queue-validation.json if present. Treat it as the harness verdict on whether slices/queue.json is executable. Report:
- ok, error_count, warning_count.
- Any issues, summarised with level, code, slice_id when present, and message.
- Whether the report is stale. If the report carries queue_contract_hash metadata, recompute the current queue-contract hash and compare that instead of file modified times. Runtime-mutated fields such as status, attempts, micro_corrections_used, verdicts, completed_at, and escalation_reason do not make the validator stale. Fall back to modified-time comparison only for legacy reports without hash metadata.
- If slices/queue.json is missing but the validator report exists, flag it as orphaned.
Active slice. Read .mutagen/state/active-slice.json if present. Report slice ID, stage, active_agent, host, attempts, and any degraded_capabilities. If the file exists outside a $mutagen-execute-next run, flag it.
Heartbeat telemetry (only if an active slice exists). Run bash "$MUTAGEN_ROOT/scripts/heartbeat.sh" 300. Report the JSON (total, window_calls, bytes_last_window, last_run_length). If last_run_length >= LOOP_THRESHOLD (default 5), flag a likely tool-call loop.
Gate telemetry. From slices/queue.json, report Tiger Claw verdict counts across the last 10 completed slices. Bishop is disabled in the automated loop, so his counts are always all-skip — surface that as disabled rather than implying he rendered verdicts.
Open escalations. From slices/queue.json, list slices whose status is escalated, refused, or blocked_retry with their escalation_reason.
Reviews. Count entries under reviews/ and list the last three.

Report

mutagen workflow status — {YYYY-MM-DD HH:MM}

Upstream documents:
  PRD  {status} ({path})  · TBDs: N · last reviewed: YYYY-MM-DD
  ADR  {aggregate status} · {count} accepted / {count} draft
  DDD  {status} ({path})  · TBDs: N · last reviewed: YYYY-MM-DD
  ISC  {status} ({path})  · TBDs: N · last reviewed: YYYY-MM-DD
  DSD  {status} ({path})  · TBDs: N · last reviewed: YYYY-MM-DD

April Readiness Brief ({date} · {mode}):
  Recommendation: {...}
  Shredder readiness: PRD 🟢 · ADR 🟢 · DDD 🟡 · ISC 🔴 · DSD 🟢
  Cross-doc issues: N                                (or "none noted")
  (or: no readiness brief on file — run $mutagen-elicit)

Elicitation checkpoint (.mutagen/state/elicitation.jsonl):
  Turns: N                                           (⚠ malformed lines: M, when present)
  Last turn: N · mode: {kickoff|gap-fill|iteration|resume} · ts: {ts}
  Last user msg: {one-line summary}
  Unanswered questions: N
    - {question}
  Open <TBD>s: N
    - {id} (owner: {who}) due {when}
  Readiness brief on latest turn: true | false
  (or: no checkpoint on file — a fresh April spawn would re-interview from kickoff)

Shredder Validation Report ({date}):
  Bundle ready: true | false
  Readiness issues: N       · Validation findings: N
  (or: no validation report on file — run $mutagen-slice)

Pipeline mode: full | lightweight   ·  max retries: N

Slice queue (slices/queue.json):
  Total: N  ·  pending: N · in_progress: N · completed: N · blocked_retry: N · refused: N · escalated: N
  By layer: L1: N · L2: N · L3: N · L4: N · L5: N · L6: N
  Next up: {slice-id}  ·  {author_agent}  ·  L{n}  ·  attempts {k} · "{objective}"

Queue validation ({path}):
  Executable: true | false                         (flag stale / orphaned when applicable)
  Errors: N  ·  warnings: N
  Issues: none noted
  - [error|warning] {code} · {slice-id?}: {message}
  (or: no queue validation report on file — run $mutagen-slice)

Active slice:
  {slice-id}  ·  stage: {stage}  ·  agent: {active_agent}  ·  host: {host}  ·  attempts {k}
  Degraded host features: {comma-separated list}   (omit when empty)
  Heartbeat (last 5 min): calls {N} · bytes {N} · last-run {tool}×{len}
    (⚠ tool-call loop detected) | (⚠ stalled) | (nominal)
  (or: no active slice)

Latest scope violation:
  {slice-id}  ·  stage: {stage}  ·  agent: {active_agent}  ·  class: {class}
  path: {path}
  recorded: {ts}
  artifact: .mutagen/state/scope-violation.json
  (or: none)

Recent gate telemetry (last N completed slices):
  Bishop:     disabled (all slices recorded skip)
  Tiger Claw: clean M · gap N · defect 0 · skipped K

Open escalations: {count}
  - {slice-id} [{status}]: {escalation_reason}

Recent reviews (last 3):
  - {slice-id}: 🟢/🟡/🔴 — reviews/{slice-id}.md

Next actions:
  - {e.g. "PRD still Draft — run $mutagen-elicit"}
  - {e.g. "Queue validation stale — re-run $mutagen-slice before dispatch"}
  - {e.g. "Queue invalid — fix Shredder output before $mutagen-execute-next"}
  - {e.g. "Queue clear — design bundle may need a new elicitation round"}
  - {e.g. "Escalation pending on L3-Auth-0001 — awaiting user decision"}

Reminders

Read-only. Never writes. Flag a stale .mutagen/state/active-slice.json rather than modifying it.
If any upstream document is missing, recommend $mutagen-elicit.
If all Approved but no queue, recommend $mutagen-slice.
If .mutagen/state/queue-validation.json is missing, stale, orphaned, or reports ok: false, recommend $mutagen-slice instead of $mutagen-execute-next.
"Stale" means the executable queue contract drifted after validation, not that Karai updated runtime bookkeeping fields during a healthy run.
If a queue has pending slices and the queue validation report is current with ok: true, recommend $mutagen-execute-next.
If an escalation is open, recommend resolving before proceeding.
If .mutagen/state/scope-violation.json exists, surface it even when the queue already shows the slice escalated — it is the canonical detail payload for the latest Traag DENY.
If the active slice reports degraded_capabilities, surface them plainly. "Serial only" and "advisory scope" are runtime facts, not folklore.
If heartbeat shows a high last_run_length, recommend investigating.
Shredder's Validation Report tells you whether the design bundle was sliceable. The queue validation report tells you whether the emitted queue is actually executable.