# Plan: Heuristic Tier 2 Doc Compression

## Overview

Collapse the inbox lifecycle from five states to three, make
`HEURISTIC_SYSTEM.md#activation-and-triage` the single triage checklist source
of truth, and reword the dual activation paths into one decision while keeping
the deterministic `skill-usage.record.v1` boundary intact. Helper enum + tests
move with the docs in the same PR so the system stays consistent. Folder and
nils-cli graduations are intentionally out of scope and tracked in sibling
plans.

## Read First

- Primary source: `docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-discussion-source.md`
- Source type: discussion-to-implementation-doc
- Open questions carried into execution: none

## Execution

- Execution state: `docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-execution-state.md`

## Scope

- In scope:
  - `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`
- Out of scope:
  - Folder layout migration (separate plan: `heuristic-case-folder-migration`).
  - nils-cli graduation (separate plan: `heuristic-inbox-cli-graduation`).
  - Execution-log capture.
  - `skill-usage.record.v1` schema or `agent-out` changes.
  - Rewriting the existing archived entry's historical lifecycle text.
  - Commit, push, or PR delivery beyond what is required to land the plan.

## Assumptions

1. No new helper subcommands are required; the work narrows existing surface.
2. Legacy lifecycle values (`triaged`, `planned`) only need read-back
   compatibility, not write-back support.
3. The repo currently has 0 active inbox entries; lifecycle migration only
   affects future writes.

## Sprint 1: Collapse The Lifecycle Enum And Cross-Link The Triage Checklist

**Goal**: Land the three-state lifecycle, the single triage checklist, and the
unified activation language across docs + helper + tests in one consistent
change.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  - `scripts/check.sh --markdown`
- Verify:
  - Docs reference the same lifecycle and the same checklist source.
  - Helper accepts only `open|promoted|wontfix` for new status writes.
  - Legacy lifecycle reads still succeed.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 1.1: Update HEURISTIC_SYSTEM.md to own the triage checklist and new lifecycle

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Rewrite the activation section so the triage checklist is
  the canonical source. Replace the dual-trigger framing with a single
  triage decision and document that `skill-usage.record.v1` only fires inside
  a named skill workflow. Update any lifecycle list references to
  `open | promoted | wontfix`.
- **Dependencies**:
  - none
- **Complexity**: 3
- **Acceptance criteria**:
  - HEURISTIC_SYSTEM.md states the lifecycle as `open | promoted | wontfix`.
  - The triage checklist appears once in HEURISTIC_SYSTEM.md.
  - `tests/test_heuristic_system_docs.py` asserts the new lifecycle list and
    that the checklist anchor name is stable.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 1.2: Cross-link the checklist and update lifecycle from sibling docs

- **Location**:
  - `heuristic-system/README.md`
  - `heuristic-system/error-inbox/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Replace the duplicated triage checklist text in
  `error-inbox/README.md` and the inbox SKILL.md with a single cross-link to
  HEURISTIC_SYSTEM.md. Update the lifecycle list in both READMEs to the
  three-state enum. Keep entry template, archive section, and cleanup rules
  intact.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 3
- **Acceptance criteria**:
  - No sibling doc duplicates the full checklist.
  - Lifecycle list shows three states everywhere except the historical
    archived entry.
  - Existing test-pinned phrases — "Do not add archived as a lifecycle status"
    and the `open` lifecycle bullet — are either preserved or replaced via
    test updates within the same change.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 1.3: Narrow the helper enum and add legacy-read compatibility test

- **Location**:
  - `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`
- **Description**: Update the helper's status enum to
  `{open, promoted, wontfix}`. Reject `triaged` and `planned` on
  `set-status` with a clear message that points to the docs. Continue to
  return legacy values from `list` and `verify` without error so historical
  entries remain readable.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 4
- **Acceptance criteria**:
  - `set-status --status triaged` returns exit 1 with a message naming the
    new lifecycle.
  - `list` and `verify` succeed on an entry whose status is a legacy value.
  - Added test confirms legacy-read compatibility and new-write rejection.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_error_inbox`

## Sprint 2: Validate And Land

**Goal**: Run the full validation gate, confirm cross-document consistency,
and prepare the change for delivery.
**Demo/Validation**:

- Command(s):
  - `plan-tooling validate --file docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-plan.md`
  - `scripts/check.sh --all`
  - `scripts/check.sh --markdown`
- Verify:
  - All targeted tests pass.
  - Markdown lint is clean.
  - Full repo gate is green before reporting complete.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 2.1: Run targeted gates and fix drift

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `heuristic-system/error-inbox/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Run targeted heuristic-system and helper tests, fix any
  line-wrap regressions introduced during edits, and verify the cross-link
  anchor names are stable.
- **Dependencies**:
  - Task 1.3
- **Complexity**: 2
- **Acceptance criteria**:
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
    passes.
  - `scripts/check.sh --markdown` passes.
- **Validation**:
  - `scripts/check.sh --tests -- -k "heuristic_system or heuristic_error_inbox"`
  - `scripts/check.sh --markdown`

### Task 2.2: Run the full repo gate and prepare delivery

- **Location**:
  - `docs/plans/heuristic-tier2-doc-compression/heuristic-tier2-doc-compression-execution-state.md`
- **Description**: Run `scripts/check.sh --all`. Record validation evidence
  in the execution state file. Confirm no out-of-scope edits leaked in.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 2
- **Acceptance criteria**:
  - `scripts/check.sh --all` passes.
  - Execution state lists final commands and outcomes.
- **Validation**:
  - `scripts/check.sh --all`

## Testing Strategy

- Unit: focused tests in `tests/test_heuristic_system_docs.py` and
  `skills/workflows/heuristic-system/heuristic-error-inbox/tests/...`.
- Integration: `scripts/check.sh --markdown`, `scripts/check.sh --docs`,
  `plan-tooling validate` for this plan.
- E2E/manual: not required; docs + helper change with no UI surface.

## Risks & gotchas

- Test-pinned phrases break easily when lines re-wrap. Run targeted tests
  after every edit, not just at the end.
- Legacy-read compatibility must remain read-only; allowing writes would
  defeat the collapse and silently revive the old lifecycle.
- Cross-link anchors must stay stable; renaming a heading breaks every
  pointer.
- Out-of-scope drift into folder layout or CLI surface should be deflected to
  the sibling plans.

## Rollback plan

- Revert the helper enum narrowing first; legacy values become writable
  again.
- Revert the docs cross-link and reinstate the duplicated checklist text.
- Revert the lifecycle list change in the two READMEs and SKILL.md.
- Restore the previous test assertions; helper tests should be the last to
  flip.
