# Troubleshooting

Common issues and solutions when working with specs.

## Why did my phase become stale?

A phase becomes `stale` when it was `approved` but upstream content changed. The [invalidation rules](concepts.md#invalidation-rules) are:

1. Requirements changed → design becomes stale (if approved)
2. Requirements changed → tasks becomes stale (if approved)
3. Design changed → tasks becomes stale (if approved)

To see exactly what changed, use the stale endpoint:

```
GET /api/specs/@myapp/spec/api-design/stale
```

The `reason` field explains which upstream phase changed and at which version the approval was recorded.

!!! info
    Staleness occurs when content updates (via `/spec edit` or `PATCH /api/specs/{fqn}`) change spec content after phases were approved.

## How do I see what changed between versions?

Use `/spec diff` in the CLI or the diff API endpoint:

```
/spec diff @myapp/spec/api-design
```

```
GET /api/specs/@myapp/spec/api-design/diff?v1=1&v2=2
```

The diff shows per-phase content changes in unified diff format, plus task-level changes (added, removed, modified).

If version parameters are omitted, the API defaults to diffing the two most recent versions.

## Only one version — nothing to diff

Specs start at version 1 on creation. A new version is created only when the content hash changes — metadata-only updates (like approving a phase) do not create new versions.

Use `/spec edit` to update content and create a new version, then diff to see what changed.

## Can I manually reset stale status?

Yes. Use `unapprove` to reset the phase to `draft`, then `approve` to re-approve it:

```
/spec unapprove @myapp/spec/api-design design
/spec approve @myapp/spec/api-design design
```

This clears the stale state and records a fresh approval at the current content version.

## My spec won't create — validation error

Common causes:

| Error | Fix |
|---|---|
| `'requirements' must be a non-empty string` | Add a `requirements:` section with content |
| `'design' must be a non-empty string` | Add a `design:` section with content |
| `'tasks' must be a list` | Ensure `tasks:` is a YAML list (use `- id: ...` syntax) |
| `Invalid YAML` | Check for indentation errors, unclosed quotes, or tab characters |
| `Duplicate task ID: 'X'` | Each task `id` must be unique within the spec |
| `Task 'X' depends on unknown task 'Y'` | Fix the `depends_on` reference — the target task ID must exist |
| `Circular dependency detected` | Remove the dependency cycle (A depends on B depends on A) |

See [Schema Reference](schema-reference.md) for the complete validation rules.

## How do I edit a spec?

Use `/spec edit <fqn>` in the CLI or `PATCH /api/specs/{fqn}` via the API. See [Commands](commands.md#spec-edit) and [API Reference](api-reference.md#update-spec-content) for details.

Editing opens your `$EDITOR` with the spec YAML. If the content changes on save, a new version is created and invalidation rules apply to downstream phases.

## Can I distribute specs via packs?

Not yet. Specs exist in the core artifact model but are not yet supported in pack manifests. This is tracked by [#1010](https://github.com/troylar/anteroom/issues/1010).

## Invalid FQN format

Spec FQNs follow the artifact FQN pattern: `@namespace/spec/name`. Common mistakes:

- Missing `@` prefix: use `@myapp/spec/api-design`, not `myapp/spec/api-design`
- Missing type segment: use `@myapp/spec/api-design`, not `@myapp/api-design`
- Invalid characters: namespace and name must match `[a-z0-9][a-z0-9._-]*`

The `/spec create` command builds the FQN automatically from the namespace and name arguments. All other commands require the full FQN.
