Log Auditor

Log Auditor Skill

This skill is used for:

• Initial adoption: Analyzing unmanaged logs in existing projects
• VCS cleanup: Finding logs in version control that should be archived
• Regular health checks: Ensuring logs properly managed
• Storage optimization: Calculating savings from hybrid retention

You generate specifications that can be followed to bring log management into alignment with fractary-logs best practices.

IMPORTANT: Use Spec Plugin When Available

• Check if fractary-spec plugin is installed
• If available: Use spec-manager to generate standardized spec
• If not available: Generate basic markdown spec
• Either way, output must be actionable

IMPORTANT: Respect Project-Specific Logs

• Focus on operational logs (build, deployment, debug, session)
• Leave application logs (structured logging) to application
• Identify logs that should be in cloud vs VCS
• Calculate storage savings accurately

Check if fractary-spec plugin is available:

if [ -f ".fractary/plugins/spec/config.json" ] || [ -d "plugins/spec" ]; then
  USE_SPEC_PLUGIN=true
else
  USE_SPEC_PLUGIN=false
fi

Step 2: Load Configuration

Load fractary-logs configuration (if exists):

• Project config: .fractary/plugins/logs/config.json
• Plugin defaults: plugins/logs/config/config.example.json
• Load .gitignore patterns

If config doesn't exist, note that configuration will need to be created.

Step 3: Discover Log State

Execute discovery scripts:

bash plugins/logs/skills/log-auditor/scripts/discover-logs.sh {project_root} {output_dir}/discovery-logs.json
bash plugins/logs/skills/log-auditor/scripts/discover-vcs-logs.sh {project_root} {output_dir}/discovery-vcs-logs.json
bash plugins/logs/skills/log-auditor/scripts/discover-patterns.sh {output_dir}/discovery-logs.json {output_dir}/discovery-patterns.json
bash plugins/logs/skills/log-auditor/scripts/analyze-storage.sh {output_dir}/discovery-logs.json {output_dir}/discovery-storage.json

Discovery Scripts Purpose:

discover-logs.sh:

• Find all log files and log-like files (*.log, *.txt in certain dirs, build outputs)
• Categorize by type: session, build, deployment, debug, test, other
• Record: path, size, last modified, managed/unmanaged status
• Output: JSON inventory of all logs

discover-vcs-logs.sh:

• Check which logs are tracked in version control (git)
• Cross-reference with .gitignore
• Identify logs that should be excluded but aren't
• Calculate repository size impact
• Output: JSON list of VCS logs with impact analysis

discover-patterns.sh:

• Analyze log file patterns and naming conventions
• Identify common log types (npm-debug.log, jest output, terraform logs)
• Detect log rotation patterns
• Map to fractary-logs categories
• Output: JSON pattern analysis

analyze-storage.sh:

• Calculate total storage used by logs
• Break down by category and managed status
• Calculate potential savings from:
  • Archival to cloud
  • Compression (60-70% reduction)
  • Hybrid retention (30 days local)
• Estimate cloud storage costs
• Output: JSON storage analysis

Step 4: Define the Standard

Define what proper fractary-logs management looks like (the target state):

Standard Configuration:

• fractary-logs initialized with config at .fractary/plugins/logs/config.json
• fractary-file configured for cloud storage (S3/R2)
• Hybrid retention strategy enabled (30 days local, archived to cloud)

Standard Directory Structure:

/logs/
├── .archive-index.json       # Archive metadata
├── sessions/                 # Session logs (*.md)
├── builds/                   # Build logs (npm-debug.log, etc.)
├── deployments/              # Deployment logs (terraform.log, etc.)
├── debug/                    # Debug logs
└── tests/                    # Test output logs

Standard Version Control:

• All /logs/ directories excluded in .gitignore
• No log files tracked in Git
• Historical logs removed from Git history (if applicable)

Standard Archival:

• Auto-archive enabled on issue close
• Auto-archive enabled for logs older than 30 days
• Compression enabled for logs > 1MB
• Archive index maintained and updated

Standard Integration:

• GitHub commenting enabled on archive
• FABER auto-capture enabled (if using FABER)
• Build/deployment logs automatically captured

Step 5: Analyze Current State vs Standard (Gap Analysis)

Load discovery results and explicitly compare against the standard:

Configuration Gaps

• Current: Check if config exists and is valid
• Standard: Config at .fractary/plugins/logs/config.json with hybrid retention
• Gap: Missing config? Invalid settings? No cloud storage configured?

Directory Structure Gaps

• Current: Where are logs actually located? (from discovery-logs.json)
• Standard: All logs in /logs/{category}/ directories
• Gap: Logs scattered across project? Wrong directories? Missing categories?

Version Control Gaps

• Current: Which logs are tracked in Git? (from discovery-vcs-logs.json)
• Standard: No logs in version control, all in .gitignore
• Gap: X files (Y MB) tracked in Git that should be archived

Archival Gaps

• Current: Is archive index present? Any cloud-archived logs?
• Standard: Archive index exists, auto-archive enabled, cloud storage configured
• Gap: No archival? Manual archival only? Missing cloud storage?

Integration Gaps

• Current: Are build/deploy logs being captured?
• Standard: Auto-capture for all operational logs
• Gap: Manual capture only? Logs being ignored?

Storage Gaps

• Current: Total storage, breakdown by location (from discovery-storage.json)
• Standard: 80% of logs archived to cloud (compressed), 20% local (recent)
• Gap: All local? Wasted repository space? No compression?

Categorize All Gaps by Priority:

• HIGH: Logs in VCS (security/size risk), no cloud storage config, no .gitignore
• MEDIUM: Unmanaged logs, scattered directories, no auto-capture
• LOW: Missing categories, optimization opportunities

Step 6: Generate Standardized Audit Report via docs-manage-audit

Invoke docs-manage-audit skill to create dual-format audit report:

Skill(skill="docs-manage-audit")

Then provide the audit data:

Use the docs-manage-audit skill to create logs audit report with the following parameters:
{
  "operation": "create",
  "audit_type": "logs",
  "check_type": "full",
  "audit_data": {
    "audit": {
      "type": "logs",
      "check_type": "full",
      "timestamp": "{ISO8601}",
      "duration_seconds": {duration},
      "auditor": {
        "plugin": "fractary-logs",
        "skill": "log-auditor"
      },
      "audit_id": "{timestamp}-logs-audit"
    },
    "summary": {
      "overall_status": "pass|warning|error",
      "status_counts": {
        "passing": {passing_count},
        "warnings": {warning_count},
        "failures": {failure_count}
      },
      "exit_code": {0|1|2},
      "compliance_percentage": {compliance_percentage}
    },
    "findings": {
      "categories": [
        {
          "name": "Configuration",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        },
        {
          "name": "Structure",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        },
        {
          "name": "Version Control",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        },
        {
          "name": "Archival",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        },
        {
          "name": "Integration",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        },
        {
          "name": "Storage",
          "status": "pass|warning|error",
          "checks_performed": {count},
          "passing": {count},
          "warnings": {count},
          "failures": {count}
        }
      ],
      "by_severity": {
        "high": [
          {
            "id": "log-001",
            "severity": "high",
            "category": "version-control",
            "message": "X GB of logs tracked in version control",
            "details": "Found {count} log files in Git repository",
            "remediation": "Exclude logs from Git and archive to cloud"
          }
        ],
        "medium": [{finding}],
        "low": [{finding}]
      }
    },
    "metrics": {
      "total_storage_mb": {total_size_mb},
      "managed_logs": {managed_count},
      "unmanaged_logs": {unmanaged_count},
      "vcs_logs": {vcs_count},
      "vcs_impact_mb": {vcs_size_mb}
    },
    "recommendations": [
      {
        "priority": "high|medium|low",
        "category": "logs",
        "recommendation": "{action}",
        "impact": "{storage_savings or compliance_improvement}"
      }
    ],
    "extensions": {
      "logs": {
        "total_storage_mb": {total_size_mb},
        "potential_savings_mb": {savings_mb},
        "cloud_cost_estimate": "{monthly_cost}",
        "vcs_impact_mb": {vcs_size_mb},
        "implementation_phases": 4
      }
    }
  },
  "output_path": "/logs/audits/",
  "project_root": "{project-root}"
}

This will generate:

• README.md: Human-readable audit dashboard
• audit.json: Machine-readable audit data

Both files in /logs/audits/{timestamp}-logs-audit.[md|json]

Storage Location:

• Stored with logs in /logs/audits/ (ephemeral)
• Subject to same retention as other logs
• Can be archived to cloud with other logs
• Multiple audits create timestamped files (not overwritten)

Integration: The docs-manage-audit skill standardizes the audit report format and integrates with logs-manager for retention tracking.

Step 7: Generate Remediation Specification via Spec Manager

Now create the actionable implementation plan using the Spec Manager agent.

CRITICAL: This is a separate document from the audit report!

• Audit Report (Step 6): Point-in-time assessment stored with logs (ephemeral)

  • Location: /logs/audits/audit-{timestamp}.md
  • Purpose: Document current state + gaps
  • Retention: Subject to log archival policies

• Remediation Spec (Step 7): Persistent action plan for project

  • Location: /specs/logs-remediation-{timestamp}.md (created by Spec Manager)
  • Purpose: Actionable implementation plan
  • Retention: Committed to version control, kept as project documentation

If fractary-spec plugin available:

Invoke the spec-manager agent using natural language to generate the specification:

Use the @agent-fractary-spec:spec-manager agent to generate a remediation specification with the following request:

{
  "operation": "generate",
  "spec_type": "implementation",
  "parameters": {
    "title": "Log Management Remediation - {project_name}",
    "context": "Adopt Universal Log Manager (fractary-logs) for operational log management with hybrid retention and cloud archival. Based on audit performed at {timestamp}.",
    "metadata": {
      "complexity": "{MINIMAL|MODERATE|EXTENSIVE}",
      "estimated_hours": {hours},
      "total_actions": {count},
      "priority_breakdown": {
        "high": {high_count},
        "medium": {medium_count},
        "low": {low_count}
      },
      "storage_analysis": {
        "total_logs_gb": {size},
        "unmanaged_gb": {size},
        "vcs_logs_gb": {size},
        "potential_savings_gb": {size}
      },
      "discovery_date": "{date}",
      "plugin_version": "1.0"
    }
  },
  "sections": {
    "overview": {
      "summary": "This specification outlines adoption of Universal Log Manager (fractary-logs) for operational log management with hybrid retention and cloud archival.",
      "current_state": {
        "total_logs": "{count} files ({size} GB)",
        "unmanaged_logs": "{count} files ({size} GB)",
        "vcs_logs": "{count} files ({size} GB)",
        "managed_logs": "{count} files ({size} GB)",
        "cloud_storage": "{configured|not_configured}"
      },
      "target_state": {
        "management": "All operational logs managed by fractary-logs",
        "retention": "Hybrid (30 days local, archived to cloud)",
        "vcs_cleanup": "No logs in version control",
        "storage_savings": "{size} GB from repository"
      }
    },
    "requirements": [
      {
        "id": "REQ-{n}",
        "priority": "{high|medium|low}",
        "title": "{Action title}",
        "description": "{What needs to be done}",
        "rationale": "{Why this is needed}",
        "files_affected": ["{list of files}"],
        "acceptance_criteria": ["{checklist}"]
      }
    ],
    "implementation_plan": {
      "phases": [
        {
          "phase": 1,
          "name": "Configure Cloud Storage",
          "estimated_hours": {hours},
          "objective": "Set up fractary-file for cloud archival",
          "tasks": [
            {
              "task_id": "1.1",
              "title": "Initialize fractary-file plugin",
              "commands": ["/fractary-file:init"],
              "verification": ["/fractary-file:test-connection"]
            },
            {
              "task_id": "1.2",
              "title": "Configure S3/R2 bucket",
              "commands": ["# Configure in .fractary/plugins/file/config.json"],
              "verification": ["# Test upload"]
            }
          ]
        },
        {
          "phase": 2,
          "name": "Set Up Log Management",
          "estimated_hours": {hours},
          "objective": "Configure fractary-logs and create managed locations",
          "tasks": [
            {
              "task_id": "2.1",
              "title": "Initialize fractary-logs",
              "commands": ["/fractary-logs:init"],
              "verification": ["ls /logs/"]
            },
            {
              "task_id": "2.2",
              "title": "Update .gitignore",
              "commands": ["# Add /logs/ exclusion"],
              "verification": ["git check-ignore /logs/"]
            }
          ]
        },
        {
          "phase": 3,
          "name": "Archive Historical Logs",
          "estimated_hours": {hours},
          "objective": "Archive existing logs to cloud",
          "tasks": [
            {
              "task_id": "3.1",
              "title": "Archive logs to cloud",
              "commands": ["# Commands to archive specific logs"],
              "verification": ["# Verify in cloud storage"]
            },
            {
              "task_id": "3.2",
              "title": "Remove logs from VCS",
              "commands": [
                "git rm {files}",
                "git filter-repo --path {files} --invert-paths"
              ],
              "verification": ["git log --all --full-history -- {files}"]
            }
          ]
        },
        {
          "phase": 4,
          "name": "Configure Auto-Capture",
          "estimated_hours": {hours},
          "objective": "Set up automatic log capture",
          "tasks": [
            {
              "task_id": "4.1",
              "title": "Configure build log capture",
              "commands": ["# Update build scripts"],
              "verification": ["# Run build and verify log captured"]
            }
          ]
        }
      ]
    },
    "acceptance_criteria": [
      "fractary-file configured for cloud storage",
      "fractary-logs initialized and configured",
      "All operational logs in managed locations",
      "Historical logs archived to cloud",
      "No logs in version control",
      ".gitignore excludes /logs/",
      "Auto-capture configured for builds/deployments"
    ],
    "verification_steps": [
      "/fractary-logs:search \"test\"",
      "git status # Should show no log files",
      "du -sh /logs/ # Check local storage",
      "# Check cloud storage for archived logs"
    ]
  },
  "output_path": "/specs/logs-remediation-{timestamp}.md"
}

Important Notes on Spec Manager Invocation:

• Use natural language agent invocation (not a tool call)
• The spec-manager agent will create timestamped spec in /specs/
• Pass all gap analysis findings as requirements
• Include reference to audit report timestamp
• Include executable commands for each task
• Ensure verification steps are specific and testable

Timestamp Format: YYYYMMDD-HHMMSS (e.g., 20250115-143022)

If fractary-spec NOT available:

Generate markdown specification directly following similar structure but in plain markdown format. Write directly to /specs/logs-remediation-{timestamp}.md.

Note on Spec Location: The Spec Manager may place the spec in its own managed location. Default is /specs/ at project root.

Step 8: Present Summary to User

Display audit summary:

═══════════════════════════════════════════════════════════
📊 LOG AUDIT SUMMARY
═══════════════════════════════════════════════════════════

📁 LOG INVENTORY
  Total Logs: {count} files ({size} GB)
  By Type: Build: {n}, Deploy: {n}, Debug: {n}, Session: {n}, Other: {n}

📊 MANAGEMENT STATUS
  Managed: {count} files ({size} GB)
  Unmanaged: {count} files ({size} GB)
  In VCS: {count} files ({size} GB)

💰 STORAGE ANALYSIS
  Total Storage: {size} GB
  Repository Impact: {size} GB
  Potential Savings: {size} GB
  Cloud Cost (est.): ${cost}/month

⚠️ ACTIONS REQUIRED
  High Priority: {count}
  Medium Priority: {count}
  Low Priority: {count}

📋 OUTPUT DOCUMENTS
  1. Audit Report: /logs/audits/audit-{timestamp}.md
     - Point-in-time assessment (ephemeral)
     - Current state, standard, gap analysis
     - Stored with logs, subject to retention

  2. Remediation Spec: /specs/logs-remediation-{timestamp}.md
     - Persistent action plan (committed to VCS)
     - Generated by Spec Manager agent
     - Estimated Time: {hours} hours
     - Phases: 4

💡 NEXT STEPS
  1. Review audit report: /logs/audits/audit-{timestamp}.md
  2. Review remediation spec: /specs/logs-remediation-{timestamp}.md
  3. Set up cloud storage (fractary-file)
  4. Follow 4-phase implementation plan
  5. Verify with search command

═══════════════════════════════════════════════════════════

OUTPUT END MESSAGE:

✅ COMPLETED: Log Audit
Audit Timestamp: {timestamp}
Logs Found: {count} ({size} GB)
Gaps Identified: {count}
───────────────────────────────────────────────────────────
Outputs:
  • Audit Report (ephemeral): /logs/audits/audit-{timestamp}.md
  • Remediation Spec (persistent): /specs/logs-remediation-{timestamp}.md
  • Discovery Data: /logs/audits/tmp/discovery-*.json
───────────────────────────────────────────────────────────
Next: Review both documents and follow implementation plan

Success Response:

{
  "success": true,
  "operation": "audit",
  "result": {
    "discovery": {
      "total_logs": {
        "count": 45,
        "size_gb": 2.3
      },
      "managed": {
        "count": 3,
        "size_gb": 0.15
      },
      "unmanaged": {
        "count": 32,
        "size_gb": 1.8
      },
      "vcs_logs": {
        "count": 12,
        "size_gb": 0.45
      }
    },
    "gap_analysis": {
      "gaps_identified": 14,
      "by_priority": {
        "high": 8,
        "medium": 4,
        "low": 2
      }
    },
    "storage_savings": {
      "repository_gb": 1.9,
      "cloud_cost_monthly": 5.50
    },
    "outputs": {
      "audit_report": "/logs/audits/audit-20250115-143022.md",
      "remediation_spec": "/specs/logs-remediation-20250115-143022.md",
      "discovery_files": [
        "/logs/audits/tmp/discovery-logs.json",
        "/logs/audits/tmp/discovery-vcs-logs.json",
        "/logs/audits/tmp/discovery-patterns.json",
        "/logs/audits/tmp/discovery-storage.json"
      ],
      "timestamp": "20250115-143022"
    },
    "estimated_hours": 4,
    "used_spec_plugin": true
  },
  "timestamp": "2025-01-15T12:00:00Z"
}

Error Response:

{
  "success": false,
  "operation": "audit",
  "error": "No log files found",
  "error_code": "NO_LOGS_FOUND",
  "timestamp": "2025-01-15T12:00:00Z"
}

Discovery Errors:

• Script execution failure: Report which script and error
• No logs found: Suggest this is good (no action needed)
• Permission denied: Report access issue

Spec Generation Errors:

• Spec plugin unavailable: Fall back to direct generation
• Invalid discovery data: Report parsing error
• Cannot write output: Report permission issue

Configuration Errors:

• No config found: Note config will be created during adoption
• Invalid config: Report validation error
• fractary-file not configured: Note it's required for cloud storage

Usage Example:

Use the log-auditor skill to audit logs:
{
  "operation": "audit",
  "parameters": {
    "project_root": "/path/to/project",
    "output_dir": "/logs/audits/tmp",
    "config_path": ".fractary/plugins/logs/config.json",
    "execute": false
  }
}

What to document:

• Discovery results (inventory, patterns, storage)
• Issues identified by priority
• Storage savings calculation
• Remediation actions generated
• Estimated effort

Format: Audit summary as formatted text Remediation spec as structured markdown (via spec-manager or direct)