From 5ab9a806eb443976336879a553d01be5447d92ff Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 25 Jul 2026 18:12:38 +0200 Subject: [PATCH] session_autopsy: handled candidates leave the nudge; drop explain-diff MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per user verdicts: the ⚙ statusline glyph told them nothing (removed on the ~/.claude side; the plain-words SessionStart line is the channel) and explain-diff is not wanted at all (skill deleted there, verdict 'dropped'). The count now means 'significant AND not yet handled' — resolving a candidate visibly shrinks it (7 -> 4), and handled table rows stop re-suggesting a review. Co-Authored-By: Claude Fable 5 --- ...-autopsy-drop-explain-diff-2026-07-25.json | 35 +++++++++ python_pkg/session_autopsy/cli.py | 10 ++- python_pkg/session_autopsy/report.py | 72 +++++++++++++++++-- .../session_autopsy/tests/test_report.py | 23 ++++-- 4 files changed, 127 insertions(+), 13 deletions(-) create mode 100644 docs/superpowers/evidence/session-autopsy-drop-explain-diff-2026-07-25.json diff --git a/docs/superpowers/evidence/session-autopsy-drop-explain-diff-2026-07-25.json b/docs/superpowers/evidence/session-autopsy-drop-explain-diff-2026-07-25.json new file mode 100644 index 00000000..32561ec1 --- /dev/null +++ b/docs/superpowers/evidence/session-autopsy-drop-explain-diff-2026-07-25.json @@ -0,0 +1,35 @@ +{ + "intent": "Act on two direct user verdicts: the statusline glyph told them nothing (drop it — the plain-words SessionStart line is the surfacing channel), and explain-diff is not needed at all (drop the skill entirely, do not compile it). Additionally stop the nudge counting candidates that already have a verdict.", + "scope": [ + "python_pkg/session_autopsy/report.py (handled_ids; table marks handled rows; Reviewed section renders 'dropped'; write_report excludes handled from the count)", + "python_pkg/session_autopsy/cli.py (mark-reviewed uses the same handled filter)", + "python_pkg/session_autopsy/tests/test_report.py (updated + new assertions)", + "~/.claude side (committed separately in that repo): statusline badge removed, skills/explain-diff/ and scripts/explain_diff.sh deleted, finish skill/script references cleaned, compiled.json verdict 'dropped'.", + "Non-goal: existing docs/explanations galleries stay — they are inert committed docs." + ], + "changes": [ + "unreviewed_count now means 'significant AND not yet handled': candidates with any compiled.json verdict (compiled / keep-llm / dropped) leave the count, so resolving a candidate visibly shrinks the nudge (7 -> 4 on the real corpus).", + "The ranked table's action column shows 'already handled — see Reviewed/scoreboard' for such candidates instead of re-suggesting a review.", + "The Reviewed section renders dropped workflows as 'dropped (workflow removed)'." + ], + "verification": [ + { + "command": "python3 -m pytest python_pkg/session_autopsy/tests/ -q", + "result": "pass", + "evidence": "81 passed; report.py and cli.py at 100% branch." + }, + { + "command": "PYTHONPATH=~/testsAndMisc python3 -m python_pkg.session_autopsy report; jq . ~/.claude/autopsy/state.json; statusline pipe-test; start-hook pipe-test", + "result": "pass", + "evidence": "unreviewed_count 7 -> 4 (err-549ef470, crdt-sync-migration, design-audit, update-config); statusline renders '[Fable] ~' with no glyph; SessionStart hook still prints its unchanged plain-words line (hook text untouched, so the mutation gate is unaffected)." + } + ], + "risks": [ + "A candidate marked handled disappears from the nudge even if its compiled script later regresses; the scoreboard ('measure') is the instrument that would show that.", + "Historical explain-diff docs remain in repos but the tooling to regenerate their gallery index (build_index.py) was deleted with the skill." + ], + "rollback": [ + "Revert the three python files to restore counting of handled candidates.", + "The ~/.claude deletions are separate commits in that repo; git revert there restores the skill, template, and scripts." + ] +} diff --git a/python_pkg/session_autopsy/cli.py b/python_pkg/session_autopsy/cli.py index a3bfa964..975e691e 100644 --- a/python_pkg/session_autopsy/cli.py +++ b/python_pkg/session_autopsy/cli.py @@ -289,9 +289,13 @@ def cmd_report(args: argparse.Namespace) -> int: result = detectors.analyze(records, _now()) report.write_report(home, records, result, _now()) if args.mark_reviewed: - report.write_state( - home, report.significant_ids(result.candidates), _now(), mark_reviewed=True - ) + handled = report.handled_ids(report.load_compiled(home)) + pending = [ + cid + for cid in report.significant_ids(result.candidates) + if cid not in handled + ] + report.write_state(home, pending, _now(), mark_reviewed=True) _emit("report: all candidates marked reviewed") _emit(f"report: {len(result.candidates)} candidates → {home / report.REPORT_FILE}") return 0 diff --git a/python_pkg/session_autopsy/report.py b/python_pkg/session_autopsy/report.py index 2e2325fa..2a6ea8c0 100644 --- a/python_pkg/session_autopsy/report.py +++ b/python_pkg/session_autopsy/report.py @@ -43,6 +43,26 @@ def fmt_tokens(count: int) -> str: return str(count) +def handled_ids(compiled: list[dict[str, object]]) -> set[str]: + """Candidate ids that already have a verdict (compiled, keep-llm, dropped). + + A handled candidate never counts toward the unreviewed nudge and its + table row stops suggesting a review — its story lives in the Reviewed + section and the scoreboard instead. + + Args: + compiled: Entries from compiled.json. + + Returns: + The candidate ids with any recorded verdict. + """ + return { + str(entry.get("candidate_id")) + for entry in compiled + if entry.get("candidate_id") + } + + def significant_ids(candidates: list[Candidate]) -> list[str]: """Ids of the candidates big enough to surface in the badge. @@ -233,7 +253,8 @@ def render_report( Returns: The Markdown document. """ - parts = [_header(records, now), _candidate_table(result.candidates)] + handled = handled_ids(compiled) + parts = [_header(records, now), _candidate_table(result.candidates, handled)] parts.extend( _candidate_detail(candidate) for candidate in result.candidates[:DETAIL_TOP] ) @@ -272,11 +293,42 @@ def _header(records: list[SessionRecord], now: datetime) -> str: ) -def _candidate_table(candidates: list[Candidate]) -> str: +def _action_cell(cand: Candidate, handled: set[str]) -> str: + """The table's action column for one candidate. + + Args: + cand: The candidate. + handled: Ids with a recorded verdict. + + Returns: + The suggested action, or a pointer to where its verdict lives. + """ + if cand.id in handled: + return "already handled — see Reviewed/scoreboard" + return cand.action + + +def _verdict_label(entry: dict[str, object]) -> str: + """Human label for a reviewed entry's verdict. + + Args: + entry: A compiled.json entry. + + Returns: + ``"dropped (workflow removed)"`` or ``"keep LLM"``. + """ + if entry.get("verdict") == "dropped": + return "dropped (workflow removed)" + return "keep LLM" + + +def _candidate_table(candidates: list[Candidate], handled: set[str]) -> str: """Render the ranked candidate table. Args: candidates: Ranked candidates. + handled: Ids with a recorded verdict — their action column stops + suggesting a review. Returns: The Markdown table (or a placeholder when empty). @@ -286,7 +338,8 @@ def _candidate_table(candidates: list[Candidate]) -> str: rows = [ f"| {rank} | {cand.id} | {cand.kind} | " f"{cand.occurrences}x / {cand.sessions} sessions " - f"| {fmt_tokens(cand.est_weekly_savings)}/wk | {cand.action} |" + f"| {fmt_tokens(cand.est_weekly_savings)}/wk | " + f"{_action_cell(cand, handled)} |" for rank, cand in enumerate(candidates[:TABLE_TOP], start=1) ] overflow = "" @@ -336,12 +389,14 @@ def _reviewed_keep_llm(compiled: list[dict[str, object]]) -> str: Returns: The section text. """ - kept = [entry for entry in compiled if entry.get("verdict") == "keep-llm"] + kept = [ + entry for entry in compiled if entry.get("verdict") in ("keep-llm", "dropped") + ] if not kept: return "## Reviewed — keeping LLM\n\nnone reviewed yet\n" lines = [ f"- {entry.get('candidate_id')} — " - f"reviewed {entry.get('compiled_at')} — keep LLM" + f"reviewed {entry.get('compiled_at')} — {_verdict_label(entry)}" for entry in kept ] return "## Reviewed — keeping LLM\n\n" + "\n".join(lines) + "\n" @@ -394,4 +449,9 @@ def write_report( (home / REPORT_FILE).write_text( render_report(records, result, compiled, now), encoding="utf-8" ) - return write_state(home, significant_ids(result.candidates), now) + pending = [ + cid + for cid in significant_ids(result.candidates) + if cid not in handled_ids(compiled) + ] + return write_state(home, pending, now) diff --git a/python_pkg/session_autopsy/tests/test_report.py b/python_pkg/session_autopsy/tests/test_report.py index 2388e96f..a9d28f56 100644 --- a/python_pkg/session_autopsy/tests/test_report.py +++ b/python_pkg/session_autopsy/tests/test_report.py @@ -131,19 +131,27 @@ def _fake_candidate(index: int) -> Candidate: def test_candidate_table_empty_and_overflow() -> None: - """Empty corpus placeholder and the beyond-top-40 overflow note.""" - assert "none yet" in report._candidate_table([]) - table = report._candidate_table([_fake_candidate(index) for index in range(45)]) + """Empty corpus placeholder, overflow note, and handled-action swap.""" + assert "none yet" in report._candidate_table([], set()) + table = report._candidate_table( + [_fake_candidate(index) for index in range(45)], {"err-00000001"} + ) assert "plus 5 below the fold" in table + assert "already handled — see Reviewed/scoreboard" in table def test_reviewed_keep_llm_section() -> None: """Empty and populated reviewed-keep-LLM sections.""" assert "none reviewed yet" in report._reviewed_keep_llm([]) section = report._reviewed_keep_llm( - [_compiled_entry(verdict="keep-llm", candidate_id="skill-x")] + [ + _compiled_entry(verdict="keep-llm", candidate_id="skill-x"), + _compiled_entry(verdict="dropped", candidate_id="skill-y"), + ] ) assert "skill-x" in section + assert "skill-y — reviewed" in section + assert "dropped (workflow removed)" in section def test_render_and_write_report(tmp_path: Path) -> None: @@ -174,6 +182,13 @@ def test_render_and_write_report(tmp_path: Path) -> None: assert unreviewed == 1 assert len(result.candidates) > 1 assert (tmp_path / report.REPORT_FILE).is_file() + (tmp_path / report.COMPILED_FILE).write_text( + json.dumps([_compiled_entry()]), encoding="utf-8" + ) + assert report.write_report(tmp_path, records, result, NOW) == 0 + assert "already handled" in (tmp_path / report.REPORT_FILE).read_text( + encoding="utf-8" + ) def test_trend_and_header_empty_states() -> None: