feat(skill): add reading unfamiliar code to the bundled pack - #531
Merged
Conversation
A procedure for building a working model of code you did not write, scoped to the edit you are about to make rather than to the repository as a whole. Its organising idea is provenance. Every claim the pending edit depends on is written down and marked read (the definition was opened in this tree, this session), ran (the behaviour was observed), or assumed (nothing was checked), and no edit may rest on a claim still marked assumed. Three claims earn the marks on nearly every change: that the symbols the edit calls are real, that one concrete input has been followed from the entry point to its effect, and that everything else observing the thing being altered has been enumerated. Unknowns are named rather than assumed away, and the model is written where the next session finds it. The opening section carries the measurement the skill exists for: models hallucinate roughly 13 percent of the third-party library calls they generate and roughly 85 percent of the calls to a project's own functions, and model size barely moves it. The published corpus answers the first number by verifying against official documentation. The second has no documentation to verify against, only the tree. It also states what this runtime executes that others cannot: concurrent children under --fanout folded into one verifiable record, so a thorough read does not cost the parent's context; sandboxed, priced execution that makes running the code the default source of evidence; a sealed run record, so what was opened before the first write is recoverable; and memory that carries the model into the next session. The skill ships without a check field and says so in the body. The condition worth grading is an ordering inside the run, and no shell command can observe the run that is invoking it. Signed-off-by: Ion Alpha <contact@ionalpha.io>
ion-alpha-dev
force-pushed
the
skill/reading-unfamiliar-code
branch
from
August 14, 2026 19:09
f248b53 to
78220b9
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
What
Adds
reading-unfamiliar-codeto the bundled skill pack: a procedure for building a working model of code you did not write, scoped to the edit you are about to make rather than to the repository as a whole. Seven rows in the pack's retrieval table say which objectives must reach it.Why
The pack had nothing on comprehension, and it is the step every other skill assumes has already happened. The measurement in the skill's opening section is the reason it is worth a slot: models hallucinate roughly 13 percent of the third-party library calls they generate and roughly 85 percent of the calls to a project's own functions, and model size barely moves it. Verifying against official documentation answers the first number. The second has no documentation to verify against, only the tree.
Its organising idea is provenance. Every claim the pending edit depends on is written down and marked read (the definition was opened in this tree, this session), ran (the behaviour was observed), or assumed (nothing was checked), and no edit may rest on a claim still marked assumed. Three claims earn the marks on nearly every change: that the symbols the edit calls are real, that one concrete input has been followed from the entry point to its effect, and that every other site observing the state being altered has been enumerated.
How to verify
go test ./skill/...is green.TestPackIsRetrievableis the one that matters: it runs the runtime's own ranker over the real pack against every row ofskill/bundled/skills/retrieval.txt, including the seven new ones, with no model and no tokens.Notes for reviewers
The skill ships with no
flynnhq.com/checkand the body has a section saying why: the condition worth grading is an ordering inside a run (definitions opened and a path traced before the first write), and no shell command can observe the run that is invoking it.Two phrases in the description were reworded so the skill stops outranking
structural-boundarieson "where should this new code go" anddomain-languageon "what should I call this thing". Both rows now pass. That tuning is sensitive to the rest of the pack: recall gathers a fixed five candidates per keyword ordered by slug and then scores on a raw count of matching terms, so adding a skill can displace an unrelated one. Worth fixing in the ranker rather than in each description, and it is not fixed here.