claudetools/.claude/SCHEMA_MSP.md

SCHEMA_MSP.md

Source: MSP-MODE-SPEC.md Section: MSP Work Tracking Tables Date: 2026-01-15

Overview

MSP work tracking tables for detailed session work items, task management, and work details tracking. These tables capture granular information about work performed during MSP sessions.

---

MSP Work Tracking Tables

work_items

Individual tasks/actions within sessions (granular tracking).

CREATE TABLE work_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    category VARCHAR(50) NOT NULL CHECK(category IN (
        'infrastructure', 'troubleshooting', 'configuration',
        'development', 'maintenance', 'security', 'documentation'
    )),
    title VARCHAR(500) NOT NULL,
    description TEXT NOT NULL,
    status VARCHAR(50) DEFAULT 'completed' CHECK(status IN (
        'completed', 'in_progress', 'blocked', 'pending', 'deferred'
    )),
    priority VARCHAR(20) CHECK(priority IN ('critical', 'high', 'medium', 'low')),
    is_billable BOOLEAN DEFAULT false,
    estimated_minutes INTEGER,
    actual_minutes INTEGER,
    affected_systems TEXT, -- JSON array: ["jupiter", "172.16.3.20"]
    technologies_used TEXT, -- JSON array: ["docker", "mariadb"]
    item_order INTEGER, -- sequence within session
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP,

    INDEX idx_work_items_session (session_id),
    INDEX idx_work_items_category (category),
    INDEX idx_work_items_status (status)
);

Categories distribution (from analysis):

• Infrastructure: 30%
• Troubleshooting: 25%
• Configuration: 15%
• Development: 15%
• Maintenance: 10%
• Security: 5%

---

Work Details Tracking Tables (6 tables)

file_changes

Track files created/modified/deleted during sessions.

CREATE TABLE file_changes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    file_path VARCHAR(1000) NOT NULL,
    change_type VARCHAR(50) CHECK(change_type IN (
        'created', 'modified', 'deleted', 'renamed', 'backed_up'
    )),
    backup_path VARCHAR(1000),
    size_bytes BIGINT,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_file_changes_work_item (work_item_id),
    INDEX idx_file_changes_session (session_id)
);

---

commands_run

Shell/PowerShell/SQL commands executed (enhanced with failure tracking).

CREATE TABLE commands_run (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    command_text TEXT NOT NULL,
    host VARCHAR(255), -- where executed: "jupiter", "172.16.3.20"
    shell_type VARCHAR(50), -- "bash", "powershell", "sql", "docker"
    success BOOLEAN,
    output_summary TEXT, -- first/last lines or error

    -- Failure tracking (new)
    exit_code INTEGER, -- non-zero indicates failure
    error_message TEXT, -- full error text
    failure_category VARCHAR(100), -- "compatibility", "permission", "syntax", "environmental"
    resolution TEXT, -- how it was fixed (if resolved)
    resolved BOOLEAN DEFAULT false,

    execution_order INTEGER, -- sequence within work item
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_commands_work_item (work_item_id),
    INDEX idx_commands_session (session_id),
    INDEX idx_commands_host (host),
    INDEX idx_commands_success (success),
    INDEX idx_commands_failure_category (failure_category)
);

---

infrastructure_changes

Audit trail for infrastructure modifications.

CREATE TABLE infrastructure_changes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    infrastructure_id UUID REFERENCES infrastructure(id) ON DELETE SET NULL,
    change_type VARCHAR(50) CHECK(change_type IN (
        'dns', 'firewall', 'routing', 'ssl', 'container',
        'service_config', 'hardware', 'network', 'storage'
    )),
    target_system VARCHAR(255) NOT NULL,
    before_state TEXT,
    after_state TEXT,
    is_permanent BOOLEAN DEFAULT true,
    rollback_procedure TEXT,
    verification_performed BOOLEAN DEFAULT false,
    verification_notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_infra_changes_work_item (work_item_id),
    INDEX idx_infra_changes_session (session_id),
    INDEX idx_infra_changes_infrastructure (infrastructure_id)
);

---

problem_solutions

Issue tracking with root cause and resolution.

CREATE TABLE problem_solutions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    problem_description TEXT NOT NULL,
    symptom TEXT, -- what user saw
    error_message TEXT, -- exact error code/message
    investigation_steps TEXT, -- JSON array of diagnostic commands
    root_cause TEXT,
    solution_applied TEXT NOT NULL,
    verification_method TEXT,
    rollback_plan TEXT,
    recurrence_count INTEGER DEFAULT 1, -- if same problem reoccurs
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_problems_work_item (work_item_id),
    INDEX idx_problems_session (session_id)
);

---

deployments

Track software/config deployments.

CREATE TABLE deployments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    infrastructure_id UUID REFERENCES infrastructure(id) ON DELETE SET NULL,
    service_id UUID REFERENCES services(id) ON DELETE SET NULL,
    deployment_type VARCHAR(50) CHECK(deployment_type IN (
        'code', 'config', 'database', 'container', 'service_restart'
    )),
    version VARCHAR(100),
    description TEXT,
    deployed_from VARCHAR(500), -- source path or repo
    deployed_to VARCHAR(500), -- destination
    rollback_available BOOLEAN DEFAULT false,
    rollback_procedure TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_deployments_work_item (work_item_id),
    INDEX idx_deployments_infrastructure (infrastructure_id),
    INDEX idx_deployments_service (service_id)
);

---

database_changes

Track database schema/data modifications.

CREATE TABLE database_changes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    work_item_id UUID NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
    session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
    database_name VARCHAR(255) NOT NULL,
    infrastructure_id UUID REFERENCES infrastructure(id) ON DELETE SET NULL,
    change_type VARCHAR(50) CHECK(change_type IN (
        'schema', 'data', 'index', 'optimization', 'cleanup', 'migration'
    )),
    sql_executed TEXT,
    rows_affected BIGINT,
    size_freed_bytes BIGINT, -- for cleanup operations
    backup_taken BOOLEAN DEFAULT false,
    backup_location VARCHAR(500),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_db_changes_work_item (work_item_id),
    INDEX idx_db_changes_database (database_name)
);

---

Relationships

• sessions → work_items (one-to-many): Each session contains multiple work items
• work_items → file_changes (one-to-many): Track files modified in each work item
• work_items → commands_run (one-to-many): Commands executed for each work item
• work_items → infrastructure_changes (one-to-many): Infrastructure changes made
• work_items → problem_solutions (one-to-many): Problems solved in work item
• work_items → deployments (one-to-many): Deployments performed
• work_items → database_changes (one-to-many): Database modifications
• work_items ↔ tags (many-to-many via work_item_tags)

---

Work Item Categorization

Auto-Categorization Logic

As work progresses, agents analyze conversation and actions to categorize work:

Keyword Triggers:

• infrastructure: "ssh", "docker restart", "service", "server", "network"
• troubleshooting: "error", "not working", "broken", "failed", "issue"
• configuration: "configure", "setup", "change settings", "modify"
• development: "build", "code", "implement", "create", "develop"
• maintenance: "cleanup", "optimize", "backup", "update", "patch"
• security: "malware", "breach", "unauthorized", "vulnerability", "firewall"

Information-Dense Data Capture

Work items use concise, structured descriptions:

Format:

Problem: [what was wrong]
Cause: [root cause if identified]
Fix: [solution applied]
Verify: [how confirmed]

Example:

Problem: ERR_SSL_PROTOCOL_ERROR on git.azcomputerguru.com
Cause: Certificate expired 2026-01-10
Fix: certbot renew && systemctl restart apache2
Verify: curl test successful, browser loads site

---

Billability Tracking

Auto-flag Billable Work

• Client work (non-internal) → is_billable = true by default
• Internal infrastructure → is_billable = false
• User can override with command: /billable false

Time Allocation

• Track time per work_item (start when created, end when completed)
• actual_minutes calculated from timestamps
• Aggregate to session total: billable_hours in sessions table

---

Cross-References

• Core Tables: See SCHEMA_CORE.md
• Infrastructure Details: See SCHEMA_INFRASTRUCTURE.md
• Credentials: See SCHEMA_CREDENTIALS.md
• Environmental Learning: See SCHEMA_CONTEXT.md
• External Integrations: See SCHEMA_INTEGRATIONS.md
• API Endpoints: See API_SPEC.md