Tracker: `.agents/skills/skill-lifecycle/SKILL.md > The Doc-Packaging Pattern`

[ptr727]

Tracker for .agents/skills/skill-lifecycle/SKILL.md > The Doc-Packaging Pattern. Filed under the rule #1314's Merge Gate half writes into that unit: a finding classed pre-existing on carried prose is gathered onto the unit's tracker rather than dispositioned one at a time. These are the pre-existing findings the whole-unit pass raised on that unit while the change adding include regions to scripts/build_dist.py (#1317, mechanism pull request) was reviewed. None was introduced by the change and none blocked it. A new pre-existing finding on this unit gathers here, numbering continuing this list. This tracker closes when the unit is rewritten and each line below is settled or superseded.

1. "The section ends with the standard pointer sentence" is contradicted by two of the three sections the bullet names as examples: GOVERNANCE.md "Documentation Style Conventions" places its pointer and then continues with four rule-bearing subsections before the next level-two heading, and "PR Review Etiquette" places its pointer and then adds a further paragraph on provider-specific mechanics. Only "Git and Commit Rules" ends on the pointer, so a reader auditing a moved-content section against this unit finds two of its own three examples non-conformant.
2. The same "Documentation Style Conventions" section keeps full rules of its own in those four subsections rather than a summary, so the comment-and-doc-style pairing named as an example of the moved-content shape is not a clean instance of it.
3. The rendered "standard pointer sentence" matches no sentence in any doc. The live pointers are three sentences, "This is packaged as the <name> Skill at ... in the hub, not a repo-relative link since .... The summary above sketches the contract. Read the skill for ...", with a closing clause that varies per section, so an author copying the unit's rendering produces a pointer unlike every existing one, and nothing under spec/ enforces a wording that would settle which form is right.

[ptr727]

One more from the second whole-unit read on the same change, numbering continuing the list above:

4. "The source doc keeps the full rules and the skill is the summary that routes to them (audit-a-repo over AUDIT.md, workflow-ci-contract over WORKFLOW.md, ...)" names two skills that describe themselves as carrying binding rules by hand, which the unit's own closing paragraph calls the drift the pattern exists to prevent, so the shape's definition and its examples disagree. workflow-ci-contract also names the wrong owner, since GOVERNANCE.md "Workflow YAML Conventions" wins over WORKFLOW.md where the two overlap, per both that section and the skill's own text.

[ptr727]

One more from the third whole-unit read on the same change, numbering continuing the list above:

5. The moved-content parenthetical "(git-commit-conventions, comment-and-doc-style, pr-review-conduct)" omits operational-vs-release-workflow, which GOVERNANCE.md packages with the identical moved-content sentence in three sections, "Branching Model", "Release Model", and "Operational Repositories", so a reader taking the parenthetical as the census of the shape mis-classifies that pairing.

[ptr727]

One more from the fourth whole-unit read on the same change, numbering continuing the list above:

6. "It has three shapes, and each pairing states which it uses" is overstated for the kept-authority pairings: WORKFLOW.md never names workflow-ci-contract and AUDIT.md never names audit-a-repo, so for those two only the skill side states the shape and a reader opening the doc to confirm the pairing finds no statement at all.

[ptr727]

One more from the fifth whole-unit read on the same change, numbering continuing the list above:

7. "each pairing states which it uses" is also false for the Verification Discipline and local-strict-review pairing: GOVERNANCE.md pairs them with "The pass itself, its delegation shape, and its model tier are the local-strict-review Skill's", naming no shape and no pointer sentence, inside a section whose closing line declares it keeps the full rules for agent-conduct, so that pairing matches none of the three descriptions.

[ptr727]

Pre-existing finding from #1385's whole-unit read of this section, numbered on from item 3.

4. "The section ends with the standard pointer sentence" holds for one of the three moved-content examples: GOVERNANCE.md "Documentation Style Conventions" continues past its pointer into a ### Comments subsection, and "PR Review Etiquette" follows its pointer with a further paragraph on scripts/pr_review.py and the carried runbook, so only "Git and Commit Rules" ends as the sentence states. [.agents/skills/skill-lifecycle/SKILL.md > The Doc-Packaging Pattern] (Carry WORKFLOW.md Section 4 Into workflow-ci-contract as an Include #1385)