nba-table-promotion

name: nba-table-promotion description: Use when updating Next Best Actions prioritization table rows in whiteboards, plans, or design docs after resolving or deferring Q/H/A items - applies gold standard formatting (strikethrough for Answered/Confirmed/Resolved, italics for Deferred) with bold status, linked evidence anchors, and validates block anchors exist

Next Best Actions Table Promotion

Overview

Last Modified: 04/17/26 08:16:13

Deterministic formatting for resolved and deferred rows in the Next Best Actions prioritization table of whiteboards, plans, or design docs. Offloads all mechanical formatting to a co-located Python script; LLM decides only which rows are semantically "resolved" vs "deferred."

Two visual states are supported:

• Resolved (Answered / Confirmed / Resolved) → ~~strikethrough~~ + bold keyword
• Deferred → *italics* + bold keyword

Italics signal "not closed, just waiting" and visually distinguish deferred work from permanently resolved items at a glance.

When to Use

Last Modified: 04/17/26 08:16:13

• After updating an NBA table row's Status to Answered/Confirmed/Resolved → strikethrough path
• After updating an NBA table row's Status to Deferred → italic path
• After adding OBS/D evidence tags to the document body
• When reviewing a plan and noticing formatting inconsistency between resolved/deferred rows

Gold Standard Format

Open Row (no changes)

| 1 | [A-001](#^A-001) (concordance table) | High | Low | Agent + User | Open |

Resolved Row — Answered / Confirmed / Resolved (strikethrough path)

Last Modified: 04/17/26 08:16:39

| 3   | ~~[Q-001](#^Q-001) (STATUS vs EMPL_STATUS column)~~ | ~~High~~ | ~~Low~~ | ~~Agent~~ | **Answered** — [OBS-014](#^OBS-014), [D-003](#^D-003) |

Deferred Row (italic path)

Last Modified: 04/17/26 08:16:39

| 3   | *[H-001](#^H-001) (2k–5k token reload without evidence-map)* | *High* | *Med* | *Agent* | **Deferred** — pending [side-plan-slug](path/to/side-plan.md) (reason) |

Formatting Rules

Last Modified: 04/17/26 08:16:39

Shared rules (both paths):

1. Status cell keyword bolded: **Answered**, **Confirmed**, **Resolved**, or **Deferred**, followed by — and evidence or reason
2. Evidence links: [OBS-NNN](#^OBS-NNN) format — NOT plain text
3. Block anchors: every TAG-NNN referenced in the prioritization table MUST have a ^TAG-NNN block anchor in the document body, colocated in the same section as the [H]/[A] it resolves (not in a dedicated Evidence or Decisions section) — see evidence-dislocation anti-pattern in evidence-ontology
4. Column padding: # cell padded to 3 chars for visual alignment

Resolved path (Answered / Confirmed / Resolved): 5. Item / Utility / Cost / DRI cells: each wrapped in ~~strikethrough~~, preserving [TAG](#^TAG) links inside

Deferred path: 6. Item / Utility / Cost / DRI cells: each wrapped in *italics* (single asterisk), preserving [TAG](#^TAG) links inside. Do NOT use ** (bold) — italics uses single asterisk. 7. Status cell SHOULD link to the side-plan, sub-plan, or blocker that defines the deferral condition: **Deferred** — pending [slug](path) (reason)

Why italics for Deferred: strikethrough signals "done/removed" — applying it to deferred work misreads at a glance as resolved. Italics signals "open but waiting," visually distinct from both Open rows and Resolved rows.

Workflow

Step 1: LLM Semantic Check (your job)

Last Modified: 04/17/26 08:17:17

Classify each row's Status as one of:

• Resolved path → keyword "Answered", "Confirmed", or "Resolved" (e.g., "Answered — OBS-014", "Confirmed — see D-003", "Resolved")
• Deferred path → keyword "Deferred" (e.g., Deferred — pending [side-plan](path))
• Open path → anything else ("Open", "Pending user", blank)

Before running the script, for each resolved row:

1. Find the source [H-NNN]/[A-NNN] being resolved
2. Verify linked [OBS-NNN]/[D-NNN] anchors are in the same section as the source
3. If not: relocate the anchor blocks under the source [H]/[A] FIRST, then run the script

For each deferred row:

1. Verify the Status cell contains a link to the side-plan, sub-plan, or blocker defining the deferral condition
2. If the deferral reason is unclear, add a parenthetical: (no observability tooling), (pending upstream fix), etc.

The script validates anchor existence but is location-agnostic by design — spatial colocation is the LLM's responsibility.

Step 2: Run the Script (deterministic)

# Dry run — show what would change
python3 .claude/skills/nba-table-promotion/scripts/nba-format-promote.py <whiteboard.md> --dry-run

# Apply fixes
python3 .claude/skills/nba-table-promotion/scripts/nba-format-promote.py <whiteboard.md>

# JSON output (for programmatic use)
python3 .claude/skills/nba-table-promotion/scripts/nba-format-promote.py <whiteboard.md> --json --dry-run

Step 3: Verify (loop safety net)

Re-run with --dry-run. If output says "All rows match gold standard" → done. If not → script applies fixes → re-run check.

Exit codes:

• 0 — all formatted correctly
• 1 — missing block anchors (fix body first, then re-run)
• 2 — file not found or parse error

Common Mistakes

Last Modified: 04/17/26 08:17:30

Process Tree

↺(×(pass, →(fix)))

• Script checks formatting → if gold standard met: pass (exit loop)
• If not: script applies fixes → loop back to check