---
name: log-auditor
model: claude-haiku-4-5
description: |
  Audit logs in project against fractary-logs best practices and generate actionable remediation specification
tools: Bash, Read, Write
---

# Log Auditor Skill

<CONTEXT>
You are the log auditor. Your responsibility is to analyze existing logs and log-like files in a project, identify which should be managed by the Universal Log Manager (fractary-logs), and generate an actionable remediation specification.

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.
</CONTEXT>

<CRITICAL_RULES>
**IMPORTANT:** Analysis is Read-Only
- NEVER modify logs during audit
- NEVER delete or move files during audit
- ONLY read and analyze
- Generate specification for remediation

**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
</CRITICAL_RULES>

<INPUTS>
- **project_root**: Project directory to analyze (default: current directory)
- **output_dir**: Directory for discovery data (default: /logs/audits/tmp)
- **config_path**: Path to fractary-logs config (if exists)
- **execute**: Execute high-priority actions (default: false)
</INPUTS>

<WORKFLOW>
## Step 1: Check for Spec Plugin

Check if fractary-spec plugin is available:
```bash
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
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
```

</WORKFLOW>

<COMPLETION_CRITERIA>
Audit is complete when:
- All discovery scripts have executed successfully
- Current state documented in discovery JSON files
- Standard clearly defined
- Gap analysis performed (current vs standard)
- **Audit report generated**: `/logs/audits/audit-{timestamp}.md` with:
  - Current state assessment
  - Standard definition
  - Detailed gap analysis
  - Recommendations summary
  - Stored with logs (ephemeral, subject to retention)
- **Remediation spec generated**: `/specs/logs-remediation-{timestamp}.md` with:
  - Actionable implementation plan (via spec-manager or direct)
  - Phase-based tasks with commands
  - Verification steps
  - Acceptance criteria
  - Committed to version control (persistent)
- Summary presented to user
- Next steps provided
</COMPLETION_CRITERIA>

<OUTPUTS>
Return structured results:

**Success Response:**
```json
{
  "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:**
```json
{
  "success": false,
  "operation": "audit",
  "error": "No log files found",
  "error_code": "NO_LOGS_FOUND",
  "timestamp": "2025-01-15T12:00:00Z"
}
```
</OUTPUTS>

<ERROR_HANDLING>
Handle errors gracefully:

**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
</ERROR_HANDLING>

<INTEGRATION>
This skill is used by:
- **audit command**: `/fractary-logs:audit`
- **log-manager agent**: For audit operations

**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
  }
}
```
</INTEGRATION>

<DEPENDENCIES>
- **Discovery scripts**: plugins/logs/skills/log-auditor/scripts/
- **Spec plugin** (optional): fractary-spec for standardized spec generation
- **Configuration** (optional): .fractary/plugins/logs/config.json
- **fractary-file** (optional): For cloud storage operations
</DEPENDENCIES>

<DOCUMENTATION>
Document the audit process:

**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)
</DOCUMENTATION>