Reposition the README around the risk-team objections - #7
Merged
Conversation
Reframes the opening from an engineering-hygiene story (models get rewritten downstream and drift) to the actual adoption blocker: risk teams reject ML for three specific reasons — stability, explainability, deployability — and those objections are correct. What was missing is infrastructure that answers them, which is what the three guarantees do. - new opening states the positioning and the honest cost (about 2% of the teacher's Gini) on the first screen rather than in a table - 'Why I built this' becomes 'The three objections, answered', with the subsections labelled by the objection each one addresses; the personal anecdote stays as supporting evidence - new scorecard section: at depth <= 2 the artifact IS a classic points scorecard, which is the closing argument for a validator audience and was missing from the README entirely - new 'Choosing the configuration' section covering the trees-vs-depth asymmetry, the sweeps, and band_efficiency - corrections: band_drivers -> band_conditioned_decision_drivers (its primary name since #3), check 4 now mentions band efficiency, guarantees list gains the reference-replay and scorecard re-sum tests, docs list gains the FAQ and tuning guide - restores the hero image with an absolute raw URL so it renders on both GitHub and the PyPI project page; the viz section referenced 'the image at the top of this README', which was a dangling reference - drops the hedge in 'is designed to produce the same governed outputs': three OSes, a SQL engine and a compiled COBOL binary agree on every push, and the sentence after it already scopes the claim Verified: every relative link resolves, every referenced symbol imports, every referenced CLI subcommand exists.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reframes the README's thesis from an engineering-hygiene story to the actual adoption blocker.
The change in one line: "models get rewritten in SQL and drift" describes a problem that lands with whoever suffers it; "risk teams reject ML for three specific reasons, and they're right to" lands with whoever causes it — and that's the person holding the veto.
The existing three subsections already were the three objections, so they mostly needed relabelling (Stability / Explainability / Deployability) rather than rewriting. The personal anecdote survives intact as supporting evidence rather than as the thesis.
What's new
band_efficiency, all also from Tuning sweeps, band efficiency, exact scorecards, tuning guide + FAQ #6 and previously unreferenced.Corrections found along the way
band_drivers→band_conditioned_decision_drivers(primary name since viz: restore the original decision-driver design exactly #3)Verified before opening: every relative link resolves to a real file, every referenced symbol imports, every referenced CLI subcommand exists.