Workflow Doctor
Diagnose the broken contract before choosing repair size.
Capability Routing
Resolve triggered methodology readiness through
scripts/workflow_methodology.py. Diagnose workflow, OpenSpec, triggered Matt
resources, goal, cache, and release readiness separately.
Procedure
- Run
scripts/validate_workflow_state.py --repo <repo> --json.
- Run
scripts/doctor_workflow.py --repo <repo> --write-report --json.
- Inspect
.dev-flow.json, .planning/devflow/STATE.md, OpenSpec artifacts,
tracking status, cache drift, and generated guidance.
Also run scripts/implementation_readiness.py inspect --repo <repo> --change-id <change> --json when that canonical namespace exists. Report
Requirement/Evidence/Receipt/override trust, exact binding drift, stable
issue codes, and the one next action separately from ordinary authority.
For an active change, compare openspec status --change <id> --json and
openspec instructions <artifact> --change <id> --json; use returned
artifactPaths and actionContext to distinguish schema paths from drift.
- For unclear behavior or compatibility, route to
openspec-explore. Retired
workflow keys route to inspect_legacy_workflow_config.py.
- State root cause, broken contracts, systemic repair, tests, docs, migration,
compatibility, and verification. Then justify systemic, minimal, staged, or
deferred execution.
Legacy or mixed state produces a read-only inspection plan; diagnosis preserves
user-owned files. AGENTS.md.generated remains a merge candidate. A doctor
result is complete when it separates blockers from warnings, names owners and
hashes, and supplies a safe next command.
Report resolver evidence read-only; repairable drift is not AWAIT_HUMAN and no marker is written.
The doctor never creates or promotes a Requirement, writes a Receipt or
override, selects a fallback, runs provider commands, or installs/activates a
provider.
1---2name: workflow-doctor3description: Use when workflow state, specs, tasks, evidence, dependencies, or generated guidance drift.4---56# Workflow Doctor78Diagnose the broken contract before choosing repair size.910## Capability Routing1112Resolve triggered methodology readiness through13`scripts/workflow_methodology.py`. Diagnose workflow, OpenSpec, triggered Matt14resources, goal, cache, and release readiness separately.1516## Procedure17181. Run `scripts/validate_workflow_state.py --repo <repo> --json`.192. Run `scripts/doctor_workflow.py --repo <repo> --write-report --json`.203. Inspect `.dev-flow.json`, `.planning/devflow/STATE.md`, OpenSpec artifacts,21 tracking status, cache drift, and generated guidance.22 Also run `scripts/implementation_readiness.py inspect --repo <repo>23 --change-id <change> --json` when that canonical namespace exists. Report24 Requirement/Evidence/Receipt/override trust, exact binding drift, stable25 issue codes, and the one next action separately from ordinary authority.26 For an active change, compare `openspec status --change <id> --json` and27 `openspec instructions <artifact> --change <id> --json`; use returned28 `artifactPaths` and `actionContext` to distinguish schema paths from drift.294. For unclear behavior or compatibility, route to `openspec-explore`. Retired30 workflow keys route to `inspect_legacy_workflow_config.py`.315. State root cause, broken contracts, systemic repair, tests, docs, migration,32 compatibility, and verification. Then justify systemic, minimal, staged, or33 deferred execution.3435Legacy or mixed state produces a read-only inspection plan; diagnosis preserves36user-owned files. `AGENTS.md.generated` remains a merge candidate. A doctor37result is complete when it separates blockers from warnings, names owners and38hashes, and supplies a safe next command.3940Report resolver evidence read-only; repairable drift is not `AWAIT_HUMAN` and no marker is written.4142The doctor never creates or promotes a Requirement, writes a Receipt or43override, selects a fallback, runs provider commands, or installs/activates a44provider.
cYz26