# Plan: Observed Friction Trigger

## Overview

Add a second HEURISTIC_SYSTEM activation path for observed tool and workflow
friction while preserving the existing named-skill `skill-usage` trigger. The
change is policy-first and docs/test backed: agents should triage repeated or
contract-relevant CLI, hook, validation, and workaround pain without turning every
non-zero exit into a durable record.

## Read First

- Primary source: `docs/plans/observed-friction-trigger/observed-friction-trigger-discussion-source.md`
- Source type: discussion-to-implementation-doc
- Open questions carried into execution: none

## Execution

- Execution state: `docs/plans/observed-friction-trigger/observed-friction-trigger-execution-state.md`

## Scope

- In scope:
  - `HEURISTIC_SYSTEM.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `heuristic-system/README.md`
  - `heuristic-system/error-inbox/README.md`
  - `skills/workflows/heuristic-system/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `skills/tools/workflow-evidence/skill-usage/SKILL.md`
  - Focused docs/text tests for HEURISTIC_SYSTEM and skill-usage boundaries.
- Out of scope:
  - `plan-tooling` CLI implementation changes.
  - Automatic command-output scraping or new Codex hook auto-writing behavior.
  - `skill-usage.record.v1` schema migration unless implementation discovers an
    unavoidable validation gap.
  - A broad `heuristic-system-lifecycle` skill.
  - Commit, push, or PR delivery.

## Assumptions

1. This is a docs and text-test policy change unless existing tests reveal a
   small local validator expectation that must be adjusted.
2. The observed-friction trigger is judgment-first. It may suggest retention, but
   it does not itself write records.
3. Existing `skill-usage` failure fields are sufficient for skill-bound friction.
4. Current active inbox/archive semantics stay unchanged.

## Sprint 1: Define The Dual Trigger Policy

**Goal**: Add the observed-friction trigger and triage checklist to the
HEURISTIC_SYSTEM docs while keeping retained records curated.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k heuristic_system`
  - `scripts/check.sh --markdown`
- Verify:
  - Docs state both named-skill and observed-friction triggers.
  - Docs reject automatic durable records from non-zero exit alone.
  - Inbox and operation-record promotion thresholds stay high-signal.

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

### Task 1.1: Add observed-friction guidance to HEURISTIC_SYSTEM

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Add a concise section that defines observed friction as
  repeated or contract-relevant pain from CLI, hook, test, validation,
  dependency, or external-service use. Define triage outcomes: ignore, summarize,
  retain/promote.
- **Dependencies**:
  - none
- **Complexity**: 3
- **Acceptance criteria**:
  - `HEURISTIC_SYSTEM.md` states named-skill usage remains the strict
    `skill-usage` trigger.
  - `HEURISTIC_SYSTEM.md` states observed friction can start triage even without
    a named skill.
  - The checklist covers repeated retries, docs/behavior mismatch, unclear error
    output, semantic workaround, skill-contract relevance, and future-agent reuse
    value.
  - The text says `exit_code != 0` alone is not enough for a durable record.
  - Tests assert the new trigger and anti-noise boundary.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 1.2: Update retained-record routing docs

- **Location**:
  - `heuristic-system/README.md`
  - `heuristic-system/error-inbox/README.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Update the retained-record flow and inbox entry criteria so
  observed friction can be routed to `error-inbox/` only when it is important,
  unresolved, and worth preserving after cleanup.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 3
- **Acceptance criteria**:
  - Retention flow names observed-friction triage before durable promotion.
  - Error-inbox criteria include important unresolved observed friction.
  - Error-inbox docs still say it is not a raw log archive.
  - Completed entries still use `promoted` or `wontfix` plus archive location,
    not a new lifecycle status.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 1.3: Preserve narrow heuristic workflow skill boundaries

- **Location**:
  - `skills/workflows/heuristic-system/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Clarify that the inbox skill can create, verify, update, and
  archive curated observed-friction entries, but implementation work and broad
  lifecycle automation remain outside that skill.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 2
- **Acceptance criteria**:
  - `heuristic-error-inbox` can handle curated observed-friction entries.
  - The skill still routes actual bug fixes to planning, provider, or domain
    workflows.
  - Docs continue to discourage a broad `heuristic-system-lifecycle` skill.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

## Sprint 2: Integrate Skill-Bound Friction Recording

**Goal**: Make skill-bound friction use the existing skill-usage failure model
while non-skill friction follows triage before retention.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k "heuristic_system or skill_usage"`
  - `scripts/check.sh --markdown`
- Verify:
  - Skill-bound friction has a lower retention threshold.
  - The `skill-usage` CLI remains a deterministic writer, not a policy engine.

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

### Task 2.1: Update skill usage runbook boundaries

- **Location**:
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `tests/test_heuristic_system_docs.py`
  - `tests/test_skill_usage_record_validator.py`
- **Description**: Document how observed friction maps to `skill-usage` only
  when it happens inside a named skill workflow that already requires a usage
  record. Keep non-skill friction outside the `skill-usage.record.v1` envelope
  unless it is later routed to a curated artifact.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Runbook says skill-bound command/script/dependency failures belong in
    `failures` when a skill usage record is required.
  - Runbook says non-skill observed friction should be triaged first and not
    forced into `skill-usage.record.v1`.
  - Existing failure classifications remain sufficient or any required change is
    explicitly justified.
  - Tests guard the skill-bound versus non-skill boundary.
- **Validation**:
  - `scripts/check.sh --tests -- -k "heuristic_system or skill_usage"`

### Task 2.2: Keep the skill-usage primitive policy-free

- **Location**:
  - `skills/tools/workflow-evidence/skill-usage/SKILL.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Update the skill-usage tool skill to state that the CLI writes
  and verifies records, while observed-friction triage and promotion decisions
  stay in HEURISTIC_SYSTEM docs and calling workflow skills.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 2
- **Acceptance criteria**:
  - The tool skill does not claim to detect or classify every command failure.
  - The tool skill links responsibility back to the calling workflow and
    HEURISTIC_SYSTEM policy.
  - Tests fail if the primitive is described as an automatic policy engine.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

### Task 2.3: Add an explicit motivating example without expanding scope

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `tests/test_heuristic_system_docs.py`
- **Description**: Include a compact example based on CLI validation friction,
  such as repeated validator errors with unclear explanations, to show how the
  triage chooses ignore, summarize, retain, or promote. Keep actual
  `plan-tooling` changes out of scope.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 2
- **Acceptance criteria**:
  - Example explains why repeated validator UX pain may deserve an issue,
    improvement source, or tool fix.
  - Example does not instruct agents to commit raw stderr or raw runtime records.
  - Example does not turn ordinary authoring mistakes into retained artifacts.
- **Validation**:
  - `scripts/check.sh --tests -- -k heuristic_system`

## Sprint 3: Validate And Preserve Executability

**Goal**: Verify the policy change, this plan bundle, and the relevant docs gates
before reporting the plan implementation complete.
**Demo/Validation**:

- Command(s):
  - `plan-tooling validate --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md`
  - `plan-tooling to-json --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md --sprint 1`
  - `plan-tooling batches --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md --sprint 1`
  - `scripts/check.sh --tests -- -k "heuristic_system or skill_usage"`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --docs`
  - `scripts/check.sh --all`
- Verify:
  - Plan lint and focused tests pass.
  - Full repository gate passes before claiming maintenance complete.
  - Any future helper/hook work remains a separate follow-up unless repeated
    evidence justifies it.

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

### Task 3.1: Run focused validation and fix drift

- **Location**:
  - `HEURISTIC_SYSTEM.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `heuristic-system/README.md`
  - `heuristic-system/error-inbox/README.md`
  - `skills/workflows/heuristic-system/README.md`
  - `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`
  - `skills/tools/workflow-evidence/skill-usage/SKILL.md`
  - `tests/test_heuristic_system_docs.py`
  - `tests/test_skill_usage_record_validator.py`
- **Description**: Run targeted tests and docs checks, then fix any
  implementation drift that remains within the observed-friction policy scope.
- **Dependencies**:
  - Task 1.3
  - Task 2.3
- **Complexity**: 3
- **Acceptance criteria**:
  - Targeted heuristic-system and skill-usage tests pass.
  - Markdown and docs freshness checks pass.
  - No test change weakens existing archive or operation-record boundaries.
- **Validation**:
  - `scripts/check.sh --tests -- -k "heuristic_system or skill_usage"`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --docs`

### Task 3.2: Validate plan executability and grouping

- **Location**:
  - `docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md`
  - `docs/plans/observed-friction-trigger/observed-friction-trigger-discussion-source.md`
- **Description**: Validate the plan bundle and per-sprint grouping output with
  `plan-tooling`, keeping source and plan links machine-checkable.
- **Dependencies**:
  - Task 3.1
- **Complexity**: 2
- **Acceptance criteria**:
  - `plan-tooling validate` passes.
  - `to-json`, `batches`, and `split-prs` produce usable output for each sprint.
  - Source doc still includes stable `Recommended plan` and `Recommended
    execution state` labels.
- **Validation**:
  - `plan-tooling validate --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md`
  - `plan-tooling to-json --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md --sprint 1`
  - `plan-tooling to-json --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md --sprint 2`
  - `plan-tooling to-json --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md --sprint 3`

### Task 3.3: Run final repository gate and record follow-up boundary

- **Location**:
  - `docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md`
  - `docs/plans/observed-friction-trigger/observed-friction-trigger-discussion-source.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `HEURISTIC_SYSTEM.md`
- **Description**: Run the full maintenance gate. If repeated observed-friction
  records later prove a deterministic helper or hook is warranted, record that as
  a separate plan or issue instead of adding it opportunistically here.
- **Dependencies**:
  - Task 3.2
- **Complexity**: 2
- **Acceptance criteria**:
  - `scripts/check.sh --all` passes before reporting implementation complete.
  - Final report lists policy files changed and validation commands run.
  - Any helper/hook follow-up is explicitly out of scope or linked as a separate
    future artifact.
- **Validation**:
  - `scripts/check.sh --all`

## Testing Strategy

- Unit: focused text tests in `tests/test_heuristic_system_docs.py` and existing
  `tests/test_skill_usage_record_validator.py` coverage when validator behavior is
  touched.
- Integration: `scripts/check.sh --markdown`, `scripts/check.sh --docs`, and
  `plan-tooling validate` for the plan bundle.
- E2E/manual: not required; this is repository policy and docs/test behavior with
  no UI or browser-facing acceptance.

## Risks & gotchas

- Adding a broad observed-friction trigger can create noisy retained artifacts.
  Keep durable record creation behind explicit high-signal criteria.
- Treating every non-zero exit as important would recreate the same noise problem
  in a structured format. The policy must state that exit code starts triage, not
  persistence.
- Under-recording skill-adjacent failures would miss contract problems in the
  workflows agents rely on. Make skill-contract relevance a lower-threshold
  signal.
- The plan-tooling example can tempt implementation to drift into nils-cli feature
  work. Keep CLI changes out of this repo plan.
- Text tests can become brittle if they assert paragraphs instead of stable
  policy phrases. Prefer short contract strings.

## Rollback plan

- Revert the observed-friction additions from HEURISTIC_SYSTEM, skill-usage, and
  heuristic-system workflow docs.
- Revert the focused text-test assertions added for observed-friction policy.
- Keep the existing named-skill `skill-usage.record.v1`, error-inbox, archive, and
  operation-record semantics unchanged.
