docs(skill): tighten update-upstream skill for general patterns#104
Merged
Conversation
Rewrite Common Pitfalls section to focus on classes of recurring bugs rather than single-occurrence specifics: - Collapse the two 'closed config key sets' bullets into one general pattern: data shapes live in multiple sites; mirror every one. - Generalize 'don't double-convert' into 'conversion happens once at the boundary' with opaque-data escape hatches as the only exception. - Move wire-conversion mechanics (? suffix, csk behavior, mock vs wire shape) out of the pitfall list and into the cheat sheet — one place. Update Phase 2 gap analysis to use general categories (signatures, events, configs, behavioral changes) instead of artifacts from a past sync (resolvedByHook, permission result kinds). Update Phase 10 self-review to require new pitfalls generalize to a class of bug — preventing the list from re-bloating each sync. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-only change refining the update-upstream skill instructions. Tightens the Common Pitfalls section in SKILL.md from specific examples to general patterns, moves wire-conversion mechanics into the PROJECT.md cheat sheet (single source of truth), and adds a guardrail in Phase 10 self-review to prevent the pitfall list from re-bloating on each sync.
Changes:
- Collapse 6 specific pitfall bullets into 4 generalized patterns in SKILL.md
- Move wire-conversion mechanics (
?suffix, csk behavior, mock vs wire shape, opaque-data escape hatches) to references/PROJECT.md cheat sheet - Add Phase 10 guardrail requiring new pitfalls to generalize to a class of bug
Show a summary per file
| File | Description |
|---|---|
| .github/skills/update-upstream/SKILL.md | Generalize Phase 2 gap examples; tighten Common Pitfalls (6→4); add Phase 10 guardrail |
| .github/skills/update-upstream/references/PROJECT.md | Expand Wire Conversion Cheat Sheet to absorb mechanics moved out of SKILL.md |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 0
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
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.
Follow-up to the v1.0.48 sync (PR #103). During Phase 10 self-review of the
update-upstreamskill, the Common Pitfalls section had drifted toward single-occurrence specifics rather than general patterns. This tightens it.Changes
SKILL.md — Common Pitfalls: 6 specific bullets → 4 general patterns
?suffix, csk behavior, mock vs wire shape) out of the pitfall list and into the cheat sheet.SKILL.md — Phase 2 gap analysis: replaced examples overfitted to past syncs (
resolvedByHook, permission result kinds) with general categories (signatures, events, configs, behavioral changes).SKILL.md — Phase 10: added a guardrail — only propose a new pitfall if it generalizes to a class of bug. Prevents the list from re-bloating each sync.
references/PROJECT.md — Cheat Sheet: now the single source of truth for wire-conversion mechanics; absorbed the details that used to live in SKILL.md, plus the opaque-data escape-hatch rule.
Net effect: SKILL.md is shorter, info lives in one place, and the self-review step has a discipline that resists future drift.