heuristic-error-inbox

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:

     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:

     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:

        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):

        # [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:

        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.

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

4. Verify before routing or reporting completion.

   • Run:

     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:

     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

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.