---
name: heuristic-error-inbox
description: Manage curated HEURISTIC_SYSTEM inbox and operation-record case folders through the nils-cli heuristic-inbox primitive with judgment-first workflow guidance.
---

# Heuristic Error Inbox

Use this skill when a curated HEURISTIC_SYSTEM workflow gap or operation-record
case should move through the retained case-folder lifecycle.

## Contract

Scope boundary:

- The skill body owns judgment ("should this be retained?", "what should
  `ENTRY.md` say?", "promote vs archive?").
- Deterministic operations route through the brew-installed `heuristic-inbox`
  primitive from nils-cli (folder ops, redaction guardrail, lifecycle
  transitions, archive moves, evidence ingest).

Prereqs:

- Target workspace is a git work tree with `heuristic-system/error-inbox/`
  (per-case folder layout: `<slug>/ENTRY.md` plus `<slug>/evidence/`).
- Required PATH usage: `heuristic-inbox` available on `PATH` from nils-cli
  0.10.2 or newer. Verify the actual binary with `heuristic-inbox --version`.
- Released boundary: Homebrew nils-cli 0.10.2 (or newer) ships the
  `heuristic-inbox` primitive. Install or upgrade with
  `brew tap sympoies/tap && brew install nils-cli` (or `brew upgrade nils-cli`).
- `skill-usage` is available when creating entries from a
  `skill-usage.record.json`; the record should already pass
  `skill-usage verify --out <record-dir> --format json`.
- Project preflight has passed before editing tracked inbox records.

Inputs:

- User request to create, verify, triage, route, update, or archive a curated
  HEURISTIC_SYSTEM error inbox entry.
- Optional observed-friction signal that has already passed judgment-first
  HEURISTIC_SYSTEM triage.
- Optional existing inbox case folder (or its `ENTRY.md` path) under
  `heuristic-system/error-inbox/`. Operation-record cases under
  `heuristic-system/operation-records/<slug>/RECORD.md` are accepted by
  `verify` only.
- Optional redacted evidence source file for
  `ingest-evidence <case> --from <path>`; the primitive rejects unredacted
  artifacts.
- Optional verified skill usage record directory for
  `new --from-skill-usage <record-dir>`.
- Optional lifecycle status: `open`, `promoted`, or `wontfix`. Legacy
  values (`triaged`, `planned`) on historical entries remain readable but
  cannot be re-set.
- Optional severity: `low`, `medium`, or `high`.
- Optional implementation plan, issue, PR/MR, operation record, or runbook link
  to preserve as lifecycle evidence.
- Optional archive reason, archive date, archive root, dry-run mode, or durable
  outcome link for completed entries.

Outputs:

- A concise recommendation about whether the gap warrants a retained inbox
  entry, duplicate update, plan routing, promotion, accepted-risk closure, or
  archive move.
- A curated case folder (`<slug>/ENTRY.md` plus an empty `evidence/`) under
  `heuristic-system/error-inbox/` when creation is appropriate.
- Deterministic CLI output for list, verify, new, set-status, ingest-evidence,
  and archive operations in text or JSON; JSON payloads use versioned schema
  values such as `cli.heuristic-inbox.verify.v1` inside a
  `{schema_version, command, ok, result}` envelope.
- Validation evidence from the CLI and project checks before claiming the
  lifecycle update is complete.
- Automatic execution logs for each write operation under the
  `agent-out project --topic heuristic-inbox` run directory, including
  `invocation.json`, `before.json`, and `after.json`.

Exit codes:

- `0`: success
- `1`: validation failure, duplicate entry detected, missing required entry
  content, or unsafe write target
- `2`: usage error

Failure modes:

- `heuristic-inbox` is unavailable on `PATH` or reports a version older than
  0.10.2; install or upgrade nils-cli before running the workflow.
- Requested entry would duplicate an existing slug, title, area, or evidence
  pointer; update the existing entry or ask the user before creating another.
- Entry lacks required sections, lifecycle status, severity, raw evidence
  pointer, workaround, promotion criteria, or next action.
- `skill-usage.record.json` is missing, malformed, unverified, or points to raw
  details that should stay linked rather than copied.
- Requested lifecycle status lacks a durable link or next action when the
  status is `promoted` or `wontfix`.
- Requested status write is a legacy lifecycle value (`triaged`, `planned`);
  use `open` plus a `Next Action` link to express triage or planned work.
- Archive is requested for a case that is not `promoted` or `wontfix`, still
  has actionable `Next Action` text, lacks a durable outcome link, or would
  overwrite an existing archived case folder.
- `ingest-evidence` is asked to write a raw `skill-usage.record.json`, a file
  matching token-like patterns, an oversize source, or content containing
  absolute `$HOME` paths that have not been rewritten to `<workspace>`.
- The user is actually asking to implement the underlying bug or tool fix; route
  that to `create-plan`, `execute-from-plan`, or the provider/domain skill
  instead of fixing it inside this inbox workflow.
- Ordinary command mistakes, single non-zero exits, or raw stderr dumps are
  mistakenly treated as retained inbox entries without observed-friction triage.

## Workflow

1. Decide whether a retained inbox entry is appropriate.
   - Run the canonical triage checklist in
     `HEURISTIC_SYSTEM.md#activation-and-triage`; this skill does not restate
     the criteria.
   - Use an entry when an important delivery, release, validation, evidence,
     or safety workflow gap remains unresolved.
   - Do not create an entry for a transient failure that was fixed immediately
     and covered by tests or an operation record.

2. Inspect the current inbox before writing.
   - Run:

     ```bash
     heuristic-inbox list
     ```

   - Check for likely duplicates by slug, title, area, and evidence pointer.

3. Create or update one curated case.
   - From a verified `skill-usage` record:

     ```bash
     heuristic-inbox new --from-skill-usage <record-dir> --slug <slug>
     ```

     The primitive writes `<inbox>/<slug>/ENTRY.md` and an empty
     `<inbox>/<slug>/evidence/` folder.
   - When no `skill-usage` record exists, hand-author the case from scratch
     against the canonical template below. The primitive's `new` path
     requires `--from-skill-usage`, so hand-authoring is judgment-owned and
     must close with the `heuristic-inbox verify` gate before the case is
     committed or routed.

     1. Create the case folder layout:

        ```bash
        mkdir -p heuristic-system/error-inbox/<slug>/evidence
        ```

     2. Write `heuristic-system/error-inbox/<slug>/ENTRY.md` using the
        canonical schema (replace bracketed placeholders, keep section
        order; lifecycle status starts at `open`):

        ```markdown
        # [Title]

        ## Status

        - Status: open
        - First observed: YYYY-MM-DD
        - Area: [domain or skill name]
        - Severity: low | medium | high

        ## Signal

        [One short paragraph describing the observed workflow gap.]

        ## Evidence

        - [Redacted artifact link or external record pointer.]

        ## Impact

        [What this gap blocks, weakens, or risks if left unresolved.]

        ## Current Workaround

        [Workaround in use today, or `None.` if none.]

        ## Promotion Criteria

        [Concrete signal that proves this gap is closed enough to promote.]

        ## Next Action

        [Single actionable next step; never leave blank.]
        ```

     3. Run the verify gate before committing or routing:

        ```bash
        heuristic-inbox verify heuristic-system/error-inbox/<slug>/ --strict
        ```

        Fix any issues the primitive reports (missing sections, raw
        `$HOME` paths under `evidence/`, lifecycle inconsistencies) before
        the case is treated as live.
   - For existing cases, edit `ENTRY.md` only as needed or use
     `set-status` for lifecycle status changes.
   - Link raw records and summarize the failure; never copy raw logs, secrets,
     credentials, or terminal dumps into the committed case. Add redacted
     artifacts through `ingest-evidence` so the primitive enforces the
     redaction guardrail.

     ```bash
     heuristic-inbox ingest-evidence heuristic-system/error-inbox/<slug>/ \
       --from <curated-excerpt.md> --label <name>
     ```

4. Verify before routing or reporting completion.
   - Run:

     ```bash
     heuristic-inbox verify heuristic-system/error-inbox/<slug>/ --strict
     ```

     The primitive accepts either the case folder or its `ENTRY.md` /
     `RECORD.md` path, and runs the redaction guardrail against every file
     under `<slug>/evidence/`. With nils-cli 0.10.2 or newer, strict verify
     also fails absolute `$HOME` paths in `ENTRY.md` / `RECORD.md` body text;
     non-strict verify reports those body findings as warnings for historical
     compatibility.
   - For lifecycle status changes, preserve a concrete next action or durable
     outcome link.

5. Archive completed cases out of the active inbox.
   - Closed cases keep status `promoted` or `wontfix`; do not add an
     `archived` lifecycle status.
   - Before archiving, verify that `Next Action` starts with `None.`, durable
     outcome evidence exists, and future follow-up has moved to a separate issue,
     plan, or source document.
   - Use dry-run first when reviewing an existing case:

     ```bash
     heuristic-inbox archive heuristic-system/error-inbox/<slug>/ --dry-run --format json
     ```

     `archive` moves the entire case folder (ENTRY.md plus any redacted
     `evidence/`). Bare `git mv` on a single file is discouraged because it
     skips the primitive's verify gate.

6. Route implementation work outside this skill.
   - Use `create-plan` or `execute-from-plan` for planned fixes.
   - Use provider-specific PR/MR/release skills for delivery failures.
   - Promote fixed and validated lessons into operation records, tests, scripts,
     runbooks, or skill policy before marking an entry `promoted`.

## Command Surface

```bash
heuristic-inbox list [--inbox-dir <dir>] [--status <csv>] [--include-archived] [--format text|json]
heuristic-inbox verify <case-folder|ENTRY.md|RECORD.md> [--inbox-dir <dir>] [--strict] [--format text|json]
heuristic-inbox new --from-skill-usage <record-dir> --slug <slug> [--out-dir <dir>] [--severity low|medium|high] [--format text|json]
heuristic-inbox set-status <case-folder|ENTRY.md> --status open|promoted|wontfix [--link <path-or-url>] [--format text|json]
heuristic-inbox ingest-evidence <case-folder|ENTRY.md> --from <path> [--label <name>] [--suffix <ext>] [--max-bytes <n>] [--force] [--format text|json]
heuristic-inbox archive <case-folder|ENTRY.md> [--link <path-or-url>] [--reason <text>] [--archive-root <dir>] [--date YYYY-MM-DD] [--dry-run] [--format text|json]
```

## Relationship To Later Skills

- `heuristic-operation-record` should be added only after promoted inbox entries
  prove operation-record creation is too large for this inbox primitive.
- `heuristic-compression-review` should be added only after several related
  archived inbox or operation records exist in one workflow family.
- Do not add a broad `heuristic-system-lifecycle` skill until the narrower
  inbox, operation-record, and compression workflows are stable.
