`/diagnose` command reference¶

The /diagnose command (shipped v0.5.0, parent S4) is the human-facing surface for the diagnostic-legibility agent. It is defined in diagnostic-legibility/commands/diagnose.md. This page is the contract reference; for a task walkthrough see run the /diagnose command.

Signature¶

/diagnose <scope> [--out <dir>]

A single verb — no subcommands.

Arguments¶

Argument	Required	Meaning
`<scope>`	yes	Directory path, file list, or free-text description of the area to diagnose. Forwarded to the agent's `scope:` line verbatim; the command performs no scope validation.
`--out <dir>`	no	Output directory override. The filename convention still applies beneath it.

If <scope> is absent the command surfaces /diagnose requires a <scope> argument and aborts with no dispatch and no write.

Dispatch contract¶

The command dispatches the diagnostic-legibility agent via the Task tool with subagent_type: diagnostic-legibility and a prompt whose first line is mode: full and second line is scope: <scope>. The agent's mode: cross-check-only is not reachable through /diagnose.

The agent returns either a markdown response containing a LegibilityModel YAML block, or a single diagnostic-legibility refusal: <reason>. line with no YAML block.

Refusal handling¶

If the response contains diagnostic-legibility refusal: and no YAML block, the command surfaces the line verbatim and aborts: no report is rendered, no file is written, no directory is created.

Output path¶

diagnostic-legibility/output/<scope-slug>-legibility-<YYYY-MM-DD>.md

Directory — default diagnostic-legibility/output/ (gitignored), overridden by --out. Created with mkdir -p at write time, on accept only.
<scope-slug> — <scope> lowercased, non-alphanumeric runs collapsed to single hyphens, leading/trailing hyphens trimmed; falls back to scope if empty.
<YYYY-MM-DD> — the date the command resolved when substituting the generated_at placeholder; the same instant feeds the report body's generated_at and the filename stamp.
Extension — .md. The raw LegibilityModel YAML is not embedded in the report.

Report structure¶

Section	Contents
Header	`# Diagnostic Legibility report — <scope>` and a six-row metadata table (Scope, Generated at, Generated by, Cross-check status, Architectural elements, Domain elements).
`## Cross-check summary`	A plain-language `cross_check_status` line, plus A→D and D→A correction counts (elements carrying ≥1 `CC<N>` entry per direction — the "elements revised" definition). The counts are a lower bound on elements touched: they count elements revised as the subject of a cross-check; side-effect revisions named in a subject's prose carry no `CC<N>` entry and are not counted.
Side-by-side summary table	Two columns (Architectural \| Domain) with each side's element count and elements revised. This table is the only "side-by-side" part of the report.
`## Models`	Stacked `### Architectural model` then `### Domain model` bodies; each element shows confidence, description, evidence, and `challenge_notes` grouped Self-challenge (`Q<N>`) then Cross-check (`CC<N>`) in canonical order.

`cross_check_status` values¶

Value	Meaning in the report
`completed`	Cross-check ran on both collections.
`skipped_asymmetric` (real one-sided scope)	Only one collection was populated; the populated collection is still self-challenged.
`skipped_asymmetric` (empty-scope sentinel)	The scope yielded no elements — the report's only element is the `(empty scope)` sentinel. The command renders a distinct human gloss ("Scope yielded no elements; cross-check did not run.") rather than "one collection was populated", since the same wrapper value carries both meanings.
`not_run`	Cross-check did not run (field absent on a v0.3.0-compatible / externally-supplied model). Not produced by `/diagnose`, which always dispatches `mode: full` against a freshly-emitted model; rendered only for forward-compatibility.

Validation checkpoint¶

Before the confirm-before-write gate the command reads the rendered report back and checks (narrow, against the parsed YAML): header completeness; no literal <DISPATCHER: substring; cross-check summary present with both counts consistent with the YAML; both collections rendered; CC<N> entries after Q<N>; header counts consistent. Deviations are fixed in place — the agent is not re-dispatched. The checkpoint is not an independent oracle; the human accept gate is the last line of defence.

Confirm-before-write gate¶

The command prints a summary naming the resolved target path (flagging an overwrite if the file exists) and prompts accept / abort. On accept it mkdir -ps the directory and writes the report; on abort it writes nothing and creates no directory. This realises the agent-emit + dispatcher-persist + human-disposes architecture with a real pre-write disposition.

/diagnose command reference¶