# Heuristic Tier 2 Doc Compression Implementation Handoff

## Status

- Date: 2026-05-19
- Source: User discussion in the current thread covering the HEURISTIC_SYSTEM
  design review and the agreed Tier 2 follow-up.
- Intended next step: Execute the sibling plan.
- Recommended plan: docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-plan.md
- Recommended execution state: docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-execution-state.md

## Purpose

Continue the doc compression started in Tier 1 (merged via PR #260) by
tightening the conceptual surface that an agent must absorb before retaining a
HEURISTIC_SYSTEM workflow lesson. Tier 2 focuses on three things: collapse the
inbox lifecycle from five states to three, make a single triage checklist the
source of truth, and stop describing the two activation paths as if they were
separate conceptual rails. This prepares the schema room needed by the later
folder-migration plan (`heuristic-case-folder-migration`).

## Confirmed Facts

- Tier 1 landed on `main@38e1cbd`. HEURISTIC_SYSTEM.md is 155 lines,
  `heuristic-system/README.md` is 25 lines, `heuristic-system/error-inbox/README.md`
  is 112 lines. Test-pinned phrases (triage checklist, lifecycle enum, entry
  template) remain intact.
- The current inbox lifecycle defines five states: `open`, `triaged`, `planned`,
  `promoted`, `wontfix`. Only one archived entry and one operation record exist
  in the repo. No entry has ever used `triaged` or `planned` distinctly from a
  PR/plan link in `Next Action`.
- The triage checklist is duplicated across three locations:
  `HEURISTIC_SYSTEM.md#activation-and-triage`,
  `heuristic-system/error-inbox/README.md#entry-criteria-summary`, and
  `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md#workflow`.
- Two activation paths (named-skill + observed-friction) share the same
  retention threshold. The conceptual split adds reader load without changing
  the actual decision.
- The deterministic helper at
  `skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py`
  exposes a `set-status` subcommand that accepts the full five-state enum;
  tests in
  `skills/workflows/heuristic-system/heuristic-error-inbox/tests/test_workflows_heuristic_system_heuristic_error_inbox.py`
  assert all five values.
- `tests/test_heuristic_system_docs.py` pins exact phrases for the triage
  checklist and the `- \`open\`: gap is known and not yet triaged.` line; the
  test must be updated in the same change as any doc/enum compression.

## Decisions

1. Collapse inbox lifecycle to three states: `open`, `promoted`, `wontfix`.
   Progress between `open` and `promoted` is represented by `Next Action` and
   linked plan / PR references, not by extra enum values.
2. Make `HEURISTIC_SYSTEM.md#activation-and-triage` the single triage
   checklist source of truth. Other locations cross-link to it instead of
   restating the criteria.
3. Reword the two activation paths into one decision ("did something fail or
   feel wrong?") while keeping the deterministic boundary that
   `skill-usage.record.v1` only fires inside a named skill workflow.
4. Migrate the one existing archived inbox entry from `triaged`/`planned`-era
   shape to the new three-state enum without losing audit history.
5. Keep all behaviour and CLI surface area intact except where the enum
   collapse requires; do not touch the redaction or storage model yet.
6. Land Tier 2 before any folder migration. Folder schema design needs the
   simplified lifecycle.

## Scope

- `HEURISTIC_SYSTEM.md`: rewrite the triage checklist as the single source,
  unify the activation language, and update the promotion ladder to refer to
  the three-state lifecycle.
- `heuristic-system/README.md`: keep cross-link only; remove any
  lifecycle-state listing.
- `heuristic-system/error-inbox/README.md`: collapse the lifecycle enum to
  three states, point all checklist references at HEURISTIC_SYSTEM.md, keep
  the entry template + archive section + cleanup rules.
- `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`:
  three-state lifecycle, cross-link the checklist.
- `skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py`:
  accept only `open|promoted|wontfix`. Existing entries with legacy values are
  read but cannot be re-set to a legacy value.
- `skills/workflows/heuristic-system/heuristic-error-inbox/tests/test_workflows_heuristic_system_heuristic_error_inbox.py`:
  update enum assertions; add a legacy-read compatibility test.
- `tests/test_heuristic_system_docs.py`: update pinned phrases to match new
  lifecycle list and single-checklist cross-link.
- Existing archived entry at
  `heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup.md`:
  retain as historical evidence; do not rewrite its lifecycle line.

## Non-Scope

- Folder layout migration for inbox or operation-record cases (covered by
  `heuristic-case-folder-migration`).
- Moving the helper to nils-cli (covered by `heuristic-inbox-cli-graduation`).
- Adding execution-log capture (lands with the CLI graduation).
- New helper subcommands; this plan only narrows existing surface.
- Any change to `skill-usage.record.v1` schema, `agent-out`, or
  `heuristic-system/operation-records/` layout.

## Requirements

- The collapsed lifecycle is the only one referenced by docs, SKILL.md, helper
  CLI surface, and tests after this plan.
- A reader can find the triage checklist once, in HEURISTIC_SYSTEM.md, and all
  other documents resolve it by cross-link.
- The helper rejects `triaged` and `planned` as new status writes but reads
  legacy values without error.
- Archived entries retain their historical lifecycle text and are not
  rewritten.
- `tests/test_heuristic_system_docs.py` continues to enforce the curated
  inbox/operation-record boundary.

## Acceptance Criteria

- `HEURISTIC_SYSTEM.md` lists exactly `open | promoted | wontfix` as the
  active lifecycle and contains the canonical triage checklist.
- `heuristic-system/error-inbox/README.md` does not duplicate the triage
  checklist; it links to HEURISTIC_SYSTEM.md.
- The helper's `set-status` CLI accepts only the three new values, errors on
  the legacy ones with a clear message, and reads legacy values from existing
  entries.
- Helper tests cover both the new enum and the legacy-read path.
- `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  passes.
- `scripts/check.sh --all` passes before reporting maintenance complete.

## Validation Plan

- `plan-tooling validate --file docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-plan.md`
- `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
- `scripts/check.sh --markdown`
- `scripts/check.sh --all`

## Risks And Guardrails

- Test-pinned phrases in `tests/test_heuristic_system_docs.py` are fragile to
  line-wrapping. Run targeted tests after each edit, not only at the end.
- Legacy-value backward compatibility must be read-only; allowing writes would
  defeat the collapse.
- Cross-document cross-links create breakage risk if anchor names change.
  Keep the anchor stable (`#activation-and-triage` and similar).
- The current archived entry uses an older shape; do not rewrite history.

## Execution

- Execution state recommendation: docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-execution-state.md
- Status: ready for sibling plan execution.
- Next-task source: docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-plan.md

## Retention Intent

This source document is a plan-created coordination artifact. Cleanup-eligible
after the lifecycle change is shipped and the durable docs reflect the new
shape.

## Open Questions

- None.

## Read-First References

- HEURISTIC_SYSTEM.md
- heuristic-system/README.md
- heuristic-system/error-inbox/README.md
- skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md
- skills/workflows/heuristic-system/heuristic-error-inbox/bin/heuristic_error_inbox.py
- skills/workflows/heuristic-system/heuristic-error-inbox/tests/test_workflows_heuristic_system_heuristic_error_inbox.py
- tests/test_heuristic_system_docs.py
- heuristic-system/error-inbox/archive/2026/deliver-gitlab-mr-skipped-pipeline-and-cleanup.md
- docs/plans/heuristic-system-retention-follow-up/heuristic-system-retention-follow-up-discussion-source.md
