Prompt List Delegate Typing Cleanup Roadmap

# PromptManager Prompt-List Delegate Typing Cleanup Roadmap

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** Reduce mechanical strict-typing risk on the active retrieval/list seam by cleaning up `gui/prompt_list_delegate.py` first, with only the smallest necessary type-supporting touch in nearby list-model code.

**Architecture:** This roadmap stays on one bounded retrieval/list seam. It targets pyright-reported unknown and partially unknown types in `gui/prompt_list_delegate.py`, especially around `QModelIndex` access, preview/handoff cue extraction, and match-span coercion. The slice should stay mechanical: clarify types, narrow `None` handling, and reuse existing list-model contracts rather than changing retrieval behavior or adding new UI features.

**Tech Stack:** Python 3.13, PySide6 model/view seam, pyright, pytest, Ruff, PromptManager product docs under `docs/`.

Direction note: `docs/plans/2026-05-10-product-direction-ssot-next-cycle.md`
Canonical product SSOT: `docs/product-ssot.md`
Most recently delivered bounded ledger before this slice: `docs/plans/2026-05-10-prompt-chain-result-decision-clarity-roadmap.md`

---

## Why this roadmap exists

Confirmed from current repo state:
- `docs/plans/2026-05-10-product-direction-ssot-next-cycle.md` keeps Candidate 3 pending for active-seam typing cleanup.
- Candidate 3 boundaries explicitly say:
  - choose smallest bounded files first,
  - avoid broad repo churn,
  - prefer files on retrieval/detail/execution seams.
- A focused pyright audit on active seams showed `gui/prompt_list_delegate.py` as one of the smallest high-value files with concentrated strict-typing debt.
- The same audit showed larger debt in `gui/dialogs/prompt_chains.py`, but that file is broader and riskier for a first C3 slice.
- `gui/prompt_list_model.py` and the nearby list-side tests already exist, so the best next move is a bounded delegate-first typing cleanup rather than a bigger refactor.

So the next useful move is:

**active-seam typing cleanup -> retrieval/list delegate first**

---

## Scope guardrails

This roadmap may improve only:
- missing or unknown type annotations in `gui/prompt_list_delegate.py`,
- the smallest nearby type-supporting contract in `gui/prompt_list_model.py` if the delegate cannot be typed cleanly otherwise,
- focused tests / pyright verification for the list-side seam.

This roadmap must not introduce:
- retrieval ranking changes,
- search/result behavior changes,
- new list UI surfaces,
- broad typing churn across unrelated files,
- refactors whose main purpose is style rather than type-risk reduction.

---

## Confirmed baseline

Treat these as already delivered unless focused regression proves otherwise:
- prompt-list action clarity beyond title match is already shipped,
- prompt-list delegate already renders the bounded handoff cue row,
- prompt-list model/delegate tests already cover current retrieval cue behavior,
- prompt-detail and prompt-chain slices are delivered previous work and should not be reopened here.

Do not re-plan those as missing features.

---

## Main product question for this roadmap

> what is the smallest typing-cleanup slice that reduces mechanical risk on an active retrieval/list seam without changing retrieval behavior or opening a larger refactor?

Preferred answer shape:
- one bounded file first,
- one small pyright debt cluster,
- no behavior drift,
- nearby tests stay green.

---

## Stage A — Prompt-list delegate typing cleanup

### Task 1: Audit the prompt-list delegate typing seam

**Status:** completed

**Objective:** Confirm the smallest pyright debt cluster in `gui/prompt_list_delegate.py` and decide whether any nearby model contract must be typed alongside it.

**Files:**
- Inspect: `gui/prompt_list_delegate.py`
- Inspect: `gui/prompt_list_model.py`
- Inspect: `tests/test_prompt_list_model.py`
- Maintain: `docs/plans/2026-05-10-prompt-list-delegate-typing-cleanup-roadmap.md`

**Implemented:**
- confirmed the smallest bounded debt cluster sits in `gui/prompt_list_delegate.py`,
- classified the errors into four groups: missing index annotations, unknown `index.data(...)` values, `str | None` flow into string-only helpers, and tuple/span coercion ambiguity,
- confirmed `gui/prompt_list_model.py` only needs a minimal supporting parent-type annotation.

**Exit criterion:**
One bounded implementation plan for the delegate seam, plus a call on whether `gui/prompt_list_model.py` needs a minimal supporting type adjustment.

---

### Task 2: Reproduce the bounded pyright failure pack

**Status:** completed

**Objective:** Lock the typing debt with a focused pyright command before code changes.

**Files:**
- Verify: `gui/prompt_list_delegate.py`
- Maybe verify: `gui/prompt_list_model.py`

**Verification command:**