Skip to content

Give each restated rule one owner - #365

Open
alanhc wants to merge 5 commits into
sysprog21:mainfrom
alanhc:skills-consolidate
Open

Give each restated rule one owner#365
alanhc wants to merge 5 commits into
sysprog21:mainfrom
alanhc:skills-consolidate

Conversation

@alanhc

@alanhc alanhc commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Eight rules were written out in two skills each, which is the shape
references/prose-register.md warns about: a rule copied to a second place is
a rule that can drift. Each now sits with the skill that owns the mechanism,
and the second site names that skill rather than restating it.

What moved

Rule Kept by Routes from
The GDB stub's refusal of x86_64 elfuse-debug elfuse-guest-abi
What check-atomics.py cannot see elfuse-conventions elfuse-security
A proof binds the arithmetic, not its callers elfuse-verify elfuse-security
The lock ordering record elfuse-syscall elfuse-conventions, elfuse-refactor, elfuse-security
The change-area-to-command table elfuse-verify elfuse-syscall, elfuse-refactor
Recompute a number, take the baseline first, name the lane that could not run elfuse-verify elfuse-refactor
Where a new file or shared declaration goes elfuse-conventions elfuse-syscall

Two skills also stated a rule twice inside themselves: elfuse-security on the
lock record, once in the shared-pages rule and once in the gate list beneath
it, and elfuse-refactor on make lint never having been clean.

What this does not do

It does not make the skills shorter. 2234 lines to 2229, because a pointer
costs about what the restatement cost. The saving is one home per rule rather
than bytes.

The volume is in elfuse-conventions at 402 lines, elfuse-security at 310
and elfuse-guest-abi at 291, and there it is subject matter rather than
repetition. Cutting it means merging skills or dropping sections, which changes
which skill fires on which task, so it is a different change from this one.

One candidate is left in place deliberately. "This skill is a working summary.
These are tracked and survive a fresh clone, so prefer them when the two
disagree:" appears verbatim in five skills, and looks like the clearest
boilerplate in the set. Skills load independently, so a reader who loaded only
elfuse-debug would lose what its authoritative sources list is for.

Verification

make check-skill-refs resolves every path, target, section and
cross-reference across the 12 files, and scripts/check-commit-log.sh accepts
all five commits. Documentation only: no build or test target reads these
files.


Summary by cubic

Consolidates duplicated rules so each has a single owning skill. Eight rules were written out in two skills each, and two skills stated a rule twice within themselves; now each rule sits with the skill that owns its mechanism, and other sites name that skill instead of restating it, so a rule can no longer drift between copies.

  • elfuse-syscall keeps the lock ordering record, elfuse-verify keeps the validation table, proof limits, and reporting rules, elfuse-conventions keeps file placement and the check-atomics.py blind spot, and elfuse-debug keeps the GDB stub refusal.
  • Skills stay nearly the same length (2234 → 2229 lines) because a pointer costs about what the restatement did; the win is one home per rule, not fewer bytes.
  • One boilerplate block ("This skill is a working summary...") deliberately remains in five skills since skills load independently and a reader of only one would lose what its sources list is for.
  • Documentation only; make check-skill-refs resolves every path, target, section, and cross-reference across the 12 files.

Written for commit a7f6cac. Summary will update on new commits.

Review in cubic

cubic-dev-ai[bot]

This comment was marked as resolved.

jserv

This comment was marked as resolved.

Three facts were written out in two skills each, in the shape the
register warns about: a rule copied to a second place is a rule that can
drift. Each now sits with the skill that owns the mechanism, and the
second site names that skill.

The GDB stub's refusal of x86_64 belongs beside the flag it refuses, in
elfuse-debug. What check-atomics.py cannot see belongs with the atomics
rules in elfuse-conventions. That a proof binds the arithmetic and not
its callers belongs with the proofs in elfuse-verify, which also carries
what narrows it.

The security skill keeps the judgment each one supports, since a review
priority is not the fact it rests on.
Four skills told a contributor to record a new lock, and only one of
them carried what the record actually holds. elfuse-syscall states where
it lives and the three constraints that do not follow from the ordering
itself, so it keeps the rule.

The other three name it instead of restating it. The security skill also
said it twice on its own, once in the shared-pages rule and once in the
gate list beneath, where check-lock-order.py is what fails the omission.
The change-area-to-command table in docs/testing.md was named and
glossed in three skills. elfuse-verify opens on it and says what a
failure in each lane means, so the other two ask it rather than
restating the pointer.

Both keep what they add: a cleanup earns the feature's command set
rather than a smaller one, and a syscall change hands a failure to
elfuse-debug. The tracked section stays in the authoritative sources
list, which is where a skill names a file it defers to.
Three rules about reporting a run were written in both elfuse-verify and
elfuse-refactor: recompute a number rather than quoting it from a
document, take the baseline before a session rather than after, and name
a lane that could not run instead of rounding it up. elfuse-verify has
the section that decides what done means, so it keeps all three.

The refactor skill keeps what only it can say: the one-liners that
measure this tree, and which of its reds a cleanup inherits rather than
causes. It also stated the lint red twice on its own, once where the
gates are measured and once in the same paragraph as the baseline.
Both skills answered it. elfuse-conventions owns where a file, a type,
and a shared declaration may go, and it is the skill a contributor
reaches for that question; the syscall procedure asks it there rather
than repeating the answer mid-step.

What stays in the procedure is the part specific to it: which domain
file a sys_ implementation belongs in, and the three examples that make
the naming legible.
@alanhc
alanhc force-pushed the skills-consolidate branch from a6182bc to a7f6cac Compare September 4, 2026 10:02
@alanhc

alanhc commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator Author

Rebased onto main; the conflicts were in elfuse-refactor/SKILL.md, which Record what this refactor pass taught (3bcd930) rewrote wholesale. Resolved by re-landing this PR's edits against the new structure: the lock bullet in "Preserve the boundaries" now routes to elfuse-syscall instead of restating the ordering-comment rule, and the obsolete "Three cases where I only moved code is wrong" list is dropped since "Route the change first" already covers it.

cubic's two findings, both folded into Give the lock ordering record one owner:

  1. elfuse-security:164 — reworded to "which the gate below fails for being missing".
  2. elfuse-conventions:237 — dropped the restated "before its second module" condition, which was weaker than elfuse-syscall's actual rule (a lock enters the record as soon as it exists). Now routes to elfuse-syscall for the condition too, not just the record's location.

@jserv

jserv commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

I defer to @henrybear327 for confirmation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants