Code Protection Skill

What This Skill Does

Systematically annotates passing code with protection levels to prevent regressions:

• •Reviews manual test results to identify passing features
• •Annotates code with appropriate protection levels
• •Documents protected files in CODE_PROTECTION_POLICY.md
• •Creates bug tasks for failing features
• •Establishes baseline for pre-commit enforcement

Protection Levels

@immutable - Never change

• •Stable APIs that must remain backward compatible
• •External integrations (Whisper API, GitHub API)
• •Core data structures referenced across codebase
• •Use when: Breaking changes would affect users or external systems

@protected - Refactor only

• •Working features that pass manual tests
• •Can be refactored for performance/clarity
• •Cannot change behavior without approval
• •Use when: Feature works correctly, needs protection from regressions

@maintainable - Bug fixes allowed

• •Features with known bugs but working core functionality
• •Can be modified to fix bugs
• •Behavior changes allowed with justification
• •Use when: Feature mostly works but has edge case issues

When Claude Should Use This

Use this skill when the user:

• •Says "annotate passing code" or "protect working features"
• •Wants to lock down stable functionality
• •Mentions "prevent regressions" or "code protection"
• •References PROTECT-001 task or Phase 0 stabilization
• •Has completed manual testing and wants to protect passing features

Workflow Process

1. Review Manual Test Results

Read test documentation:

# Look for manual test results
find . -name "MANUAL_TEST*.md" -o -name "TEST_RESULTS*.md"

Identify passing features:

• •Review each test case
• •Mark tests as: ✅ PASS, ❌ FAIL, ⚠️ PARTIAL
• •Extract passing feature list
• •Note failing features for bug tasks

Example test result format:

## Test 1: Voice Panel
✅ Opens with backtick key
✅ Recording works
❌ Transcription fails (timeout error)
⚠️ Insert to editor works but slow

Verdict: PARTIAL - Core functionality works, needs performance fix

2. Analyze Code for Protection Level

For each passing feature, determine protection level:

Choose @immutable if:

• •External API calls (Whisper, GitHub, npm)
• •Data formats that persist (TOML schema, JSON config)
• •CLI commands that users depend on
• •Extension activation sequence
• •Breaking changes would affect users

Choose @protected if:

• •UI components that work correctly
• •Feature workflows that pass tests
• •Services with correct business logic
• •Can be refactored but behavior must stay same
• •Most common protection level

Choose @maintainable if:

• •Features with known bugs
• •Partial test passes
• •Needs improvement but core works
• •Bug fixes expected

3. Annotate Code with Protection Comments

Annotation format:

/**
 * @protected
 * Locked: 2025-11-06 (v0.16.7)
 * Test: MANUAL_TEST_v0.16.7.md - Test 2.1 (Voice Panel opens with backtick)
 * Status: PASSING - Core functionality works
 *
 * Voice panel activation via backtick key.
 * DO NOT modify without approval - breaks user workflow.
 */
export function activateVoicePanel() {
    // implementation
}

For @immutable APIs:

/**
 * @immutable
 * Locked: 2025-11-06 (v0.16.7)
 * API: External Whisper API integration
 * Status: STABLE - Backward compatible
 *
 * Whisper API client for transcription.
 * NEVER change interface - external dependency.
 */
export class WhisperClient {
    // implementation
}

For @maintainable code:

/**
 * @maintainable
 * Locked: 2025-11-06 (v0.16.7)
 * Test: MANUAL_TEST_v0.16.7.md - Test 3.2 (Sprint loader partial pass)
 * Status: PARTIAL - Works but has bugs
 * Known issues: Slow loading (>2s), occasional TOML parse errors
 *
 * Sprint loader service.
 * Bug fixes allowed - performance and parsing issues known.
 */
export class SprintLoader {
    // implementation
}

Placement rules:

• •Place annotation IMMEDIATELY before function/class/export
• •Include lock date (today's date)
• •Reference test case from manual test document
• •Note status (PASSING, STABLE, PARTIAL)
• •Explain why protected and what breaks if changed

4. Document in CODE_PROTECTION_POLICY.md

Create or update the protection policy document:

# Code Protection Policy

**Status:** ✅ ACTIVE (v0.16.7 - 2025-11-06)

## Protected Files

### @immutable Files (Never Change)
| File | Lock Date | Test Reference | Reason |
|------|-----------|----------------|--------|
| vscode-lumina/src/services/whisperClient.ts | 2025-11-06 | Test 1.1 | External API integration |
| vscode-lumina/src/services/githubClient.ts | 2025-11-06 | Test 4.2 | GitHub API integration |

### @protected Files (Refactor Only)
| File | Lock Date | Test Reference | Reason |
|------|-----------|----------------|--------|
| vscode-lumina/src/extension.ts | 2025-11-06 | Test 1.0 | Extension activation |
| vscode-lumina/src/commands/SprintLoader.ts | 2025-11-06 | Test 2.3 | Sprint loading |
| vscode-lumina/src/services/AutoTerminalSelector.ts | 2025-11-06 | Test 3.1 | Terminal selection |

### @maintainable Files (Bug Fixes Allowed)
| File | Lock Date | Test Reference | Known Issues |
|------|-----------|----------------|--------------|
| vscode-lumina/src/commands/voicePanel.ts | 2025-11-06 | Test 1.2 | Slow insert, timeout errors |

## Enforcement

Protection enforced via:
1. Pre-commit hook (validates protection on commit)
2. Static analysis (scripts/validate-protection.js)
3. Code review (reviewer checks for unauthorized changes)
4. CI/CD pipeline (blocks merges with protection violations)

## Override Process

If you need to modify protected code:

1. **Document justification** in commit message:

PROTECTED: Fix critical bug in WhisperClient

Justification: Whisper API changed, breaking compatibility. Files modified: vscode-lumina/src/services/whisperClient.ts Protection level: @immutable → requires architecture approval Approval: [Reference issue/PR/discussion]

2. **Get approval** (based on protection level):
- @immutable: Architecture review + user impact assessment
- @protected: Technical lead approval
- @maintainable: Self-approval (document justification)

3. **Update tests** after change:
- Re-run manual tests
- Update test document with new results
- Update protection annotation if status changes

## Audit Trail

View protection changes via git log:
```bash
# Show all protected code changes
git log --grep="PROTECTED:" --oneline

# Show changes to specific protected file
git log --grep="PROTECTED:" -- vscode-lumina/src/services/whisperClient.ts

### 5. Create Bug Tasks for Failing Features

**For each failing test, create a bug task:**

**Task format:**
```toml
[tasks.BUG-001]
id = "BUG-001"
name = "Fix voice panel transcription timeout"
phase = "phase-0b-ux-polish"
assigned_engineer = "engineer_1"
status = "pending"
description = "Transcription fails with timeout error after 30s"
estimated_lines = 50
estimated_time = "1-2 hours"
dependencies = ["PROTECT-001"]
agent = "infrastructure-agent"

deliverables = [
    "Increase timeout to 60s",
    "Add retry logic (3 attempts)",
    "Update error message to be user-friendly",
    "Test with long recordings (>2min)"
]

validation_criteria = [
    "Transcription completes for 2min recording",
    "Timeout error no longer occurs",
    "Retry logic works (verify in logs)"
]

why = """
Manual test Test 1.3 failed: Transcription timeout after 30s.
Whisper API can take 45-60s for long recordings.
Needs longer timeout + retry for reliability.
"""

context = """
Test reference: MANUAL_TEST_v0.16.7.md - Test 1.3
Error: "Whisper API timeout after 30000ms"
File: vscode-lumina/src/services/whisperClient.ts:142

Current timeout: 30s
Whisper API avg response: 15-45s (varies by length)
Long recordings (>2min): 45-60s response time

Fix: Increase timeout to 60s, add 3-retry logic
"""

Add bug tasks to sprint TOML:

• •Group under phase-0b-ux-polish
• •Depend on PROTECT-001 (after protection annotations)
• •Assign to appropriate agent
• •Include test reference and error details

6. Verify Protection Annotations

Run validation script (after PROTECT-002 completes):

node scripts/validate-protection.js

Manual verification checklist:

• • All passing features annotated
• • Protection level appropriate for each file
• • Annotations include lock date + test reference
• • CODE_PROTECTION_POLICY.md lists all protected files
• • Bug tasks created for all failing features
• • Each bug task references test case

Example: Complete Protection Workflow

Scenario: Protect Voice Panel feature after manual testing

Step 1: Review test results

# MANUAL_TEST_v0.16.7.md

## Test 1: Voice Panel
1.1 Open panel with backtick key → ✅ PASS
1.2 Start recording → ✅ PASS
1.3 Stop recording → ✅ PASS
1.4 Transcribe audio → ❌ FAIL (timeout)
1.5 Insert into editor → ✅ PASS

Verdict: PARTIAL - 4/5 pass, transcription timeout issue

Step 2: Determine protection levels

• •Voice panel activation (Test 1.1) → @protected (UI feature, works)
• •Recording logic (Test 1.2-1.3) → @protected (core feature, works)
• •Transcription (Test 1.4) → @maintainable (has bug, needs fix)
• •Editor insertion (Test 1.5) → @protected (works, but slow)

Step 3: Annotate code

File: vscode-lumina/src/commands/voicePanel.ts

/**
 * @protected
 * Locked: 2025-11-06 (v0.16.7)
 * Test: MANUAL_TEST_v0.16.7.md - Test 1.1
 * Status: PASSING
 *
 * Activates voice panel when backtick key pressed.
 * DO NOT modify without approval - user workflow depends on this.
 */
export function activateVoicePanel() { ... }

/**
 * @maintainable
 * Locked: 2025-11-06 (v0.16.7)
 * Test: MANUAL_TEST_v0.16.7.md - Test 1.4 (FAIL)
 * Status: PARTIAL - Timeout errors on long recordings
 * Known issue: 30s timeout too short for Whisper API
 *
 * Transcription logic - bug fix needed for timeout.
 */
async function transcribeAudio() { ... }

Step 4: Update CODE_PROTECTION_POLICY.md

## @protected Files
- vscode-lumina/src/commands/voicePanel.ts (activateVoicePanel) - Test 1.1

## @maintainable Files
- vscode-lumina/src/commands/voicePanel.ts (transcribeAudio) - Test 1.4 (timeout bug)

Step 5: Create bug task

[tasks.BUG-001]
id = "BUG-001"
name = "Fix transcription timeout"
# ... (see format above)

Step 6: Commit

git add vscode-lumina/src/commands/voicePanel.ts docs/CODE_PROTECTION_POLICY.md internal/sprints/ACTIVE_SPRINT.toml
git commit -m "PROTECT-001: Annotate voice panel with protection levels

- @protected: activateVoicePanel (Test 1.1 PASS)
- @maintainable: transcribeAudio (Test 1.4 FAIL - timeout)
- Created BUG-001 for transcription timeout fix
- Updated CODE_PROTECTION_POLICY.md

Files: 3 files changed, 45 insertions(+)"

Integration with Other Protection Tasks

PROTECT-001 → PROTECT-002 → PROTECT-003

1. •PROTECT-001 (This Skill): Annotate code with protection levels
2. •PROTECT-002: Build pre-commit enforcement (validates annotations)
3. •PROTECT-003: Complete CODE_PROTECTION_POLICY.md documentation

After PROTECT-002 completes:

• •Pre-commit hook will validate protection annotations
• •Modifications to @protected files will require approval
• •Commit messages must include "PROTECTED:" prefix
• •Audit trail in git log

After PROTECT-003 completes:

• •CODE_PROTECTION_POLICY.md fully documented
• •Developers know override process
• •Enforcement mechanisms explained
• •Audit commands available

Related Files

• •internal/sprints/ACTIVE_SPRINT.toml - PROTECT-001 task definition
• •docs/CODE_PROTECTION_POLICY.md - Protection policy (created by this skill)
• •scripts/validate-protection.js - Validation script (created in PROTECT-002)
• •.git/hooks/pre-commit - Pre-commit enforcement (updated in PROTECT-002)
• •.claude/CLAUDE.md - Known Issues section (references historical bugs)

Historical Context

Why code protection is critical:

v0.13.23: Native dependency broke extension (9 hours to fix)

• •Added @nut-tree-fork/nut-js to package.json
• •Extension activation failed for all users
• •Required replacing with VS Code APIs
• •Prevention: @immutable annotation on package.json dependencies

v0.15.31-32: Runtime npm dependency broke extension (2 hours to fix)

• •Added glob package at runtime
• •Extension excluded it via --no-dependencies flag
• •Activation failed for all users
• •Prevention: @protected annotation on dependency imports

Protection prevents repeat of costly bugs.

Pattern: Lock down working code, fix bugs separately, prevent regressions.

Tips

Start with high-impact files:

1. •extension.ts (activation)
2. •whisperClient.ts (external API)
3. •Core services (sprint loading, terminal selection)
4. •Working UI features

Batch annotations by file:

• •Annotate all functions in one file together
• •Keep protection consistent within a file
• •Update CODE_PROTECTION_POLICY.md after each file

Create bug tasks immediately:

• •Don't delay bug task creation
• •Include all failing tests
• •Reference original test document
• •Group in phase-0b-ux-polish

Document reasoning:

• •Explain why this protection level
• •Note what breaks if changed
• •Reference test case
• •Include status (PASSING/STABLE/PARTIAL)