Initial commit

2025-11-30 08:59:38 +08:00
commit 57790ee711
8 changed files with 1419 additions and 0 deletions
--- a/skills/using-skillpack-maintenance/implementing-fixes.md
+++ b/skills/using-skillpack-maintenance/implementing-fixes.md
@@ -0,0 +1,334 @@
+# Implementing Fixes
+
+**Purpose:** Autonomous execution of approved changes with version management and git commit.
+
+## Prerequisites
+
+You should have completed and gotten approval for:
+- Pass 1: Structure review (gaps, duplicates, organization)
+- Pass 2: Content testing (gauntlet results, fix priorities)
+- Pass 3: Coherence validation (cross-skill consistency, faction alignment)
+- User discussion and approval of scope
+
+**Do NOT proceed without user approval of the scope of work.**
+
+## Execution Workflow
+
+### 1. Structural Fixes (from Pass 1)
+
+**CRITICAL CHECKPOINT - New Skills:**
+
+**STOP:** Did you identify gaps (new skills needed) in Pass 1?
+
+**If YES → You MUST exit this workflow NOW:**
+
+1. **DO NOT proceed to execution**
+2. **For EACH gap identified:**
+   - Use `superpowers:writing-skills` skill
+   - RED: Test scenario WITHOUT the skill
+   - GREEN: Write skill addressing gaps
+   - REFACTOR: Close loopholes
+   - **Commit that ONE skill**
+3. **Repeat for ALL gaps** (each skill = separate RED-GREEN-REFACTOR cycle)
+4. **AFTER all new skills are tested and committed:**
+   - Return to meta-skillpack-maintenance
+   - Load this briefing again
+   - Continue with other structural fixes below
+
+**Proceeding past this checkpoint assumes:**
+- ✓ Zero new skills needed, OR
+- ✓ All new skills already created via superpowers:writing-skills
+- ✓ You are ONLY enhancing existing skills, removing duplicates, updating router/metadata
+
+**If you identified ANY gaps and haven't used superpowers:writing-skills for each:**
+**STOP. Exit now. You're violating the Iron Law: NO SKILL WITHOUT BEHAVIORAL TESTING.**
+
+---
+
+**Remove duplicate skills:**
+
+For skills marked for removal:
+1. Identify unique value in skill being removed
+2. Merge unique value into kept skill (if any)
+3. Delete duplicate SKILL.md and directory
+4. Remove references from router (if exists)
+5. Update cross-references in other skills
+
+**Merge overlapping skills:**
+
+For partial duplicates:
+1. Identify all unique content from both skills
+2. Create merged skill with comprehensive coverage
+3. Reorganize structure if needed
+4. Delete original skills
+5. Update router and cross-references
+6. Update skill name/description if needed
+
+**Update router skill:**
+
+If pack has using-X router:
+1. Update specialist list to reflect adds/removes
+2. Update descriptions to match current skills
+3. Verify routing logic makes sense
+4. Add cross-references as needed
+
+### 2. Content Enhancements (from Pass 2)
+
+**For each skill marked "Fix needed" in gauntlet testing:**
+
+**Fix rationalizations (A-type issues):**
+1. Add explicit counter for each identified rationalization
+2. Update "Common Rationalizations" table
+3. Add to "Red Flags" list if applicable
+4. Strengthen "No exceptions" language
+
+**Fill edge case gaps (C-type issues):**
+1. Add guidance for identified corner cases
+2. Document when/how to adapt core principles
+3. Add examples for edge case handling
+4. Cross-reference related skills if needed
+
+**Enhance real-world guidance (B-type issues):**
+1. Add examples from realistic scenarios
+2. Clarify ambiguous instructions
+3. Add decision frameworks where needed
+4. Update "When to Use" section if unclear
+
+**Add anti-patterns:**
+1. Document observed failure modes from testing
+2. Add ❌ WRONG / ✅ CORRECT examples
+3. Update "Common Mistakes" section
+4. Add warnings for subtle pitfalls
+
+**Improve examples:**
+1. Replace weak examples with tested scenarios
+2. Ensure examples are complete and runnable
+3. Add comments explaining WHY, not just WHAT
+4. Use realistic domain context
+
+### 3. Coherence Improvements (from Pass 3)
+
+**Cross-reference updates:**
+
+**CRITICAL:** This is post-update hygiene - ensure skills reference new/enhanced skills.
+
+For each skill in pack:
+1. Identify related skills (related concepts, prerequisites, follow-ups)
+2. Add cross-references where helpful:
+   - "See [skill-name] for [related concept]"
+   - "**REQUIRED BACKGROUND:** [skill-name]"
+   - "After mastering this, see [skill-name]"
+3. Update router cross-references
+4. Ensure bidirectional links (if A references B, should B reference A?)
+
+**Terminology alignment:**
+
+1. Identify terminology inconsistencies across skills
+2. Choose canonical terms (most clear/standard)
+3. Update all skills to use canonical terms
+4. Add glossary to router if needed
+
+**Faction voice adjustment:**
+
+For skills flagged with faction drift:
+1. Read FACTIONS.md for faction principles
+2. Adjust language/tone to match faction
+3. Realign examples with faction philosophy
+4. If severe drift: Flag for potential rehoming
+
+**If rehoming recommended:**
+- Document which faction skill should move to
+- Note in commit message for manual handling
+- Don't move skills automatically (requires marketplace changes)
+
+**Metadata synchronization:**
+
+Update `plugin.json`:
+1. Description - ensure it matches enhanced pack content
+2. Count skills if tool supports it
+3. Verify category is appropriate
+
+### 4. Version Management (Impact-Based)
+
+**Assess impact of all changes:**
+
+**Patch bump (x.y.Z) - Low impact:**
+- Typos fixed
+- Formatting improvements
+- Minor clarifications (< 50 words added)
+- Small example corrections
+- No new skills, no skills removed
+
+**Minor bump (x.Y.0) - Medium impact (DEFAULT):**
+- Enhanced guidance (added sections, better examples)
+- New skills added
+- Improved existing skills significantly
+- Better anti-pattern coverage
+- Fixed gauntlet failures
+- Updated for current best practices
+
+**Major bump (X.0.0) - High impact (RARE, use sparingly):**
+- Skills removed entirely
+- Structural reorganization
+- Philosophy shifts
+- Breaking changes to how skills work
+- Deprecated major patterns
+
+**Decision logic:**
+1. Any new skills added? → Minor minimum
+2. Any skills removed? → Consider major
+3. Only fixes/clarifications? → Patch
+4. Enhanced multiple skills significantly? → Minor
+5. Changed pack philosophy? → Major
+
+**Default for maintenance reviews: Minor bump**
+
+**Update version in plugin.json:**
+```json
+{
+  "version": "[new-version]"
+}
+```
+
+### 5. Git Commit
+
+**Single commit with all changes:**
+
+**Commit message format:**
+
+```
+feat(meta): enhance [pack-name] - [one-line summary]
+
+Structure changes:
+- Added [count] new skills: [skill-1], [skill-2], ...
+- Removed [count] duplicate skills: [skill-1], [skill-2], ...
+- Merged [skill-a] + [skill-b] into [skill-merged]
+- Updated router to reflect new structure
+
+Content improvements:
+- Enhanced [skill-1]: [specific improvements]
+- Enhanced [skill-2]: [specific improvements]
+- Fixed gauntlet failures in [skill-3]: [issues addressed]
+- Added anti-patterns to [skill-4]
+
+Coherence updates:
+- Added cross-references between [count] skills
+- Aligned terminology across pack
+- Adjusted faction voice in [skill-name]
+- Updated plugin.json metadata
+
+Version: [old-version] → [new-version] ([patch/minor/major])
+Rationale: [reason for version bump type]
+```
+
+**Commit command:**
+
+```bash
+git add plugins/[pack-name]/
+git commit -m "$(cat <<'EOF'
+feat(meta): enhance [pack-name] - [summary]
+
+[Full message body as above]
+EOF
+)"
+```
+
+**Do NOT push** - let user decide when to push.
+
+## Execution Principles
+
+**Autonomous within approved scope:**
+- Execute all approved changes without asking again
+- Follow user's approved plan exactly
+- Make editorial decisions within scope
+- Ask only if something unexpected blocks progress
+
+**Quality standards:**
+- All new skills follow CSO guidelines (name/description format)
+- All code examples are complete and appropriate to domain
+- All cross-references are accurate
+- Faction voice is maintained
+
+**Verification before commit:**
+- Verify YAML front matter syntax in all modified skills
+- Check that all cross-references point to existing skills
+- Ensure router (if exists) references all current skills
+- Verify plugin.json has valid JSON syntax
+
+## Output After Completion
+
+Provide comprehensive summary:
+
+```
+# Pack Enhancement Complete: [pack-name]
+
+## Version: [old] → [new] ([type])
+
+## Summary Statistics
+
+- Skills added: [count]
+- Skills removed: [count]
+- Skills enhanced: [count]
+- Skills tested and passed: [count]
+
+## Changes by Category
+
+### Structure
+[List of structural changes]
+
+### Content
+[List of content improvements]
+
+### Coherence
+[List of coherence updates]
+
+## Git Commit
+
+Created commit: [commit-hash if available]
+Message: [first line of commit]
+
+Ready to push: [Yes]
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Proceeding without approval | Always get user approval before executing |
+| Batch changes across passes | Complete one pass fully before next |
+| Inconsistent faction voice | Read FACTIONS.md, maintain voice throughout |
+| Broken cross-references | Verify all referenced skills exist |
+| Invalid YAML | Check syntax before committing |
+| Pushing automatically | Let user decide when to push |
+| Vague commit messages | Be specific about what changed and why |
+| Wrong version bump | Follow impact-based rules, default to minor |
+
+## Anti-Patterns
+
+**❌ Changing scope during execution:**
+- Don't add extra improvements not discussed
+- Don't skip approved changes because "not needed"
+- Stick to approved scope exactly
+
+**❌ Sub-optimal quality:**
+- Don't write quick/dirty skills to fill gaps
+- Don't copy-paste without adapting to faction
+- Don't skip cross-references to save time
+
+**❌ Incomplete commits:**
+- Don't commit partial work
+- Don't split into multiple commits
+- Single commit with all changes
+
+**❌ No verification:**
+- Don't assume syntax is correct
+- Don't skip cross-reference checking
+- Verify before committing
+
+## The Bottom Line
+
+**Execute approved changes autonomously with high quality standards.**
+
+One commit. Proper versioning. Complete summary.
+
+No shortcuts. No scope creep. Professional execution.