> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Broken state and recovery

> Use comet status and comet doctor to diagnose bad Classic routing, missing .comet.yaml files, malformed state, or missing evidence.

Normal Classic recovery only needs the shared `/comet` entry; see [resuming interrupted work](/en/guides/resuming-workflow). 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.

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/sd_slIArmm0kHnD4/assets/state-recovery-illustrations/01-state-recovery-first-aid.png?fit=max&auto=format&n=sd_slIArmm0kHnD4&q=85&s=4d67beebfc02917111cc37ba9a83d345" alt="Xiaoyu diagnoses broken Comet state with status and doctor, then restores evidence from file facts" width="800" data-path="assets/state-recovery-illustrations/01-state-recovery-first-aid.png" />
</p>

<p align="center">
  Recover state by diagnosing real file evidence first. Do not fake state just to move the workflow
  forward.
</p>

## 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

```bash theme={null}
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](/en/cli/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.

## Recommended flow

```mermaid theme={null}
flowchart TD
  A["/comet-classic route or state looks wrong"] --> B["comet status: inspect runtime_eval"]
  B --> C["comet doctor: diagnose install/state"]
  C --> D{"Install problem?"}
  D -->|yes| E["Follow doctor fix\ninit / update / install OpenSpec"]
  D -->|no| F["Check OpenSpec artifacts"]
  F --> G["Check Design Doc and Plan"]
  G --> H["Check working tree and verification evidence"]
  H --> I["Recover through Comet commands"]
  I --> J["Run /comet again"]
```

## Next steps

* [Resume probe](/en/cli/resume-probe)
* [Resuming interrupted work](/en/guides/resuming-workflow)
* [Project file structure](/en/guides/project-structure)
* [State and configuration](/en/concepts/state-management)