Skip to content

feat(skill-writer): Add scope-aware encapsulation depth gate#139

Open
the-simian wants to merge 1 commit into
getsentry:mainfrom
the-simian:feat/scope-aware-encapsulation
Open

feat(skill-writer): Add scope-aware encapsulation depth gate#139
the-simian wants to merge 1 commit into
getsentry:mainfrom
the-simian:feat/scope-aware-encapsulation

Conversation

@the-simian
Copy link
Copy Markdown

@the-simian the-simian commented May 2, 2026

Add a Scope-Aware Encapsulation principle to skill-writer/references/design-principles.md, a matching hard-stop rule in mode-selection.md, and a sister-update to skill-writer/SPEC.md, so authored skills stay matched to the level at which they are registered.

Why. skill-writer's synthesis path explicitly permits local project files as grounding evidence. For a project-scoped skill, surfacing those files' identifiers in the authored body is correct; for a globally registered skill, it is not. The rule is implicit in good practice but is not currently codified anywhere skill-writer consults: Independence And Portability covers provider portability (paths, runtime deps), and mode-selection.md's portability note in synthesis outputs covers provider-specific mechanics, not registration-scope encapsulation of body content. An authoring agent following the documented synthesis-then-author flow can therefore land a global skill whose worked examples reference symbols that exist in only one project, producing references that resolve to nothing for every other consumer of the skill. This PR adds the principle, the matching hard-stop, and the contract bullet.

Scope of the principle. The rule targets body content vs. registration scope: a skill's worked examples and inline references must not exceed the scope at which it is registered. Source synthesis may consult a project's files to learn the canonical pattern; the resulting body must abstract that pattern with structural placeholder names. Project-scoped skills are explicitly carved out and may anchor freely on real codebase symbols.

What changed.

  • skills/skill-writer/references/design-principles.md: add a Scope-Aware Encapsulation section after Independence And Portability with a registration/scope/body-may-reference table, an explicit one-sentence distinction from the prior section, and four bullets covering the resolution rule, the abstraction rule for globals, the consult-but-don't-bake rule for synthesis, and the carve-out for project skills.
  • skills/skill-writer/references/mode-selection.md: add one line to Hard stop rules flagging hard-coded project-specific identifiers in a globally registered skill as a hard failure. Cross-references the new section.
  • skills/skill-writer/SPEC.md: add one bullet to Non-negotiable constraints mirroring the new principle, so the skill's maintenance contract reflects the new gate.

@the-simian the-simian force-pushed the feat/scope-aware-encapsulation branch from 5cbe1fc to 7c58ddb Compare May 2, 2026 01:26
Comment thread skills/skill-writer/references/design-principles.md Outdated
@the-simian the-simian force-pushed the feat/scope-aware-encapsulation branch from 7c58ddb to d0f61dc Compare May 2, 2026 01:31
A skill's body should not exceed its registration scope. Globally registered skills that hard-code project-specific identifiers ship them to every consumer, where the references resolve to nothing.

- design-principles.md: new Scope-Aware Encapsulation section pairs registration locations with what the body may reference, and sets the rule for resolving scope before authoring.
- mode-selection.md: hard-coded project-specific identifiers in a globally registered skill are now a hard failure in the authoring path.
- SPEC.md: matching bullet in Non-negotiable constraints reflects the new gate in the skill's maintenance contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@the-simian the-simian force-pushed the feat/scope-aware-encapsulation branch from d0f61dc to 74b1a91 Compare May 2, 2026 01:35
@the-simian
Copy link
Copy Markdown
Author

Force-pushed a few times to fold self-review fixes into the original commit (current HEAD 74b1a91). The Sentry bot's MEDIUM finding on placeholder names is addressed. Diff is +18 / -0 across the three files in the PR body.

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.

1 participant