session_autopsy: handled candidates leave the nudge; drop explain-diff
Some checks failed
Pre-commit checks / pre-commit (push) Waiting to run
Shell tests / shell-tests (push) Waiting to run
Shell tests / arch-tests (push) Waiting to run
Python tests / test (push) Has been cancelled

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 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-07-25 18:12:38 +02:00
parent a07405c05f
commit 5ab9a806eb
4 changed files with 127 additions and 13 deletions

View File

@ -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."
]
}

View File

@ -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

View File

@ -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)

View File

@ -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: