Action Items redesign — spec + plan (clean title / description / relations)

[jordanrburger]

Action Items redesign — spec + plan for review (no code yet)

Origin: Slack thread with Adam (2026-07-07). The action items render as a wall of
run-on text — the "title" is a whole sentence stuffed with priority/status
emoji, machine ids ([#TAG], Linear PROJ-####, GitHub #7056, cross-ref
hashtags), dates and quotes; _italic_ markdown shows raw underscores.

This PR contains only the design spec and the implementation plan, pushed for
review before any code is written (per our review-first flow).

• Spec: docs/superpowers/specs/2026-07-09-action-items-redesign-design.md
• Plan: docs/superpowers/plans/2026-07-09-action-items-redesign.md

The approach (chosen from 3 options during brainstorming)

Convention + render — fix authoring at the source and redesign the app
render, with no parser / parser-corpus.json / checksum change (keeps
markdown canonical + hand-editable, avoids the 3-repo checksum dance). Both the
producer and the consumer change:

Engine track (scout-plugin, prompt only): the bold title becomes a short
imperative human phrase — no ids/status/emoji/dates/internal —; all detail
moves after the — (body) or into - Source:/- Context: sub-bullets;
priority is expressed by section placement, not an inline emoji.

App track (scout-app):

1. Fix InlineMarkdownText → .inlineOnlyPreservingWhitespace (+ no silent
   raw-markdown fallback) so _italic_ renders.
2. New TaskDisplayText display-only cleaner: strips emoji / [#TAG] / Linear
   ids (that have a chip) / cross-ref hashtags / _(carries…)_ markers, while
   keeping [[entity|Name]] wikilinks inline as clickable names. Separate
   from plainSubject/matchableSubject — the scoutctl write path is untouched.
3. TaskCardView collapsed = clean bold title + 2-line description teaser +
   relation chip row; #TAG hidden; priority = left stripe only. Expand reveals
   full body + comments + links + actions.
4. Clean titles applied to Board / Focus / Done / Digest too.

Key decisions to sanity-check

• ids out, names stay — machine keys become chips; human names stay inline.
• collapsed card = title + 2-line description + chips (urgent still
  auto-expands).
• Coverage guard — the cleaner only strips an id that has a chip to land in;
  anything else stays inline (never silently lost). Documented limitation:
  bare GitHub refs (#7056) aren't detected as deep links, so they have no chip
  and stay inline (clickable via GitHubRefLinkifier); chip-ifying them is a
  possible follow-up. The engine rule keeps them out of the title regardless.
• No migration — defensive cleaning fixes existing messy files immediately;
  the prompt fixes new files.

Sequencing

App track = one scout-app PR (this branch, once approved → code); engine track =
a separate scout-plugin PR. TDD, one commit per task.

Reviewers, please confirm

• Approach depth (convention+render vs a structured contract) is the right call.
• The "ids out, names stay" line — and the GitHub-bare-ref limitation — are
  acceptable.
• Nothing in scope should touch the parser/corpus/checksum (it doesn't).

🤖 Generated with Claude Code

[AdamVyborny]

I am not sure if this will work good enough. IIUC I would instead of stripping emojis and IDs generate the titles without them and adjust prompt to make them very human readeble and natural and pass IDs separetelly in different block...

[jordanrburger]

Yeah, you're right — stripping in the app is a band-aid. And the old-files argument doesn't really hold anyway, since open items get re-rendered every day when they carry forward. The prompt fix converges within a day on its own.

Reworking the spec now: clean titles generated from the start, IDs/relations passed in a separate block, and the app-side cleaner is gone completely. Archives just stay as-is.