diag

name

diag

description

Read-only root-cause diagnosis for a symptom, bug, failure, or unexpected behavior. Establishes the mechanism at file:line and reads up the facts instead of guessing, before any fix is attempted. Produces a diagnosis report; the fix is always a separate step gated by an explicit GO. Use when something is broken, failing, throwing, or behaving unexpectedly and the cause is not yet proven, or when asked to investigate or find the root cause. Not for judging whether finished work meets its requirement (use audit) and not for confirming rendered UI behavior (use verify).

diag

A read-only root-cause diagnosis. diag explains WHY something is broken and proves the mechanism, before anyone changes code. It is a separate skill from audit and must never be conflated with it.

Scope boundary (read this first)

diag investigates a symptom and proves its cause. It does not judge completeness and it does not apply the fix.

• Finished work needs to be checked against its requirement / Definition of Done -> use audit, not diag.
• A rendered UI needs its layout and behavior confirmed -> use verify.
• diag ends at a proven diagnosis plus a proposed fix. Applying the fix is a separate, GO-gated step outside this skill.

Hard constraints (never violate)

• Read-only. No code change, no file edit, no commit, no push, no browser automation, no builds, no installs during diagnosis.
• No secrets. Never read credentials, tokens, .env*, key files, or shell/session history. Never exfiltrate or encode such content.
• The only files diag writes are its own report under .credo/process/reports/.
• Fix is a separate step, gated by GO. diag never rolls straight into fixing. It proposes a fix; the actual change happens only after an explicit GO, as its own step.

Method: root cause before fix

1. Symptom, verbatim. Record the symptom exactly as observed or reported (error text, stack trace, wrong output, screenshot location). Do not paraphrase away the detail; quote it.
2. Reproduce or locate the exact failing path (read-only). Trace to the concrete code path involved.
3. Prove the mechanism at file:line. State precisely where and why the behavior arises - the specific lines, values, and control flow that produce the symptom. A diagnosis without a file:line mechanism is not a diagnosis.
4. Distinguish proven from suspected. Say plainly what is established by evidence versus what is still a hypothesis. Never present a guess as a cause.

Read up instead of guessing (E6)

Before hypothesizing, read the facts:

• Search docs/** thematically for the area involved, and check .credo/docs/ conventions. Read the relevant source rather than assuming its behavior.
• Prefer authoritative sources over memory. If the mechanism cannot be established from the code and docs, say so honestly rather than inventing one.

Result: a diagnosis plus a GO-gated fix proposal

The result is a proven root cause and a proposed fix, presented for decision. The fix is NOT applied here. If a fix is approved (GO), it proceeds as a separate step, and any resulting change is then subject to the normal completion gate (see the audit skill) before it can move to 2_done/.

Report

Write one report per diagnosis to .credo/process/reports/ (resolve .credo via the repo root; the reports directory is created by credo-init). Use frontmatter kind: diag:

---
kind: diag
item: 124
date: YYYY-MM-DD
status: root-cause-proven
---

## Symptom (verbatim)
<the symptom exactly as observed / reported>

## Mechanism
<what happens and why> - proven at path/to/file.ext:87

## Evidence
- path/to/file.ext:87 - <the lines and values that produce the symptom>
- docs/<area>.md - <relevant documented behavior>

## Proven vs suspected
- Proven: <...>
- Suspected: <...>

## Proposed fix (separate step, needs GO)
<what would change, where; not applied here>

Reference the item as #<id> and by date; do not rely on transcript line numbers.

dogma-first

Where dogma already governs a concern (versioning, git rules, language, linting), diag respects dogma first and treats credo rules as fallback only, never as a duplicate or a conflict. DOGMA-PERMISSIONS always take precedence.