name: master-plan-manager description: SAFE MASTER-PLAN MAINTENANCE - Intelligent master-plan file management with comprehensive analysis, backup, and validation. Reads entire file, detects changes, updates only when needed, maintains document integrity. Optimized for personal productivity app master-plans.

Master Plan Manager - Intelligent Document Maintenance

Version: 1.0.0 Category: Document Management / File Operations Related Skills: chief-architect, comprehensive-system-analyzer, qa-testing

Overview

A specialized skill for safe and intelligent master-plan file management. This skill reads entire master-plan documents, analyzes current content vs. needed updates, and applies changes only when meaningful improvements are detected. Implements comprehensive safety measures including backups, validation, and rollback capabilities.

Quick Context

• Complexity: Medium-High (File operations with safety validation)
• Duration: Variable (Based on update complexity)
• Dependencies: File system access, markdown parsing
• Safety: Comprehensive backup and validation procedures

Activation Triggers

• Keywords: master-plan, plan update, documentation, file analysis, document maintenance
• Files: /docs/master-plan/README.md and related planning documents
• Contexts: Chief-architect delegation, post-implementation updates, architectural decision documentation

🚨 CRITICAL SAFETY PROTOCOLS

MANDATORY File Safety Standards

DOCUMENT INTEGRITY FIRST: Never make changes without comprehensive analysis, backup creation, and validation procedures.

Before Any File Operations - MANDATORY Steps:

1. Complete File Analysis: Read entire current document before any changes
2. Backup Creation: Create timestamped backup before any modifications
3. Change Detection: Analyze if updates are actually needed
4. Content Validation: Verify markdown structure and integrity
5. Safety Check: Confirm changes won't damage existing content
6. Rollback Preparation: Ensure quick restoration capability
7. Integrity Verification: Validate document after changes

CRITICAL: No Blind Updates Protocol

• MANDATORY: Never make changes without reading complete current file
• MANDATORY: Always check if content already exists before adding
• MANDATORY: Validate updates are meaningful improvements
• BACKUP LOCATION: All backups stored with timestamps in /docs/master-plan/backups/

Core Capabilities

1. Intelligent Document Analysis

• Complete File Reading: Parse entire master-plan before any operations
• Content Structure Analysis: Understand existing sections and format
• Change Detection: Identify outdated, missing, or redundant content
• Currency Assessment: Determine what needs updating vs. what's current
• Redundancy Prevention: Avoid adding duplicate or unnecessary content

2. Safe Update Operations

• Read-First Approach: Never write without comprehensive analysis
• Incremental Updates: Apply changes section by section
• Content Merging: Integrate new information with existing content
• Format Preservation: Maintain existing structure and emoji usage
• Validation Gates: Multiple checkpoints to ensure safety

3. Comprehensive Safety Measures

• Automatic Backups: Timestamped backups before any changes
• Rollback Capability: Instant restore if issues detected
• Markdown Validation: Ensure proper formatting and structure
• Content Integrity: Verify no information is lost or corrupted
• Error Recovery: Graceful handling of file operation failures

4. Content Intelligence

• Semantic Analysis: Understand content meaning, not just text matching
• Context Awareness: Recognize existing documentation patterns
• Status Tracking: Monitor completion status and progress indicators
• Quality Standards: Maintain high documentation quality and consistency

Master-Plan Management Domains

Domain 1: Executive Summary Management

Focus Areas:

• Current State Assessment: Analyze project health and status indicators
• Brutal Honesty Updates: Update honest assessments with current data
• Success Criteria Refresh: Update measurable success criteria
• Immediate Actions: Maintain current prioritized action items

Domain 2: Phase Progress Tracking

Focus Areas:

• Phase Completion Status: Track and update phase progress with metrics
• Deliverable Documentation: Update created deliverables and evidence
• Validation Results: Document testing and validation outcomes
• Readiness Assessment: Update phase-to-phase readiness status

Domain 3: Architecture Decision Records (ADRs)

Focus Areas:

• Decision Documentation: Add new architectural decisions with full rationale
• Alternative Analysis: Document considered alternatives and trade-offs
• Impact Assessment: Track decision impact on user experience and system
• Status Updates: Update ADR status based on implementation outcomes

Domain 4: Skills Execution Tracking

Focus Areas:

• Skills Inventory: Update skills executed with actual outcomes
• Performance Metrics: Document quantified results and improvements
• Learning Capture: Update insights and patterns discovered
• Integration Status: Track how skills work together

Domain 5: Success Criteria Management

Focus Areas:

• Criteria Tracking: Monitor progress toward measurable success criteria
• Completion Evidence: Document proof of criteria fulfillment
• Metrics Updates: Update quantified metrics with current data
• Status Validation: Verify and document completion status

Safe Operations Workflow

Phase 1: Document Analysis

async analyzeMasterPlan(): Promise<PlanAnalysis> {
  // 1. Read complete current document
  const currentContent = await this.readEntireFile(this.planPath);

  // 2. Parse and understand structure
  const parsedStructure = this.parseMarkdownStructure(currentContent);

  // 3. Analyze content currency and completeness
  const contentAnalysis = {
    currentSections: parsedStructure.sections,
    outdatedContent: this.detectOutdatedContent(parsedStructure),
    missingContent: this.identifyMissingContent(parsedStructure),
    redundantAreas: this.identifyRedundantContent(parsedStructure)
  };

  // 4. Create safety backup
  await this.createTimestampedBackup(currentContent);

  return contentAnalysis;
}

Phase 2: Change Detection

async detectNeededChanges(analysis: PlanAnalysis, context: UpdateContext): Promise<NeededChange[]> {
  const neededChanges: NeededChange[] = [];

  // For each potential update, analyze if actually needed
  for (const potentialChange of this.generatePotentialChanges(context)) {
    const existingContent = analysis.currentSections[potentialChange.section];

    // Comprehensive need analysis
    const changeNeeded = !this.contentAlreadyExists(potentialChange, existingContent) &&
                        !this.contentIsCurrent(potentialChange, existingContent) &&
                        !this.wouldBeRedundant(potentialChange, existingContent) &&
                        this.representsMeaningfulImprovement(potentialChange, existingContent);

    if (changeNeeded) {
      neededChanges.push({
        ...potentialChange,
        rationale: this.explainWhyChangeNeeded(potentialChange, existingContent),
        impact: this.assessChangeImpact(potentialChange, existingContent),
        safetyChecks: this.generateSafetyChecks(potentialChange)
      });
    }
  }

  return neededChanges;
}

Phase 3: Safe Update Execution

async executeSafeUpdates(changes: NeededChange[]): Promise<UpdateResult> {
  const results: UpdateResult[] = [];

  // Process changes one at a time with validation
  for (const change of changes) {
    try {
      // 1. Pre-change validation
      await this.validatePreChangeConditions(change);

      // 2. Apply change with content preservation
      const updateResult = await this.applyChangeSafely(change);

      // 3. Post-change validation
      await this.validatePostChangeIntegrity(updateResult);

      // 4. Verify document integrity
      await this.validateDocumentIntegrity();

      results.push(updateResult);

    } catch (error) {
      // 5. Rollback if any issues
      await this.rollbackChange(change, error);
      throw new SafeUpdateError(`Change failed and was rolled back: ${error.message}`, change);
    }
  }

  return {
    totalChanges: changes.length,
    successfulChanges: results.length,
    documentIntegrity: await this.verifyDocumentIntegrity(),
    backupLocation: this.currentBackupPath
  };
}

Integration with Chief-Architect

Delegation Interface

The master-plan-manager skill accepts delegation from chief-architect through standardized interfaces:

Update with Implementation Results

interface ImplementationUpdateRequest {
  action: 'update-with-implementation-results';
  decision: PersonalAppDecision;
  results: PersonalImplementationResult;
  context: PersonalAppContext;
  safetyLevel: 'comprehensive' | 'standard' | 'quick';
}

Update with Architecture Decision

interface ArchitectureDecisionUpdateRequest {
  action: 'update-with-architecture-decision';
  decision: PersonalAppDecision;
  alternatives: AlternativeAnalysis[];
  rationale: DecisionRationale;
  impact: ImpactAssessment;
}

Update Progress Status

interface ProgressUpdateRequest {
  action: 'update-progress-status';
  phase: number;
  completion: CompletionStatus;
  deliverables: DeliverableRecord[];
  validation: ValidationResults;
}

Safety Validation Gates

Pre-Update Validation

• File Integrity: Verify current file is readable and valid markdown
• Backup Success: Confirm backup was created successfully
• Change Necessity: Verify change actually improves the document
• Format Compatibility: Ensure changes maintain existing structure
• Content Safety: Verify no valuable content will be lost

Post-Update Validation

• Markdown Integrity: Validate proper markdown formatting
• Link Validation: Ensure all internal links remain valid
• Structure Consistency: Verify document structure is maintained
• Content Accuracy: Validate updated content is correct
• Readability Check: Ensure document remains readable and organized

Error Recovery

• Automatic Rollback: Restore from backup if issues detected
• Partial Recovery: Handle partial updates gracefully
• Error Reporting: Clear reporting of what failed and why
• Manual Intervention: Provide clear information for manual fixes

Success Criteria

• ✅ Document Integrity: Master-plan remains valid and well-structured after all updates
• ✅ Content Accuracy: All updates are accurate and well-documented
• ✅ No Data Loss: No existing valuable content is ever lost
• ✅ Redundancy Prevention: No duplicate or unnecessary content is added
• ✅ Safety Compliance: All safety protocols are followed for every operation
• ✅ Backup Reliability: All backups are created and can be restored successfully
• ✅ Integration Success: Seamless integration with chief-architect delegation

Usage Examples

Example 1: Chief-Architect Delegation

chief-architect delegates to master-plan-manager:
  action: "update-with-implementation-results"
  decision: { decision: "implement-cross-tab-sync", rationale: "..." }
  results: { filesCreated: 5, testsPassed: 12, performanceImproved: "30%" }
  safetyLevel: "comprehensive"

Example 2: Architecture Decision Documentation

master-plan-manager update-architecture-decision:
  section: "Architecture Decision Records"
  decision: "Local-First Data Strategy"
  alternatives: ["IndexedDB", "LocalForage", "Custom Storage"]
  rationale: "Cross-tab sync requirements and offline-first priority"
  impact: { userExperience: "High", developmentComplexity: "Medium" }

Example 3: Progress Status Update

master-plan-manager update-progress:
  phase: 3
  completion: { percentage: 85, status: "near-complete" }
  deliverables: ["Cross-tab sync", "Performance optimization", "UI improvements"]
  validation: { testsPassed: "100%", performanceMet: true, userAccepted: true }

Implementation Protocol

1. Safety-First Analysis

• Always read complete current file before any operations
• Create timestamped backup before any changes
• Analyze if updates are actually needed and beneficial
• Verify no existing content will be damaged

2. Intelligent Updates

• Only update when meaningful improvements are detected
• Preserve existing structure, formatting, and valuable content
• Integrate new information seamlessly with existing content
• Maintain document quality and consistency standards

3. Comprehensive Validation

• Validate markdown structure and formatting
• Verify all internal and external links remain valid
• Ensure document remains readable and well-organized
• Confirm all safety protocols were followed

4. Error Recovery

• Automatic rollback to previous state if any issues detected
• Clear error reporting and manual intervention guidance
• Multiple recovery options for different failure scenarios
• Learning from errors to improve future operations

Master-Plan Manager Principles

1. Document Safety First: Never compromise document integrity or existing content
2. Read Before Writing: Never make changes without comprehensive analysis of current state
3. Meaningful Updates Only: Only update when changes represent genuine improvements
4. Backup and Recovery: Always maintain reliable backup and rollback capabilities
5. Format Preservation: Maintain existing document structure, formatting, and style
6. Content Intelligence: Understand context and meaning, not just text patterns
7. Integration Excellence: Work seamlessly with chief-architect and other skills
8. Continuous Learning: Improve from every operation and maintain operation history

Master-Plan Manager Cognitive Architecture

This skill implements the Safe Document Management cognitive architecture:

• Perception: Comprehensively reads and analyzes entire document structure and content
• Analysis: Understands context, identifies needs, detects redundancies, assesses currency
• Planning: Determines optimal update strategies while preserving document integrity
• Action: Applies changes safely with comprehensive validation and backup procedures
• Validation: Verifies document integrity, content accuracy, and structural consistency
• Learning: Maintains operation history and improves from each update experience
• Safety: Prioritizes document safety above all other considerations

This creates a highly reliable document management intelligence that maintains and improves master-plan documents while ensuring complete safety and integrity of existing content.

MANDATORY USER VERIFICATION REQUIREMENT

Policy: No Fix Claims Without User Confirmation

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:

Step 1: Technical Verification

• Run all relevant tests (build, type-check, unit tests)
• Verify no console errors
• Take screenshots/evidence of the fix

Step 2: User Verification Request

REQUIRED: Use the AskUserQuestion tool to explicitly ask the user to verify the fix:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

Step 3: Wait for User Confirmation

• DO NOT proceed with claims of success until user responds
• DO NOT mark tasks as "completed" without user confirmation
• DO NOT use phrases like "fixed", "resolved", "working" without user verification

Step 4: Handle User Feedback

• If user confirms: Document the fix and mark as complete
• If user reports issues: Continue debugging, repeat verification cycle

Prohibited Actions (Without User Verification)

• Claiming a bug is "fixed"
• Stating functionality is "working"
• Marking issues as "resolved"
• Declaring features as "complete"
• Any success claims about fixes

Required Evidence Before User Verification Request

1. Technical tests passing
2. Visual confirmation via Playwright/screenshots
3. Specific test scenarios executed
4. Clear description of what was changed

Remember: The user is the final authority on whether something is fixed. No exceptions.