refactor: proverki.md and stavki.md become indexes, not the full text - #107
Merged
Conversation
Both files are read on every audit regardless of which checks or rate topics a
payroll actually needs - proverki.md ~27K tokens for 86 checks, stavki.md ~30K
for thirteen unrelated rate topics. Neither the checklist nor the rates need
to be one file: SKILL.md's step 3a already decides which check groups stay
"проверява се" before the checklist is read, and a given payroll rarely
touches more than three or four of stavki.md's thirteen topics at once.
proverki.md is now an index: every check's title, grouped A-K, and nothing
else. The full text - basis, arithmetic, worked example - moves to
references/proverki/<letter>.md, one file per group, read only for the groups
step 3a leaves open. Group K's file also carries "Как се чете електронна
таблица" above its bullets and "Формули" below them, matching their prior
position.
stavki.md is now an index the same way: the status legend, the per-section
verification-date table (now with a file column), the currency-changeover
rule, the contributor guide and the changelog. The thirteen rate tables move
to references/stavki/<topic>.md - МРЗ/МОД, contributions, the чл. 446 ГПК
attachment scale, income tax, the leave-pay/severance base, sick pay, in-kind
benefits, class, overtime/night/holiday premiums, and КТ deadlines - linked
from a new "Ставки по теми" section.
Both splits were verified lossless before anything else: every group/topic
file's content was diffed byte-for-byte against the original file's matching
section before the source was touched.
What moving the content broke, and the fix:
- Cross-file prose that assumed single-file adjacency ("по-горе", "в
началото на този файл"): three in stavki.md's own body (a запор section
pointing back at the МРЗ table now in a different file, a bolnichni section
pointing at the leave-pay base, a срокове table pointing at the запор
scale), plus roughly thirty places across SKILL.md and every
proverki/<letter>.md file that named a specific stavki.md section by
heading ("„Срокове и лимити по КТ“", "„Състав на базата“", etc.) - each now
names its topic file directly. One citation (F1_insurable_unexplained's
чл. 6, ал. 2 КСО) lived only in what is now a proverki/f.md paragraph and
nowhere else in the reference tree.
- test/findings.py's citation-grounding search read exactly three top-level
files; a citation living only in a moved fragment silently stopped being
"grounded" and would have raised ImportError on the next import. Now globs
every file under references/proverki/ and references/stavki/ too.
- test/rates_test.py's TEXT was one file's content; a rate that moved out of
the index would never be found by extract()'s regexes. Now concatenates the
index with every topic file (the "exactly one match" rule still holds
across all of them, and now also catches an accidental duplicate between
index and topic).
- tools/preflight.py's regime_boundaries() scanned stavki.md alone for the
МРЗ/МОД date-range tables; those moved into stavki/mrz-mod.md. Now reads
the index plus every file under stavki/.
- test/skill_test.py's PAID_GUIDANCE search built its file bundle from
os.listdir(references/), which does not recurse - a pinned phrase that
moved into stavki/otpusk-baza.md went invisible to it. Now recurses one
level into subdirectories.
- test/eval_skill.py's isolation-taint check and _skill_signature() (which
guards against grading a stale plugin-cache checkout) both read a hardcoded
four-file list; a scenario id leaking into a moved fragment, or a stale
checkout of one, would have gone unnoticed. Both now enumerate every file
under references/proverki/ and references/stavki/ via a shared
_skill_files() helper.
- test/skill_test.py did not previously verify that references/proverki/ or
references/stavki/ contained exactly the files their respective index
promises - the generic orphan-file check does not recurse into
subdirectories, so a missing or stale group/topic file would have gone
unnoticed there too. Two new checks pin the exact file set against what
each index's own bullets name.
- .agents/skills/trz-expert/SKILL.md (the Codex CLI pointer), CONTRIBUTING.md,
CLAUDE.md and .github/PULL_REQUEST_TEMPLATE.md updated to describe the two-
tier structure and where to actually add a check or a rate now.
Full test battery green throughout, at higher depth than the default for the
final state: rates_test, skill_test, run_tests --seeds 50, preflight_test,
komplekt_test, lifecycle_test, k_checker_test --seeds 100, eval_skill
--selftest, plus direct calls to eval_skill.check_isolation() and
tree_skill_signature().
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XvbzEbQwxwxxHAtXfPMrno
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.
Summary
Point 3 of the trz-expert evaluation:
proverki.md(~27K tokens, 86 checks) andstavki.md(~30K tokens, thirteen unrelated rate topics) were read in full on every audit regardless of which checks or topics a payroll actually needed. SKILL.md's step 3a already decides which check groups stay "проверява се" before the checklist is read, and a given payroll rarely touches more than three or four of stavki.md's thirteen topics — so neither file needed to be monolithic.proverki.mdis now an index — every check's title, grouped A–K. Full text (basis, arithmetic, example) moves toreferences/proverki/<letter>.md, loaded only for open groups.stavki.mdis now an index — status legend, per-section verification-date table (now with a file column), currency rule, contributor guide, changelog. The thirteen rate tables move toreferences/stavki/<topic>.md, linked from a new "Ставки по теми" section.Both splits were verified lossless before anything else — every group/topic file diffed byte-for-byte against the original section.
What the split broke, and the fix
proverki/<letter>.mdfile that named a specificstavki.mdsection by heading (e.g. „Срокове и лимити по КТ“) now name the topic file directly. Three prose references instavki.mditself assumed single-file adjacency ("по-горе", "в началото на този файл") and needed rewording.F1_insurable_unexplained's чл. 6, ал. 2 КСО) lived only in a paragraph that moved toproverki/f.md—test/findings.py's citation-grounding search read only 3 top-level files and would have raisedImportErroron next import (confirmed by reproducing it before fixing).test/rates_test.py,tools/preflight.py'sregime_boundaries(), andtest/skill_test.py'sPAID_GUIDANCEsearch all assumed the rates/reference text lived in one file — all three now read the index plus every split-out file.test/eval_skill.py's isolation-taint check and_skill_signature()(staleness guard against a frozen plugin-cache checkout) read a hardcoded 4-file list — now enumerate every file under both subdirectories via a shared helper.skill_test.pychecks pin the exact file sets underreferences/proverki/andreferences/stavki/against what each index's own bullets promise — an orphan or missing file there was previously invisible to the generic (non-recursive) orphan check..agents/skills/trz-expert/SKILL.md(Codex pointer),CONTRIBUTING.md,CLAUDE.md,.github/PULL_REQUEST_TEMPLATE.mdupdated to describe the two-tier structure.Test plan
rates_test,skill_test,run_tests --seeds 50,preflight_test,komplekt_test,lifecycle_test,k_checker_test --seeds 100,eval_skill --selftest— all greeneval_skill.check_isolation()andtree_skill_signature()— clean, no exceptionsskill_test.pyfile-set checks have teeth (moved a group/topic file aside, watched it fail, restored it)🤖 Generated with Claude Code
https://claude.ai/code/session_01XvbzEbQwxwxxHAtXfPMrno