gh-tachyon-beep-skillpacks-plugins-meta-skillpack-maintenance/skills/using-skillpack-maintenance/reviewing-pack-structure.md

# Reviewing Pack Structure

**Purpose:** Pass 1 - Analyze pack organization, identify structural issues, generate fitness scorecard.

## Inputs

From `analyzing-pack-domain.md`:
- Domain coverage map (what should exist)
- Current skill inventory (what does exist)
- Gap analysis (missing/duplicate/obsolete)
- Research currency flag

## Analysis Tasks

### 1. Fitness Scorecard

Generate scorecard with risk-driven prioritization:

**Critical Issues** - Pack unusable or fundamentally broken:
- Missing core foundational concepts (users can't understand basics)
- Major gaps in essential coverage (50%+ of core techniques missing)
- Router completely inaccurate or missing when needed
- Multiple skills broken or contradictory

**Decision:** Critical issues → Recommend "Rebuild from scratch" vs. "Enhance existing"

Rebuild if:
- More skills missing than exist
- Fundamental philosophy is wrong
- Faction mismatch is severe

Enhance if:
- Core structure is sound, just needs additions/fixes
- Most existing skills are salvageable

**Major Issues** - Significant effectiveness reduction:
- Important gaps in core coverage (20-50% of core techniques missing)
- Multiple duplicate skills causing confusion
- Obsolete skills teaching deprecated patterns
- Faction drift across multiple skills
- Metadata significantly out of sync

**Minor Issues** - Polish and improvements:
- Small gaps in advanced topics
- Minor organizational inconsistencies
- Router descriptions slightly outdated
- Small metadata corrections needed

**Pass** - Structurally sound:
- Comprehensive coverage of foundational and core areas
- No major gaps or duplicates
- Router (if exists) is accurate
- Faction alignment is good
- Metadata is current

**Output:** Scorecard with category and specific issues listed

### 2. Gap Identification

From coverage map, identify missing skills:

**Prioritize by importance:**

**High priority (foundational/core):**
- Foundational concepts users must understand
- Core techniques used frequently
- Common patterns missing from basics

**Medium priority (advanced):**
- Advanced topics for expert users
- Specialized techniques
- Edge case handling

**Low priority (nice-to-have):**
- Rare patterns
- Future-looking topics
- Experimental techniques

**For each gap:**
- Draft skill name (following naming conventions)
- Write description (following CSO guidelines)
- Estimate scope (small/medium/large skill)
- Note dependencies (what skills should be read first)

**Output:** Prioritized list of gaps with draft names/descriptions

### 3. Duplicate Detection

Find skills with overlapping coverage:

**Analysis process:**
1. Read all skill descriptions
2. Identify content overlap (skills covering same concepts)
3. Read overlapping skills to assess actual content
4. Determine relationship

**Duplicate types:**

**Complete duplicates** - Same content, different names:
- **Action:** Remove one, preserve unique value from both

**Partial overlap** - Significant shared content:
- **Action:** Merge into single comprehensive skill

**Specialization** - One general, one specific:
- **Action:** Keep both, clarify relationship via cross-references
- Example: "async-patterns" (general) + "asyncio-taskgroup" (specific)

**Complementary** - Different angles on same topic:
- **Action:** Keep both, strengthen cross-references
- Example: "testing-async-code" + "async-patterns-and-concurrency"

**False positive** - Similar names, different content:
- **Action:** No change, maybe clarify descriptions

**For each duplicate pair:**
- Classification (complete/partial/specialization/complementary/false)
- Recommendation (remove/merge/keep with cross-refs)
- Preserve unique value from each

**Output:** Duplicate analysis with recommendations

### 4. Organization Validation

Check pack-level organization:

**Router skill validation (if exists):**
- Does router list all current specialist skills?
- Are descriptions in router accurate?
- Does routing logic make sense?
- Are there skills NOT mentioned in router?
- Are there router entries for NON-EXISTENT skills?

**Faction alignment:**
- Read FACTIONS.md for this pack's faction principles
- Check 3-5 representative skills for voice/philosophy
- Identify drift patterns
- Severity: Minor (style drift) / Major (wrong philosophy)

**Metadata validation:**
- plugin.json description matches actual content?
- Skill count is accurate?
- Category is appropriate?
- Version reflects current state?

**Navigation experience:**
- Can users find appropriate skills easily?
- Are skill names descriptive?
- Are descriptions helpful for discovery?

**Output:** Organization issues with severity

## Generate Complete Report

Combine all analyses:

```
# Structural Review: [pack-name]

## Scorecard: [Critical / Major / Minor / Pass]

[If Critical]
Recommendation: [Rebuild from scratch / Enhance existing]
Rationale: [Specific reasons]

## Issues by Priority

### Critical Issues ([count])
- [Issue 1] - [Description]
- [Issue 2] - [Description]

### Major Issues ([count])
- [Issue 1] - [Description]
- [Issue 2] - [Description]

### Minor Issues ([count])
- [Issue 1] - [Description]
- [Issue 2] - [Description]

## Gap Analysis

### High Priority Gaps ([count])
- [Gap 1]
  - Skill name: [proposed-name]
  - Description: [draft description]
  - Scope: [small/medium/large]
  - Dependencies: [prerequisites]

### Medium Priority Gaps ([count])
[Same format]

### Low Priority Gaps ([count])
[Same format]

## Duplicate Analysis

- [Skill A] + [Skill B]
  - Type: [complete/partial/specialization/complementary]
  - Recommendation: [remove/merge/keep with cross-refs]
  - Rationale: [why]

## Organization Issues

### Router ([issues count])
- [Issue description]

### Faction Alignment ([severity])
- [Drift pattern]
- Affected skills: [list]

### Metadata ([issues count])
- [Issue description]

## Recommended Actions

**Gaps requiring superpowers:writing-skills:**
- [count] new skills needed (RED-GREEN-REFACTOR for each, outside this workflow)

**Structure fixes (for later execution phase):**
- Remove: [count] duplicate skills
- Merge: [count] partial duplicates
- Update router: [Yes/No]
```

## Decision Gate

Present scorecard and report to user:

**If Critical:**
- Explain rebuild vs. enhance trade-offs
- Get user decision before proceeding

**If Major/Minor/Pass:**
- Present findings
- Confirm user wants to proceed with Pass 2 (content testing)

## Proceeding to Next Stage

After scorecard approval:
- If proceeding → Move to `testing-skill-quality.md` (Pass 2)
- If rebuilding → Stop maintenance workflow, switch to creation workflow
- If canceling → Stop workflow

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Scorecard too lenient | Be honest: missing 50% of core = Critical |
| Vague gap descriptions | Draft actual skill names and descriptions |
| Keeping all duplicates | Duplicates confuse users - merge or remove |
| Ignoring faction drift | Faction identity matters - flag misalignment |
| Skipping metadata check | Inaccurate metadata breaks discovery |