--- name: support-report description: > When a colocated SmartStack skill CLI fails unexpectedly at a CLIENT project — a stack trace on stderr, non-JSON stdout, an unexplained non-zero exit — OR when an audit envelope contradicts itself (a `dedupOf` mirror finding in err while its primary rule is ok on the same scope) or renders a verdict you can DEMONSTRATE wrong, you are NOT the CLI's maintainer: the files under ~/.claude are deployed copies (no sources, overwritten on update) and must NEVER be edited. This skill is the sanctioned path instead: VERIFY the failure is real (fail-closed evidence rule — reproduction, classification, never a hypothesis), check the installed CLI version against npm (a newer release may already fix it — propose the update, retest), attach what the CLI READ (`inputs[]`, scrubbed) and produce a deduplicated, reproducible report bundle + zip under .smartstack/support/ for the client to send to support@atlashub.ch. Use for « la CLI a planté », « erreur de la CLI », « bug du scaffolder », « deux règles se contredisent », « ce verdict est faux », a crashed `npx tsx skills/…` invocation, or a `cli.runtime-error` / `audit.rule-contradiction` blocker. argument-hint: "(after a skill CLI crash or a contradictory audit verdict — evidence is gathered from the failing run)" allowed-tools: [Read, Glob, Grep, Bash] # Bash: reproduce the failing command + the support-report CLI --- # /support-report — a CLI failure becomes a verified report, never a hand-fix ## The doctrine (non-negotiable) **You are not the CLI's maintainer.** At a client site, everything under `~/.claude/` (skills, agents, hooks, commands) is a **deployed copy**: the sources live in the SmartStack CLI repository the client has no access to, and the next `ss update` overwrites every local change. Therefore: - **NEVER** edit, patch, monkey-patch or "temporarily fix" a file under `~/.claude/` — the `skills-guard` hook blocks it, and the guard is right. - **NEVER** copy a deployed CLI aside to fix the copy, and never hand-write the artifact the CLI failed to produce (`cli.runtime-error` doctrine: scaffolder-owned code stays scaffolder-owned). - **NEVER** report a hypothesis. A report that reaches support@atlashub.ch must carry a PROVEN, reproducible defect — the CLI below enforces that rule; your job is to feed it honest evidence. ## When this skill fires Any colocated CLI invocation (`npx tsx skills/<…>/index.ts`) that ends in one of these shapes: | Shape | Meaning | |---|---| | Stack trace on stderr, empty/garbage stdout | Likely CLI-internal — the strongest signal | | stdout is not a JSON envelope, exit ≠ 0 | Possibly CLI-internal — needs reproduction | | Envelope `success:false` with `errors[]` | **A controlled refusal — NOT a bug.** Fix your spec | | Envelope `success:true`, exit 1/2/3, findings coherent | **A verdict (audit CLIs) — NOT a crash.** Read the envelope, act on the docs | | Envelope `success:true`, a finding `dedupOf: Y` in **err** while `Y` is **ok** on the same app/module | **A rule contradiction — a CLI defect.** Reportable; the CLI detects it mechanically from the envelope | | Envelope `success:true`, a verdict you can DEMONSTRATE wrong (rule contract quoted, doc line quoted) | **A verdict dispute.** Reportable with `dispute` (≥ 80 chars) + `disputedRuleIds` | | `'npx' is not recognized`, `EPERM`, `ECONNREFUSED` | Environment — fix the toolchain, no report | ## Protocol ### Step 1 — Rule out your own spec first, then your own doc Re-read the failing CLI's `SKILL.md` contract and compare it with the spec you sent. If the CLI answered its envelope contract (`success:false` + `errors[]`), the defect is in YOUR spec: fix it, re-run, stop here. No report. An audit `err` is not wrong because you disagree with it. It is wrong when the rule's stated contract (its table in the `/ba-audit-*` SKILL.md) is contradicted by a document line you can quote — or when two rules of the SAME envelope disagree on the SAME screen/entity/scope while one declares itself the mirror (`dedupOf`) of the other. Only those two shapes leave this step. ### Step 2 — Reproduce (honestly) - **Read-only CLI** (`derive-*`, `audit-*`, `--mode check`, `status`, `list`): re-run the EXACT same command once more and capture both runs verbatim (exitCode, stdout, stderr). For a contradiction, the second envelope must show the same pair. - **Write CLI** (`scaffold-*`, `apply`, `aggregate-*`): re-run ONLY if the first crash wrote nothing (envelope `filesCreated` empty, worktree clean). Otherwise rely on the single capture — a stack trace pointing into `~/.claude/skills/` is deterministic proof on its own; without one, the report CLI will (rightly) refuse a single run. ### Step 2b — Attach what the CLI read Support cannot reproduce from outputs alone. Name, in `inputs[]` (paths relative to `projectPath`), what the failing CLI READ — never `src/` wholesale: | CLI family | `inputs[]` | |---|---| | `audit-ba` (any dimension) | `.smartstack/ba` — add `.smartstack/sources` when SRC-* rules are involved (`raw/` binaries are never bundled) | | `derive-*` / `scaffold-*` on one module | `.smartstack/ba//` + the app's `acteur.md` (`.smartstack/ba//acteur.md`) | | `audit-cross-ref-code` / scanners of the generated app | the above + `src/.Domain` | | `documentation`, `uat-plan` | `.smartstack/core-seed`, `.documentation/docs-manifest.json` | Rules the CLI enforces: inside the project only (an escaping path refuses the whole spec), VCS / build output / previous reports / `*.Local.json` / `.env*` / key files excluded, text only, every file through the secret scrubber, 25 MiB total cap — over it, NOTHING is attached and the envelope says to narrow `inputs[]`. ### Step 3 — Invoke the report CLI with the evidence ```bash npx --prefer-offline tsx skills/support-report/cli/create/index.ts --spec-file ``` ```jsonc { "projectPath": "D:/…/client-project", "command": "npx --prefer-offline tsx skills/…/index.ts --spec-file …", // verbatim "runs": [ { "exitCode": 1, "stdout": "…", "stderr": "…" } ], // your captures "spec": { … }, // the spec you passed to the failing CLI "context": "Phase 3 ba-develop, entity Facture, scaffold-component", "analysis": "…", // optional: why you believe cli-internal "inputs": [".smartstack/ba"], // what the CLI READ — bundled, scrubbed, zipped (Step 2b) "dispute": "…", // against a controlled refusal: ≥ 20 chars, quote the contract // against a verdict: ≥ 80 chars, quote the rule contract AND the doc line "disputedRuleIds": ["SCR-022"] // verdict dispute only — rules PRESENT in the envelope findings } ``` The CLI is **fail-closed**: it classifies from evidence alone and refuses to write anything for `usage-error`, `environment`, `no-failure` (a coherent verdict), `unverified` (one run, no stack), `flaky` (diverging signatures), a dispute that does not argue or names a rule the envelope never emitted, and an input outside the project — its `nextSteps`/`errors` say exactly what to do instead. Trust the refusal; do not argue around it. It writes for `cli-internal`, `rule-contradiction` (detected on its own, no dispute needed), `disputed-usage-error` and `disputed-verdict`. ### Step 4 — Act on the envelope - **Refused** (`success:false`) → follow `nextSteps` (fix the spec, fix the environment, reproduce properly, or anchor the dispute). No report exists; continue the work. - **`update-available`** (`status: pending-retest-after-update`) → a newer CLI exists on npm; the defect may already be fixed. **Propose to the user** — one sentence, then WAIT for their yes: `npm i -g @atlashub/smartstack-cli@latest` then `ss update`. After the update, re-run the originally failing command: - fixed → tell the user the update solved it; transmit nothing; - still failing → re-invoke this CLI with the FRESH captures; the report becomes `confirmed` on the latest version. - **`confirmed`** → tell the user, in one clear block: the archive `.smartstack/support//support-.zip` (report.md + report.json + repro.md + runs/ + inputs/, sha256 sidecar beside it) is ready to **send to support@atlashub.ch**. Secrets were scrubbed before writing. Then record the blocker and **continue the run** — never halt the pipeline on a filed report. - **`rule-contradiction`** → the audit `err` is **not the client's to fix**: two rules of the CLI disagree on a valid document. Record the blocker as `audit.rule-contradiction`, never edit the BA doc (or invent an entity) to silence the mirror, and continue. ### Step 5 — Skip, never substitute The artifact the CLI failed to produce is **skipped** (and its coupled pair skipped with it, per the `cli.runtime-error` doctrine in `ba-develop/references/auto-healing.md`). You never hand-write the `.cs`/`.tsx` it would have generated, and you never touch the CLI. ## Deduplication One defect = one fingerprint = one folder. Re-invoking on the same failure bumps `occurrences` in the existing report instead of creating a new one — `.smartstack/support/index.json` is the ledger. Ten crashes of the same bug during a `/ba-develop` run produce ONE report to transmit. A rule contradiction is fingerprinted on the RULE PAIR (the defect is the rule's code, not the client's module): the same pair on ten modules — or reproduced with a narrower `--spec` — is one folder, scopes merged. Each re-invocation refreshes the `inputs/` snapshot and the zip.