Skill Simplify

Skill Simplify

Three-phase pipeline: analyze functional inventory, apply optimization rules, verify integrity.

Phase Reference Documents (read on-demand):

Input Processing

const targetPath = input.trim()
const targetFile = targetPath.endsWith('.md') ? targetPath : `${targetPath}/SKILL.md`
const originalContent = Read(targetFile)
const originalLineCount = originalContent.split('\n').length

TodoWrite Pattern

TodoWrite({ todos: [
  { content: `Phase 1: Analyzing ${targetFile}`, status: "in_progress", activeForm: "Extracting functional inventory" },
  { content: "Phase 2: Optimize", status: "pending" },
  { content: "Phase 3: Integrity Check", status: "pending" }
]})

Core Rules

1. Preserve ALL functional elements: Code blocks with logic, agent calls, data structures, routing, error handling, input/output specs 2. Only reduce descriptive content: Flowcharts, verbose comments, duplicate sections, examples that repeat logic 3. Never summarize algorithm logic: If-else branches, function bodies, schemas must remain verbatim 4. Classify code blocks: Distinguish functional (logic, routing, schemas) from descriptive (ASCII art, examples, display templates) — only descriptive blocks may be deleted 5. Merge equivalent variants: Single/multi-perspective templates differing only by a parameter → one template with variant comment 6. Fix format issues: Nested backtick template literals in code fences → convert to prose; hardcoded option lists → flag for dynamic generation; workflow handoff references → ensure execution steps present 7. Validate pseudo-code: Check bracket matching, variable consistency, structural completeness 8. Quantitative verification: Phase 3 counts must match Phase 1 counts for functional categories; descriptive block decreases are expected

Error Handling

Phase 1: Functional Analysis

Read target file, extract functional inventory with code block classification, identify redundancy, validate pseudo-code format, and produce optimization plan.

Objective

• Build quantitative functional inventory with code block classification (baseline for Phase 3)
• Identify redundancy categories with specific line ranges
• Detect pseudo-code format issues
• Produce optimization plan with estimated line savings

Execution

Step 1.1: Read & Measure Target

const originalContent = Read(targetFile)
const lines = originalContent.split('\n')
const originalLineCount = lines.length

Step 1.2: Extract Functional Inventory

Count and catalog every functional element. These counts are the baseline for Phase 3 verification.

const inventory = {
  // Code structures — with role classification
  codeBlocks: [],        // { startLine, endLine, language, purpose, role: 'functional'|'descriptive' }
  agentCalls: [],        // { line, agentType, description, mergeGroup?: string }
  dataStructures: [],    // { line, name, type: 'object'|'array'|'schema' }

  // Logic elements
  routingBranches: [],   // { line, condition, outcomes[] }
  errorHandlers: [],     // { line, errorType, resolution }
  conditionalLogic: [],  // { line, condition, trueAction, falseAction }

  // Interface elements
  askUserQuestions: [],   // { line, questionCount, headers[], optionType: 'static'|'dynamic' }
  inputModes: [],        // { line, mode, description }
  outputArtifacts: [],   // { line, artifact, format }

  // Structural elements
  todoWriteBlocks: [],   // { line, phaseCount }
  phaseHandoffs: [],     // { line, fromPhase, toPhase }
  skillInvocations: [],  // { line, skillName, hasExecutionSteps: boolean }

  // Reference elements
  tables: [],            // { startLine, endLine, columns }
  schemas: [],           // { line, schemaName, fields[] }

  // Format issues
  formatIssues: [],      // { line, type, description, severity: 'error'|'warning' }

  // Totals (computed)
  counts: {}
}

Extraction rules:

• Code blocks: Match `language ... ` pairs, record start/end/language/first-line-as-purpose
• Agent calls: Match Agent(, Task(, subagent_type=, record type and prompt summary
• Data structures: Match const xxx = {, const xxx = [, JSON schema objects
• Routing branches: Match if/else, switch/case, ternary ? : with meaningful branching
• Error handlers: Match catch, error table rows | Error |, fallback patterns
• AskUserQuestion: Match AskUserQuestion({, count questions array length
• Input modes: Match Mode 1/2/3, --flag, argument parsing
• Output artifacts: Match Write(, Output:, file path patterns in comments
• TodoWrite: Match TodoWrite({, count todo items
• Phase handoffs: Match Read("phases/, Skill(, proceed_to_next_phase
• Tables: Match | header | markdown table blocks
• Schemas: Match schema references, JSON structure definitions

Step 1.2.1: Code Block Role Classification

For each code block, determine its role:

Classification rules:

• If block contains ANY of: Agent(, Bash(, AskUserQuestion(, if (, switch, Skill(, Write(, Read(, TodoWrite( → functional
• If block language is bash and content is only example invocations (no logic) → descriptive
• If block has no language tag and contains only ASCII box-drawing characters → descriptive
• If block is labeled as "Example" in surrounding markdown heading → descriptive
• Default: functional (conservative)

Step 1.2.2: Pseudo-Code Format Validation

Scan all functional code blocks for format issues:

inventory.formatIssues = validatePseudoCode(inventory.codeBlocks.filter(b => b.role === 'functional'))

Step 1.2.3: Compute Totals

inventory.counts = {
  codeBlocks: inventory.codeBlocks.length,
  functionalCodeBlocks: inventory.codeBlocks.filter(b => b.role === 'functional').length,
  descriptiveCodeBlocks: inventory.codeBlocks.filter(b => b.role === 'descriptive').length,
  agentCalls: inventory.agentCalls.length,
  dataStructures: inventory.dataStructures.length,
  routingBranches: inventory.routingBranches.length,
  errorHandlers: inventory.errorHandlers.length,
  conditionalLogic: inventory.conditionalLogic.length,
  askUserQuestions: inventory.askUserQuestions.length,
  inputModes: inventory.inputModes.length,
  outputArtifacts: inventory.outputArtifacts.length,
  todoWriteBlocks: inventory.todoWriteBlocks.length,
  phaseHandoffs: inventory.phaseHandoffs.length,
  skillInvocations: inventory.skillInvocations.length,
  tables: inventory.tables.length,
  schemas: inventory.schemas.length,
  formatIssues: inventory.formatIssues.length
}

Step 1.3: Identify Redundancy Categories

Scan for each category, record specific line ranges:

const redundancyMap = {
  deletable: [],       // { category, startLine, endLine, reason, estimatedSave }
  simplifiable: [],    // { category, startLine, endLine, strategy, estimatedSave }
  mergeable: [],       // { items: [{startLine, endLine}], mergeStrategy, estimatedSave }
  formatFixes: [],     // { line, type, fix }
  languageUnify: []    // { line, currentLang, targetLang }
}

Deletable (remove entirely, no functional loss):

Simplifiable (compress, preserve meaning):

Mergeable (combine related structures):

Format fixes (pseudo-code quality):

Language unification:

• Detect mixed Chinese/English in functional comments
• Recommend consistent language (match majority)

Step 1.4: Build Optimization Plan

const optimizationPlan = {
  targetFile,
  originalLineCount,
  estimatedReduction: redundancyMap.deletable.reduce((s, d) => s + d.estimatedSave, 0)
    + redundancyMap.simplifiable.reduce((s, d) => s + d.estimatedSave, 0)
    + redundancyMap.mergeable.reduce((s, d) => s + d.estimatedSave, 0),
  categories: {
    deletable: { count: redundancyMap.deletable.length, totalLines: '...' },
    simplifiable: { count: redundancyMap.simplifiable.length, totalLines: '...' },
    mergeable: { count: redundancyMap.mergeable.length, totalLines: '...' },
    formatFixes: { count: redundancyMap.formatFixes.length },
    languageUnify: { count: redundancyMap.languageUnify.length }
  },
  // Ordered: delete → merge → simplify → format
  operations: [
    ...redundancyMap.deletable.map(d => ({ type: 'delete', ...d, priority: 1 })),
    ...redundancyMap.mergeable.map(m => ({ type: 'merge', ...m, priority: 2 })),
    ...redundancyMap.simplifiable.map(s => ({ type: 'simplify', ...s, priority: 3 })),
    ...redundancyMap.formatFixes.map(f => ({ type: 'format', ...f, priority: 4 }))
  ]
}

Display plan summary: category counts, estimated reduction percentage, sections NOT changed (functional core).

Output

• Variable: analysisResult = { inventory, redundancyMap, optimizationPlan, originalContent, originalLineCount }
• TodoWrite: Mark Phase 1 completed, Phase 2 in_progress

Phase 2: Optimize

Apply simplification rules from analysisResult to produce optimized content. Write result to disk.

Objective

• Execute all optimization operations in priority order (delete → merge → simplify → format)
• Preserve every functional element identified in Phase 1 inventory
• Fix pseudo-code format issues
• Write optimized content back to target file

Pre-Step: Load Context

Run ccw spec load --category validation for verification rules and acceptance criteria to validate optimization preserves functional integrity.

Execution

Step 2.1: Apply Operations in Order

Process analysisResult.optimizationPlan.operations sorted by priority:

Priority 1 — Delete (safest, highest impact):

Priority 2 — Merge (structural optimization):

Priority 3 — Simplify (compress descriptive content):

Priority 4 — Format fixes (pseudo-code quality):

Step 2.2: Language Unification (if applicable)

if (analysisResult.redundancyMap.languageUnify.length > 0) {
  // Detect majority language, unify non-functional text
  // DO NOT change: variable names, function names, schema fields, error messages in code
}

Step 2.3: Write Optimized Content

Write(targetFile, optimizedContent)
const optimizedLineCount = optimizedContent.split('\n').length
const reduction = originalLineCount - optimizedLineCount
const reductionPct = Math.round(reduction / originalLineCount * 100)

Step 2.4: Preserve Optimization Record

const optimizationRecord = {
  deletedSections: [],    // section names removed
  mergedGroups: [],       // { from: [sections], to: description }
  simplifiedAreas: [],    // { section, strategy }
  formatFixes: [],        // { line, type, fix }
  linesBefore: originalLineCount,
  linesAfter: optimizedLineCount
}

Key Rules

1. Never modify functional code blocks — only compress comments/whitespace within them 2. Descriptive code blocks may be deleted if their content is covered by prose or tables 3. Never change function signatures, variable names, or schema fields 4. Merge preserves all branches — unified function must handle all original cases 5. When uncertain, keep original — conservative approach prevents functional loss 6. Format fixes must not alter semantics — only presentation changes

Output

• File: Target file overwritten with optimized content
• Variable: optimizationRecord (changes log for Phase 3)
• TodoWrite: Mark Phase 2 completed, Phase 3 in_progress

Phase 3: Integrity Check

Re-extract functional inventory from optimized file, compare against Phase 1 baseline, validate pseudo-code format. Report PASS/FAIL with detailed delta.

Objective

• Re-run the same inventory extraction on optimized content
• Compare counts using role-aware classification (functional vs descriptive)
• Validate pseudo-code format issues are resolved
• Report check result with actionable details
• Revert if critical functional elements are missing

Execution

Step 3.1: Re-Extract Inventory from Optimized File

const optimizedContent = Read(targetFile)
const optimizedLineCount = optimizedContent.split('\n').length

// Use SAME extraction logic as Phase 1 (including role classification)
const afterInventory = extractFunctionalInventory(optimizedContent)

Step 3.2: Compare Inventories (Role-Aware)

const beforeCounts = analysisResult.inventory.counts
const afterCounts = afterInventory.counts

const delta = {}
let hasCriticalLoss = false
let hasWarning = false

// CRITICAL: Functional elements that MUST NOT decrease
const CRITICAL = ['functionalCodeBlocks', 'dataStructures', 'routingBranches',
                  'errorHandlers', 'conditionalLogic', 'askUserQuestions',
                  'inputModes', 'outputArtifacts', 'skillInvocations']

// MERGE_AWARE: May decrease due to valid merge operations — verify coverage
const MERGE_AWARE = ['agentCalls', 'codeBlocks']

// EXPECTED_DECREASE: May decrease from merge/consolidation
const EXPECTED_DECREASE = ['descriptiveCodeBlocks', 'todoWriteBlocks',
                           'phaseHandoffs', 'tables', 'schemas']

for (const [key, before] of Object.entries(beforeCounts)) {
  const after = afterCounts[key] || 0
  const diff = after - before
  let category, status

  if (CRITICAL.includes(key)) {
    category = 'critical'
    status = diff < 0 ? 'FAIL' : 'OK'
    if (diff < 0) hasCriticalLoss = true
  } else if (MERGE_AWARE.includes(key)) {
    category = 'merge_aware'
    // Decrease is WARN (needs justification), not FAIL
    status = diff < 0 ? 'WARN' : 'OK'
    if (diff < 0) hasWarning = true
  } else {
    category = 'expected'
    status = 'OK'  // Descriptive decreases are expected
  }

  delta[key] = { before, after, diff, category, status }
}

Step 3.3: Deep Verification

For CRITICAL categories with decrease — identify exactly what was lost:

if (hasCriticalLoss) {
  const lostElements = {}
  for (const [key, d] of Object.entries(delta)) {
    if (d.status === 'FAIL') {
      const beforeItems = analysisResult.inventory[key]
      const afterItems = afterInventory[key]
      lostElements[key] = beforeItems.filter(beforeItem =>
        !afterItems.some(afterItem => matchesElement(beforeItem, afterItem))
      )
    }
  }
}

For MERGE_AWARE categories with decrease — verify merged coverage:

if (hasWarning) {
  for (const [key, d] of Object.entries(delta)) {
    if (d.category === 'merge_aware' && d.diff < 0) {
      // Check if merged template covers all original variants
      // e.g., single Agent template with "// For multi: add Perspective" covers both
      const beforeItems = analysisResult.inventory[key]
      const afterItems = afterInventory[key]
      const unmatched = beforeItems.filter(beforeItem =>
        !afterItems.some(afterItem => matchesElement(beforeItem, afterItem))
      )
      if (unmatched.length > 0) {
        // Check if unmatched items are covered by merge comments in remaining items
        const mergeComments = afterItems.flatMap(item => extractMergeComments(item))
        const trulyLost = unmatched.filter(item =>
          !mergeComments.some(comment => coversElement(comment, item))
        )
        if (trulyLost.length > 0) {
          delta[key].status = 'FAIL'
          hasCriticalLoss = true
          delta[key].trulyLost = trulyLost
        }
        // else: merge-covered, WARN is correct
      }
    }
  }
}

Step 3.4: Pseudo-Code Format Validation

const afterFormatIssues = validatePseudoCode(afterInventory.codeBlocks.filter(b => b.role === 'functional'))
const beforeFormatCount = analysisResult.inventory.formatIssues.length
const afterFormatCount = afterFormatIssues.length

const formatDelta = {
  before: beforeFormatCount,
  after: afterFormatCount,
  resolved: beforeFormatCount - afterFormatCount,
  newIssues: afterFormatIssues.filter(issue =>
    !analysisResult.inventory.formatIssues.some(orig => orig.line === issue.line && orig.type === issue.type)
  )
}

// New format issues introduced by optimization = FAIL
if (formatDelta.newIssues.length > 0) {
  hasCriticalLoss = true
}

Pseudo-code validation checks:

Step 3.5: Generate Check Report

const status = hasCriticalLoss ? 'FAIL' : (hasWarning ? 'WARN' : 'PASS')

const checkReport = {
  status,
  linesBefore: analysisResult.originalLineCount,
  linesAfter: optimizedLineCount,
  reduction: `${analysisResult.originalLineCount - optimizedLineCount} lines (-${Math.round((analysisResult.originalLineCount - optimizedLineCount) / analysisResult.originalLineCount * 100)}%)`,
  delta,
  formatDelta,
  lostElements: hasCriticalLoss ? lostElements : null
}

// Display report table
// | Category | Before | After | Delta | Status |
// Show all categories, highlight FAIL/WARN rows
// Show format issues summary if any

Step 3.6: Act on Result

if (status === 'FAIL') {
  Write(targetFile, analysisResult.originalContent)
  // Report: "Critical elements lost / new format issues introduced. Reverted."
}

if (status === 'WARN') {
  // Report: "Decreases from merge/descriptive removal. Verify coverage."
  // Show merge justifications for MERGE_AWARE categories
}

if (status === 'PASS') {
  // Report: "All functional elements preserved. Optimization successful."
}

Element Matching Rules

How matchesElement() determines if a before-element exists in after-inventory:

Merge coverage check (coversElement()):

• Agent calls: Merged template contains // For multi: or // Multi-perspective: comment referencing the missing variant
• Code blocks: Merged block contains comment noting the alternative was folded in

Completion

TodoWrite({ todos: [
  { content: `Phase 1: Analysis [${Object.keys(analysisResult.inventory.counts).length} categories]`, status: "completed" },
  { content: `Phase 2: Optimize [${checkReport.reduction}]`, status: "completed" },
  { content: `Phase 3: Check [${checkReport.status}] | Format: ${formatDelta.resolved} resolved, ${formatDelta.newIssues.length} new`, status: "completed" }
]})