Error Handler Pattern

---
name: error-handler-pattern
description: Chuẩn hóa error handling theo Architecture Profile: typed error, response schema, logging và retry
user-invocable: true
---

# Error Handler Pattern (`/error-handler-pattern`)

**Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`CRITICAL`, `WARNING`, `CONFIGURATION GAP`, `APPROVED`, `PENDING HUMAN REVIEW`), error codes, file paths, and CLI commands are language-invariant.

Audit hoặc thiết kế error handling theo `CONSTITUTION.md` `ENG-02`.

## Tham số

- `--file=<path>`: File cần audit; skill chỉ đưa remediation proposal.
- `--feature=<slug>`: Audit toàn feature.
- `--mode=audit|scaffold`: `audit` phân tích gap; `scaffold` đề xuất template/mapping phù hợp profile dưới dạng proposal, không ghi file.

## Architecture Profile gate

- Core-only được audit error taxonomy và layer boundary.
- HTTP handler, request ID, logger adapter, package import, retry client config và test command chỉ được sinh khi binding `APPROVED` có evidence.
- Binding thiếu thì báo `CONFIGURATION GAP`; không sinh Express, NestJS, Fastify, logger package, test command hoặc retry API suy đoán.

## Quy tắc

- Domain/usecase throw typed error, không import HTTP/transport type.
- Interface map typed error thành response theo approved transport adapter.
- Infra translate provider/DB error tại boundary, không leak driver detail hay stack.
- Khi HTTP binding đã `APPROVED`, response theo `ENG-02` là `{ error_code, message, request_id, timestamp }`; `details` không chứa PII.
- Với event/CLI/transport khác, error contract do `SPEC.md` và binding đã approved xác định; `request_id` chỉ lấy từ request-context mechanism đã approved.
- Retry chỉ ở `src/infra/`, chỉ cho idempotent operation hoặc operation có idempotency guarantee; timeout/backoff phải do Spec/constraint xác định.

## Core template

```typescript
export abstract class AppError extends Error {
  abstract readonly errorCode: string;
  readonly isOperational = true;

  constructor(
    message: string,
    readonly details?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}
```

Đặt tại `src/shared/errors/`. Chỉ map `errorCode` sang HTTP/event status ở approved interface adapter.

## Output

```text
ERROR HANDLING AUDIT REPORT
Feature: {slug} | Profile: v{version}
CRITICAL:
  [ENG-02] {path}:{line} — {exposed stack/PII/provider error or missing safe mapping}
WARNING:
  [BOUNDARY|RETRY|LOGGING] {path}:{line} — {finding}
CONFIGURATION GAP:
  {missing binding; framework-specific remediation omitted}
REMEDIATION:
  - Binding: {approved binding or human decision required}
  - Change: {profile-compatible action}
  - Verification: {exact approved command or N/A with reason}
  - Spec/Plan impact: {artifact or N/A}
```

Error code, visible message, retry hoặc idempotency change cần cập nhật `SPEC.md` trước code. Chỉ thay đổi chính `ENG-02` trong `CONSTITUTION.md` mới cần RFC; thay đổi feature dùng `/sdd-review` trước execution.

## Hướng dẫn sử dụng
- **Khi dùng:** Audit hoặc lập proposal error taxonomy/mapping theo `ENG-02` và Architecture Profile.
- **Không dùng:** `scaffold` vẫn read-only proposal; không viết `src/`, thêm logger/package hay chạy retry command ngoài `/add-execute` boundary.
- **Input:** `--file` hoặc `--feature`; `--mode=audit|scaffold`; reject framework/package/config guesses and direct write requests.
- **Điều kiện trước:** Target và Spec tồn tại; transport/logger/retry binding phải `APPROVED` trước remediation adapter-specific.
- **Evidence:** `ERROR HANDLING AUDIT REPORT`, typed-error boundary findings, profile evidence, exact verification result hoặc reason, recommendation pending.
- **Dừng khi:** Configuration gap, exposed PII/stack, behavior contract chưa được review hoặc write scope không có approved task grant.
- **Human quyết định:** Human duyệt error contract và remediation scope; approved code change chỉ đi qua `/add-execute`.
- **Lệnh tiếp theo:** `/sdd-update --feature=<slug> --artifact=spec --bump=patch --reason="Clarify error contract"` trước behavior change, sau đó dùng persisted `/add-execute` Follow-up.
- **Ví dụ:** `/error-handler-pattern --feature=feat-login --mode=scaffold` tạo mapping proposal, không tạo file handler.

## Completion output

Dùng [Completion output contract](../_shared/ai-review-protocol.md#completion-output-contract) sau `ERROR HANDLING AUDIT REPORT`. Nêu audit/scaffold mode, profile/binding, findings, verification evidence và Spec/Plan impact. Kết quả audit sạch không có action scope mới chọn `continue` với action không-command: giữ evidence và chỉ theo persisted feature/delivery Follow-up hiện có. Feature behavior change là `Human decision required` để `/sdd-update --artifact=spec ...` rồi review; `ENG-02` Constitution change route qua RFC. `CONFIGURATION GAP` hoặc unresolved `CRITICAL` là `BLOCKED`; không scaffold framework/logger/retry command suy đoán.