State Damage and Recovery

To restore Classic normally, only the unified entry /comet is required (see Restoring Interrupted Work ). After configuring and entering Classic, the internal /comet-classic will read the file status and select the stage; this page only handles this internal routing exception or status damage. When the state is damaged, first restore the repository’s actual state, and then allow the process to continue based on the correct state. Do not forcibly modify the fields just to understand the lock process.

Little Fish diagnoses bad conditions on the status emergency table using Status and doctor, and restores evidence according to the file facts.

When recovering state, first inspect tangible file evidence and repair according to suggestions. Do not manually forge state just to advance the workflow.

First determine: Is state corrupted, or was work simply interrupted?

Symptom	Issue Type	Resolution
Session interrupted, context compressed, or switched devices	Normal interruption	Invoke `/comet` directly (see Restoring Interrupted Work)
Natural language request matches multiple active changes	Target ambiguity (not corruption)	Check the `reason` in recovery probe results and specify the target change to resume
Uncommitted changes in working tree	Attribution needed (not corruption)	Confirm which change the modifications belong to before continuing
`/comet-classic` routed to incorrect phase	Potential metadata/file discrepancy	`/comet-classic` self-heals based on files. If still unresolved, run diagnostics
`.comet.yaml` missing or malformed	Corrupted state	Run `comet doctor` for diagnostics
Declared artifacts/evidence missing from disk	Missing evidence	Run `comet status` and inspect `runtime_eval`

Diagnostic command

comet resume-probe . --utterance "Continue with the work just now"  # Only read to determine whether it should be restored
comet status        # Look at the phase, task completion degree, and runtime_eval of the active change
comet doctor        # Diagnose installation, environment, Skill integrity, and the validity of.comet.yaml

Adding --json is suitable for reading to Agents or automated tools. Ordinary users first look at the text output. Recovery detection only covers the decision before entering a workflow. When it returns ask_user, it commonly indicates multiple changes, uncommitted workspace edits, or a user decision point, not state corruption. For details, see the Recovery probe command.

What to watch on comet status

Each active change reports: phase, task done/total, workflow | build_mode, run_step, runtime_mode, runtime_eval (whether the declared step evidence is truly on the disk), design, plan, verify_result, and next: prompt. When runtime_eval fails, run < command > or restore missing evidence (...) will be prompted - follow the prompt to provide evidence or restore.

What does comet doctor watch

Check the Comet CLI version, openspec CLI, Superpowers, working directories (docs/superpowers/specs, docs/superpowers/plans), the integrity of skills on each platform, whether scripts exist, and CodeGraph And the validity of .comet.yaml and runtime_eval for each change. Common repair tips: npm install -g @fission-ai/openspec@latest, run: comet init, run: comet update --scope ....

Common symptoms and management

Symptoms	Possible reasons	What to do first?
`comet status` has no next step	`.comet.yaml` is missing or has an abnormal format	`comet doctor`
build cannot enter verify	Missing `build_mode`/`isolation`/`tdd_mode`	Re-call `/comet` to route Classic back to build for supplementary selection
verify passed but cannot archive	Missing verification reports, branch binding drift or abnormal status	Supplement the verification report, switch back to the bound branch, and keep verify guard `branch_status: pending`
After archiving, it still shows “active”	Manual movement of directories or status is not synchronized	Check with `openspec status` and re-run with the archive script (recoverable)
`/comet-classic` reports an abnormal format of `.comet.yaml`	The document was manually corrupted	`comet doctor`;” In severe cases, restore `.comet.yaml` from git

Restoration principle

** With documents as evidence ** : OpenSpec artifacts, Design Doc, Plan, test results, and the actual working tree are the only trusted source of state.
** Do not manually write the machine-owned Run field ** (.comet/run-state.json etc., maintained automatically by Comet).
Don’t mistake build_pause for build_mode - they are different fields.
** Do not skip the verify failure decision point ** - It is up to you to choose to fix or accept the bias.
** Do not manually forge the archive status ** - Archiving is completed by /comet-archive or comet archive.
** Do not manually edit the .comet.yaml advance phase** - use comet guard --apply or comet state transition.

What should I do if.comet.yaml is missing or broken

/comet-classic has compatible paths for bad states:

When .comet.yaml is missing, roll back to the openspec status --json + tasks.md + docs/superpowers/ file to check the reconstruction status.
When the format is abnormal, the file status shall prevail. Correct it with comet state set and then continue.
When proposal/design/tasks are complete, guard --apply to correct the status first and then make a judgment.

If /comet-classic cannot be repaired by itself (for example, if the file is severely damaged), restore .comet.yaml from git and then run comet doctor to confirm.

Recommended processing flow

Next step

Resume Probe Command — Distinguish between requests that can be automatically resumed, require confirmation, or should not enter workflow
Resuming Interrupted Work — Classic normal interruptions only require /comet
Project File Structure — In which files state is stored
State Management — .comet.yaml fields and state guards

Understand Comet Classic

Five-phase workflow

Presets

Recovery and troubleshooting

Practical scenarios

State Damage and Recovery

First determine: Is state corrupted, or was work simply interrupted?

Diagnostic command

What to watch on comet status

What does comet doctor watch

Common symptoms and management

Restoration principle

What should I do if.comet.yaml is missing or broken

Recommended processing flow

Next step

​First determine: Is state corrupted, or was work simply interrupted?

​Diagnostic command

​What to watch on comet status

​What does comet doctor watch

​Common symptoms and management

​Restoration principle

​What should I do if.comet.yaml is missing or broken

​Recommended processing flow

​Next step

First determine: Is state corrupted, or was work simply interrupted?

Diagnostic command

What to watch on comet status

What does comet doctor watch

Common symptoms and management

Restoration principle

What should I do if.comet.yaml is missing or broken

Recommended processing flow

Next step