# Debugging Workflow

Use this workflow when a consumer reports that `coding-cli-runtime` output
looks inconsistent, incomplete, or provider-specific in surprising ways.

## 1. Pick the question before the file

- Need the final answer? Start with `response`, then `artifact`.
- Need provider-direct output? Start with `raw_output_artifact`.
- Need transcript counts or tool/message facts? Start with `conversation_log`
  and `derive_transcript_facts(...)`.

## 2. Confirm the intended package layer

- Stable root package:
  execution primitives, provider specs/contracts, schema helpers, transcript
  facts.
- Preview provider adapters:
  provider-aware parsing, session lookup, continuation, and provider-native
  contract behavior.

If a consumer is reimplementing provider transcript parsing, it is usually a
sign they should be using either a provider adapter or `derive_transcript_facts(...)`.

## 3. Check contract truth before patching symptoms

- Read `provider_contracts.py` for launch/auth/path/headless facts.
- Read `provider_specs.py` for model/control truth.
- Read `docs/TRANSCRIPT_FACTS.md` before inventing new transcript heuristics.
- Read `docs/PROVIDER_CONTRACT_API_PLAN.md` if the issue looks architectural
  rather than provider-specific.

## 4. Validate against packaged tests and probes

- Package tests under `packages/coding-cli-runtime/tests/` are the first stop
  for contract regressions.
- `playground/README.md` and transcript-probe outputs are the maintainer path
  for drift-sensitive provider evidence.

## 5. Keep package vs repo concerns separate

- Fix generic package semantics in `coding-cli-runtime`.
- Fix workflow-specific policy in downstream repos.
- Do not encode repo-local rollout or benchmark behavior into the package-owned
  companion assets.
