triage-lessons

name	triage-lessons
description	Triage UX-log entries marked downstream_target=LL into formal lessons-learned.md entries with verifiable enforcement layer citations per LL-33 protocol. Operates on notes/ux-log-*.csv rows; outputs LL-NN entries + Priority Queue updates + bidirectional cross-references. Triggers: triage lessons, promote UX-log to LL, codify lesson, LL promotion, run lesson triage.
argument-hint	Optional: filter to specific tracker ID (e.g., 'UXL-042') or 'all-pending'
allowed-tools	Read, Edit, Write, Grep, Glob

Triage Lessons (LL Promotion Protocol)

Purpose

Promote UX-log tracker rows (notes/ux-log-*.csv) marked downstream_target=LL into formal lessons-learned.md entries. Operates as the operational layer for LL-33 (verification protocol for INTEGRATED classifications) — every promotion enforces the verification-citation discipline at write-time, preventing the drift surfaced in Session 43 (LL-30 missing from Priority Queue + claimed-but-unwoven INTEGRATED state).

When to Invoke

• After accumulating ≥3 UX-log rows with downstream_target=LL
• At session-close when a notable architectural learning emerged that warrants cross-session persistence
• Before publishing a CAB version (hygiene pass on lessons-learned.md)
• Reactively when a recurrence happens that should have been prevented by an existing LL — surfaces gap between claimed and actual integration

Protocol

Step 1: Discover Pending Rows

# Find UX-log rows tagged for LL promotion
grep -h "downstream_target=LL\|downstream_target,LL" notes/ux-log-*.csv 2>/dev/null

Filter by $ARGUMENTS if provided (specific tracker ID or all-pending).

For each pending row, extract:

Field	Use
id	UXL-NNN reference (origin pointer in LL detail)
surface	which CC component or workflow surfaced the issue
framework_anchor	which prioritization framework applies (RICE/Kano/etc.)
value, effort, severity	log-time prioritization signals
kano, rice_score, moscow	triage-time signals
evidence_path	concrete artifact backing the lesson
orchestrator_take	analyst's running interpretation

Step 2: LL Classification (per LL-33 protocol)

For each row, decide Class + Pri using the verification-required rubric:

Class	Pri	Decision criteria
INTEGRATED	—	(LL-33) Lesson is structurally woven via specific files/lines/rules. MUST cite: (a) enforcement layer files with line refs, (b) runnable verification command (grep/script), (c) recurrence test (known-bad input that the gate blocks). If you can't cite all three, the lesson is NOT integrated yet — classify as ACTIVE.
ACTIVE	P0	Load-bearing constraint NOT yet structurally woven; recurrence imminent or recently observed. Integration urgency = block on lack of integration this iteration.
ACTIVE	P1	Load-bearing but failure mode currently contained; integrate this quarter.
ACTIVE	P2	Nice to have; clean integration would be valuable but no urgency.
ADVISORY	—	Heuristic / wisdom; useful to know, no enforcement gate needed or feasible.
ARCHIVED	—	Superseded by later lesson, fixed by structural change, or no longer applicable.

Hard gate (LL-33): do NOT classify as INTEGRATED unless the verification triple (files+lines, runnable command, recurrence test) is concrete and fits in the LL detail. "Documented in skill X" is NOT sufficient — cite the specific section/lines AND the grep that confirms presence.

Step 3: Draft LL Detail

Required structure (per notes/lessons-learned.md schema):

| LL-NN | YYYY-MM-DD | <ops|arch|ctx|proc|tool> | <Class> | <Pri|—> | <one-line lesson> | <detail> |

Detail template:

**Why**: [root cause + recurrence pattern]
**Integration hook(s)**: [file:line citations + grep/script verification command]
**Recurrence test**: [known-bad input that the gate(s) block; OR "manual visual scan against <criterion>"]
**Provenance**: UXL-<NNN> [origin row reference] + [artifact paths]
**Reinforces / Supersedes**: [related LL refs]
**Woven via**: [enforcement layers list]

Step 4: Insert into lessons-learned.md

1. Determine next LL-NN (LL-32 was last as of 2026-05-05; check grep -E "^\| LL-[0-9]+" notes/lessons-learned.md | sort -t- -k2 -n | tail -1).
2. Insert row in the appropriate Class section (INTEGRATED / ACTIVE-P0 / ACTIVE-P1 / ACTIVE-P2 / ADVISORY) in ID-ascending order.
3. If ACTIVE, ALSO add Priority Queue table row at top of file.
4. Verify ID-ordering invariant within section.

Step 5: Bidirectional Cross-Reference

Per .claude/rules/kb-conventions.md "LL ↔ tracker cross-reference convention":

1. In LL detail: cite UXL-NNN (origin row) in Provenance section ✓ done in Step 3
2. In tracker row: append → LL-NN to the row's orchestrator_take field. Edit the CSV file to update the specific row.

Step 6: Verify

# 1. Confirm new LL entry present
grep -n "^| LL-NN |" notes/lessons-learned.md

# 2. If INTEGRATED, run the verification command from the entry's detail
# (the entry MUST include a runnable command per LL-33)
<paste verification command from the LL detail>

# 3. Confirm bidirectional cross-ref
grep "→ LL-NN" notes/ux-log-*.csv

# 4. If ACTIVE, confirm Priority Queue row added
grep "^| \\*\\*LL-NN\\*\\*" notes/lessons-learned.md

If verification fails on any step, correct before considering the promotion complete.

LL-33 Protocol (Verification Discipline)

The decisive innovation this skill enforces:

An INTEGRATED classification is a falsifiable claim, not narrative assertion. Every INTEGRATED entry must include a runnable verification command that can be executed independently to confirm the claimed enforcement actually enforces.

Empirical motivation (Session 43 + 44 evidence):

• Session 43 discovered LL-30 was claimed INTEGRATED in some surfaces but was actually ACTIVE-P0 with rubric-deep gaps (consumer-skill polish pending in Phase 2E.5+)
• Session 43 also discovered LL-30 was missing from Priority Queue table despite being ACTIVE-P0 — no automated cross-check between TODO claims and lessons-learned content
• Session 44's LL-30 + LL-32 promotion to INTEGRATED required authoring rubric-deep cross-refs first, THEN promoting — verification BEFORE classification, not after

LL-33 codifies this discipline: classification follows verifiable enforcement, not the other way around.

Anti-Patterns

• Don't classify INTEGRATED based on intent. "We're going to wire this via skill X" → ACTIVE-P1 with skill X named as integration hook. INTEGRATED comes after the wiring lands AND has citation + verification.
• Don't bundle multiple unrelated lessons in one LL-NN. Each LL is one lesson with one (or one closely-related set of) enforcement layer(s).
• Don't skip Step 5 bidirectional cross-ref. The KB-graph reachability guarantee depends on both ends linking.
• Don't promote UXL rows that lack evidence_path. Without a concrete artifact, the lesson is folklore — keep it in tracker as ADVISORY-future until evidence lands.

Integration Points

• notes/lessons-learned.md — destination + classification schema
• notes/ux-log-*.csv — origin (rows with downstream_target=LL)
• .claude/rules/kb-conventions.md — LL ↔ tracker cross-reference convention
• skills/audit-workspace/SKILL.md — eventual consumer (will gain lessons-learned-audit dimension cross-checking TODO claims vs LL entries vs Priority Queue, per LL-33 verification-protocol expansion)

Verification (this skill itself)

• Each promoted LL has Provenance UXL-NNN reference ✓ check via grep
• Each INTEGRATED LL has runnable verification command in detail ✓ check by parsing detail for code-fence bash blocks
• Tracker row's orchestrator_take ends with → LL-NN ✓ grep cross-ref
• Priority Queue row count matches ACTIVE-classified entry count ✓ grep + diff

See Also

• notes/lessons-learned.md LL-33 — the canonical LL entry codifying this protocol (entry created when this skill is first used; bootstrap via this skill's Step 4 against the LL-33 candidate detail in TODO.md)
• knowledge/reference/prioritization-frameworks.md — RICE / Kano / MoSCoW context for tracker-row prioritization signals
• notes/cab-philosophy-audit-playbook.md (GTA Iteration 1 reference artifact) — empirical validation that classification cycles benefit from explicit verification discipline (§lines 167-180 schema)