Priority Review

Refresh the priority signals table for a workflow state — metadata from the Shortcut API, judgment signals from sonnet classification of card descriptions. Display the comparison table at the end. The table is the artifact; the skill is the refresh workflow that keeps it current.

Constraints

• Classification model: Use claude-sonnet-4-6 for agent classification. Bake-off showed haiku gets counts right but misclassifies evidence_type; sonnet and opus are equivalent on judgment, sonnet is cheaper.
• Subagents are classifiers, not summarizers. They return structured JSON. Review evidence_type assignments if any look wrong — sonnet is good but not perfect.
• Incremental by default. Only re-classify cards whose updated_at has changed since last classification. Use --force flags when a full refresh is needed.
• No mutations. This skill reads Shortcut cards and writes to the local PostgreSQL priority_signals table. It does not modify Shortcut.

Steps

0. Preflight: reconcile live board with DB

Before refreshing anything, check for cards in the DB that have moved out of the target state since the last run.

1. Fetch live card IDs from Shortcut for the target state:

   bash
   1python3 box/shortcut-cards.py --state "Ready to Build" --ids-only

   If --ids-only isn't available, use --summary and extract IDs.

2. Query the DB for card IDs currently stored with that state:

   bash
   1psql postgresql://localhost:5432/feedforward -t -A \
   2  -c "SELECT card_id FROM priority_signals WHERE state = 'Ready to Build'"

3. Diff the two sets. Cards in the DB but not on the live board have moved. For each moved card, re-extract to update its state in the DB:

   bash
   1python3 box/priority-signals.py extract --id <comma-separated-moved-ids>

   Report what moved and where (the extract updates the state field).

4. Cards on the live board but not in the DB are new — they'll be picked up by the extract in Step 1.

This prevents stale cards from appearing in the signals table or framework ranking. Skip this step only if running with --force on a fresh DB.

1. Refresh metadata from Shortcut API

bash
1python3 box/priority-signals.py extract --state "Ready to Build"

This updates board position, state, product area, feature area users, and dates. Incremental: skips cards whose updated_at hasn't changed.

2. Check what needs classification

bash
1python3 box/priority-signals.py classify --state "Ready to Build" > /tmp/ff-$AGENTERMINAL_SESSION_ID/classify.json

Outputs card descriptions as JSON for cards that either:

• Have never been classified
• Have been updated in Shortcut since last classification

If the count is 0, skip to Step 5.

3. Delegate classification to sonnet agents

Split the classify output into batches of ~16 cards. Delegate each batch to agenterminal.delegate with model: "claude-sonnet-4-6".

The classification prompt for each batch:

You are classifying Shortcut card descriptions for priority signal extraction.
Read each card description and return structured classification data.

The cards are in {BATCH_FILE}. Read this file, then for each card extract:

1. intercom_conversations: Total count of Intercom conversations referenced.
   Count BOTH linked conversations AND stated totals (e.g. "31 conversations").
   Use the stated total when available. Return 0 if no Intercom evidence.

2. failure_volume_weekly: For bug cards, the headline weekly failure volume.
   If sub-categories are broken down, report the headline total, NOT the sum
   of sub-breakdowns. Return null for non-bug cards.

3. has_revenue_signal: true if evidence mentions cancellations, refunds, users
   leaving, declining to subscribe. Polite requests without leaving signals = false.

4. evidence_type: One of:
   - "direct_customer_pain" — Intercom conversations show real users affected
   - "internal_metric" — evidence from internal dashboards, not customer reports
   - "speculative" — no evidence of current customer impact
   - "mixed" — combination of customer and internal evidence
   - "implementation_step" — sub-task of a larger initiative

5. sentiment: "high" | "medium" | "low" | "none"

6. notes: One sentence on the most important thing the numbers don't convey.

Return ONLY valid JSON:
{"classifications": [{"card_id": N, ...}, ...]}

Collect all batches in parallel.

4. Import classification results

Merge all batch results into a single JSON file, then:

bash
1python3 box/priority-signals.py import-classifications /tmp/ff-$AGENTERMINAL_SESSION_ID/results.json

5. Display the table

bash
1python3 box/priority-signals.py show --state "Ready to Build"

This is the deliverable. Sorted by board position, showing all priority signals in a scannable comparison format.

6. Score unscored cards (default, skippable)

Run gaps to find cards missing judgment scores:

bash
1python3 box/framework-rank.py gaps

If there are gaps, propose scores and apply them. If the user says to skip this step, go directly to Step 7 — mispriority will run on scored cards only.

Scoring rules:

• Features need an Impact score (1-10). "How much would this move the needle if shipped?" Informed by revenue potential, retention effect, strategic value. This is product judgment, not mechanical.
• Bugs need a Severity score (1-5):
  • 5 = Financial harm / data loss / security
  • 4 = Feature broken / workflow blocked
  • 3 = Degraded experience / workaround exists
  • 2 = Cosmetic / misleading display
  • 1 = Edge case / negligible

Process:

1. Read the classification data (D×C partial scores, evidence_type, notes) from the gaps output.
2. For each unscored card, propose an Impact or Severity score with a one-line rationale. Use the card description and classification notes — don't infer from titles alone.
3. Present the full batch of proposed scores to the user for review. The user may adjust individual scores or approve the batch.
4. Apply approved scores:

   bash
   1python3 box/framework-rank.py score SC-NNN --impact N    # features
   2python3 box/framework-rank.py score SC-NNN --severity N   # bugs

If the batch is large (>10 cards), split into groups by product area for easier review. Don't score infra-track cards (chores, implementation_step) — they are capacity-allocated, not DIC-ranked.

7. Framework ranking comparison

bash
1python3 box/framework-rank.py mispriority -n 20

Compares framework rank (by DIC score) against live board position. Positive gap = board has the card lower than the framework thinks it should be (underprioritized). Only includes scored cards — unscored cards from skipped Step 6 will not appear.

Adapting to other states

The default is "Ready to Build" but the same workflow works for any single state. Replace --state "Ready to Build" with the target state in all commands. The show command without --state displays all non-released cards.