# Observed Friction Trigger Implementation Handoff

## Status

- Date: 2026-05-19
- Source: User discussion in the current Codex thread.
- Intended next step: Execute the sibling plan.
- Recommended plan: docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md
- Recommended execution state: docs/plans/observed-friction-trigger/observed-friction-trigger-execution-state.md

## Purpose

Extend the HEURISTIC_SYSTEM retention model so agents can triage important
tooling friction observed during ordinary CLI, hook, validation, or workflow
execution, without requiring every useful lesson to start from a named skill
invocation.

## Confirmed Facts

- Current `skill-usage.record.v1` creation is gated by a named skill invocation,
  concrete workflow activity, and project permission to retain local evidence.
- Current HEURISTIC_SYSTEM guidance already distinguishes raw runtime evidence,
  curated `error-inbox/` entries, and promoted `operation-records/`.
- Codex hook support for skill usage recording is advisory only and must not
  auto-write records.
- The user agrees with a dual-trigger model: keep the named-skill trigger and add
  an observed-friction trigger for agent-visible tool or workflow pain.
- The example motivating this change is repeated `plan-tooling validate` friction:
  `--explain` did not help key error classes, source-doc label syntax was strict
  but underdocumented, dependency parsing rejected useful annotations, directory
  locations were rejected even when semantically accurate, and text output repeated
  related errors instead of grouping them.

## Decisions

1. Keep named skill usage as the strict trigger for `skill-usage.record.v1`.
2. Add an observed-friction triage path for non-skill or not-clearly-skill-bound
   CLI, hook, test, validation, dependency, and external service failures.
3. Do not make non-zero exit codes automatically durable records. Exit code,
   stderr, retry count, or workaround use should start judgment, not persistence.
4. Classify observed friction into three outcomes:
   - ignore: transient typo, wrong cwd, obvious authoring miss, or immediately
     fixed issue with no reusable lesson;
   - summarize: mention in final response or runtime evidence when useful but not
     worth a retained repo artifact;
   - retain or promote: preserve as issue, improvement source, error-inbox entry,
     test, script, runbook, skill policy, primitive change, or operation record.
5. Lower the retention threshold when friction occurs inside an active named skill
   workflow or directly contradicts a skill contract, because it may mean the
   skill boundary needs repair.
6. Keep raw logs and raw `skill-usage.record.json` files out of committed tracker
   artifacts by default.

## Scope

- Add HEURISTIC_SYSTEM guidance for observed-friction triage and promotion.
- Update skill usage recording guidance so skill-bound friction is captured in the
  existing `failures` model while non-skill friction follows triage first.
- Update heuristic-system README and error-inbox entry criteria so durable entries
  remain high-signal and do not become an exit-code log.
- Update narrow workflow skill docs only where they route inbox or skill-usage
  lifecycle decisions.
- Add or update focused text tests that protect the new boundaries.

## Non-Scope

- Do not implement automatic command-output scraping, shell hooks, or Codex hook
  auto-writing.
- Do not change the `skill-usage.record.v1` schema unless existing validation
  cannot express the required behavior.
- Do not implement the `plan-tooling` CLI improvements in this plan.
- Do not create a broad `heuristic-system-lifecycle` skill.
- Do not commit raw runtime records as durable trackers.

## Requirements

- HEURISTIC_SYSTEM must state that observed tool friction can be triaged even when
  no named skill was explicitly invoked.
- The policy must explicitly reject automatic durable record creation from
  `exit_code != 0` alone.
- The triage checklist must include repeated retries, documentation/behavior
  mismatch, unclear error output, semantic workaround, skill-contract relevance,
  and future-agent reuse value.
- Skill-bound friction must route to the existing `skill-usage` failure model when
  a `skill-usage.record.v1` record is already required.
- Unresolved important friction that should survive cleanup must route to
  `heuristic-system/error-inbox/`.
- Fixed, repeated, cross-skill, or audit-worthy friction may become tests,
  scripts, runbooks, skill policy, primitives, or operation records.
- The active inbox must remain curated and archiveable; this change must not
  lower the threshold so far that every transient CLI mistake becomes retained.

## Acceptance Criteria

- `HEURISTIC_SYSTEM.md` documents the dual trigger model and observed-friction
  triage outcomes.
- `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md` explains when observed
  friction belongs in a skill usage failure versus ordinary triage.
- `heuristic-system/README.md` and `heuristic-system/error-inbox/README.md`
  preserve the curated-record boundary and mention observed-friction retention
  criteria.
- `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md` routes
  implementation work outside the inbox workflow and avoids catch-all lifecycle
  expansion.
- `skills/tools/workflow-evidence/skill-usage/SKILL.md` keeps the CLI primitive as
  a record writer, not a policy engine.
- Focused tests fail if docs imply auto-writing records for every non-zero exit
  or if they remove the lower threshold for skill-contract friction.
- `plan-tooling validate` passes for the sibling plan.
- The smallest relevant docs/tests pass after implementation, and `scripts/check.sh
  --all` passes before reporting maintenance complete.

## Validation Plan

- `plan-tooling validate --file docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md`
- `scripts/check.sh --tests -- -k "heuristic_system or skill_usage"`
- `scripts/check.sh --markdown`
- `scripts/check.sh --docs`
- `scripts/check.sh --all`

## Risks And Guardrails

- Too much automation would turn HEURISTIC_SYSTEM into a noisy CLI failure log.
  Keep this as judgment-first triage unless repeated evidence justifies a helper.
- Too little guidance would keep useful tool pain trapped in one-off session
  summaries. Include enough checklist language for future agents to decide.
- Skill-bound friction can be under-recorded if the policy treats it like ordinary
  ad hoc CLI use. State the lower threshold clearly.
- The plan-tooling example is motivating evidence, not scope for this repo change.
  Actual nils-cli improvements should be planned or implemented separately.

## Execution

- Execution state recommendation: docs/plans/observed-friction-trigger/observed-friction-trigger-execution-state.md
- Status: ready for sibling plan execution.
- Next-task source: docs/plans/observed-friction-trigger/observed-friction-trigger-plan.md

## Retention Intent

This source document is a plan-created coordination artifact. It can be cleaned
up after the policy is implemented, tested, and either promoted into durable docs
or represented by the changed docs/tests themselves.

## Open Questions

- None. Implementation may still stop if the current worktree contains overlapping
  user-owned changes in the target docs or tests.

## Read-First References

- 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/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
