Broken state and recovery

Normal Classic recovery only needs the shared /comet entry; see resuming interrupted work. After configuration selects Classic, the internal /comet-classic entry reads file state and chooses a phase. This page covers failures in that internal routing or damaged state. When state is damaged, the goal is to recover the real facts, not to force fields forward until the workflow continues.

Xiaoyu diagnoses broken Comet state with status and doctor, then restores evidence from file facts

Recover state by diagnosing real file evidence first. Do not fake state just to move the workflow forward.

First check: damaged state or normal interruption?

Situation	What it means	What to do
Session ended, context compacted, or device changed	Normal interruption	Run `/comet`.
A natural-language request matches multiple active changes	The target needs confirmation; state is not damaged	Read the probe `reason` and name the change to resume.
The worktree has uncommitted files	Attribution is required; state is not necessarily damaged	Decide which change owns the files before continuing.
`/comet-classic` routes to the wrong phase	Metadata and files may disagree	`/comet-classic` tries to self-heal from files; if not, run diagnostics.
`.comet.yaml` is missing or malformed	Damaged state	Run `comet doctor`.
Declared artifacts or evidence are missing	Missing evidence	Run `comet status` and inspect `runtime_eval`.

Diagnostic commands

comet resume-probe . --utterance "continue the previous work"
comet status
comet doctor

Use --json for agents and automation. For humans, start with text output. The resume probe only classifies whether the workflow should be entered. An ask_user result usually means ambiguity or a decision point, not damaged state. See Resume probe.

What comet status shows

comet status reports active changes, phase, task progress, workflow/build mode, runtime mode, current step, runtime evidence, design doc, plan, verification result, and the recommended next command. When runtime_eval fails, it tells you which command to run or which evidence to restore.

What comet doctor checks

comet doctor checks the Comet CLI version, OpenSpec CLI, Superpowers, working directories, platform Skill integrity, scripts, CodeGraph, .comet.yaml validity, and runtime evidence for each active change.

Common symptoms

Symptom	Likely cause	Start with
`comet status` has no next step	Missing or malformed `.comet.yaml`	`comet doctor`
Build cannot enter verify	Missing `build_mode`, `isolation`, or `tdd_mode`	Run `/comet` and let Classic route back to build.
Verify passed but archive is blocked	Missing verification report, branch drift, or invalid state	Restore the report, switch to the bound branch, and let the Verify guard keep `branch_status: pending`.
Archived change still appears active	Directory/state mismatch	Compare `openspec status` and rerun archive script if recoverable.
`/comet-classic` reports malformed YAML	Manual edit or broken merge	Run `comet doctor`; restore from Git if severe.

Recovery principles

Treat OpenSpec artifacts, Design Docs, Plans, tests, and the working tree as facts.
Do not hand-edit machine-owned Run fields such as .comet/run-state.json.
Do not confuse build_pause with build_mode.
Do not skip the verification-failure decision point.
Do not fake archive state by hand; use /comet-archive or comet archive.
Do not advance .comet.yaml phase manually; use comet guard --apply or comet state transition.

Missing or broken .comet.yaml

/comet-classic has compatibility paths for damaged state:

If .comet.yaml is missing, it reconstructs from openspec status --json, tasks.md, and docs/superpowers/ evidence.
If YAML is malformed, it uses file state and comet state set to repair supported fields.
If phase is open but proposal/design/tasks are complete, guard --apply can correct the phase.

If /comet-classic cannot repair the state, restore .comet.yaml from Git and run comet doctor again.

Get started

Understand Comet

Five-phase workflow

Presets

Recovery and troubleshooting

Practical scenarios

Broken state and recovery

First check: damaged state or normal interruption?

Diagnostic commands

What comet status shows

What comet doctor checks

Common symptoms

Recovery principles

Missing or broken .comet.yaml

Recommended flow

Next steps

​First check: damaged state or normal interruption?

​Diagnostic commands

​What comet status shows

​What comet doctor checks

​Common symptoms

​Recovery principles

​Missing or broken .comet.yaml

​Recommended flow

​Next steps

First check: damaged state or normal interruption?

Diagnostic commands

What comet status shows

What comet doctor checks

Common symptoms

Recovery principles

Missing or broken .comet.yaml

Recommended flow

Next steps