decision-hold-lifecycle

Decision Hold Lifecycle

Every unresolved decision that belongs to the user and is discovered while producing work must become a structured hold item before that work may be treated as complete.

Why

Decisions evaporate between sessions. Compaction wipes them. Context resets lose them. The audit (Jul 2026) found that focus-loss often starts with an unresolved decision that was never persisted — the model moved on, the user never saw it, and the work proceeded on an assumption.

This skill is the structural fix: decisions get persisted to disk, not held in context.

What it does

1. Inventory. When you discover an unresolved choice that requires the user, give it a stable key (a short slug), a title, a reason, and the repository/project path.

2. Hold. Write it to ~/.pi/agent/decisions.json:

   [
     {
       "key": "pagination-cursor-vs-offset",
       "title": "Cursor-based or offset-based pagination?",
       "reason": "Cursor is more performant for large datasets but breaks skip-to-page UX",
       "project": "/Users/rom.iluz/Dev/SDR-AI",
       "createdAt": "2026-07-20T...",
       "resolved": false
     }
   ]
   

3. Surface. The /bearings command reads this file and shows open decisions in the "Your Call" section. The user sees them on their next status check.

4. Resolve. When the user decides, mark resolved: true and record their answer in a resolution field. Dependent work can proceed.

Rules

• Only genuine unresolved choices that require the user create holds.
• Resolved findings, recommendations that need no user choice, and prose that merely sounds decision-like do NOT create holds.
• A hold remains open until the user's answer is durably recorded — not until the originating task completes.
• Do not close a hold merely because the task completed, the session ended, or compaction fired.
• Use the same key on retry so registration is idempotent.