Skip to content

aiskillstore/marketplace / skills/2389-research/documentation-audit

documentation-audit

Verified

This skill should be used when verifying documentation claims against codebase reality. Triggers on "audit docs", "verify documentation", "check docs", "docs accurate", "documentation drift", "before release", "after refactor", "docs don't match". Uses two-pass extraction with pattern expansion for comprehensive detection.

FileKindSize
SKILL.mdskill md3.5 KB
checklist.mdmarkdown3.2 KB
extraction-patterns.mdmarkdown3.8 KB
skill-report.jsonconfig31.1 KB

skill-report.json

View on GitHub
{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-07-04T17:44:46.379Z",
    "slug": "2389-research-documentation-audit",
    "source_url": "https://github.com/2389-research/claude-plugins/tree/main/documentation-audit/skills",
    "source_ref": "main",
    "model": "codex",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "672c8f4070bd99ce9c40e64dbb4070682c85b0d0620bd89a8d7dd0cb8ab8ad24",
    "tree_hash": "29d5459edb9543152e353b00dd06545f4123796ab9577864fc86e63c1b1040d3",
    "provenance": {
      "model_requested": "gpt-5.5:high",
      "model_effective": "codex:gpt-5.5:high",
      "fallback_chain": [
        {
          "agent": "codex",
          "model": "gpt-5.5",
          "effort": "high",
          "outcome": "success"
        }
      ],
      "analysis_version": "3.0.0"
    }
  },
  "skill": {
    "name": "documentation-audit",
    "description": "Audits documentation claims against the current codebase using structured extraction, verification, pattern expansion, and gap detection.",
    "summary": "Verify documentation accuracy by checking claims against real codebase evidence.",
    "icon": "📦",
    "version": "1.0.0",
    "author": "2389-research",
    "license": "MIT",
    "tags": [
      "documentation-audit",
      "documentation-drift",
      "claim-verification",
      "release-readiness",
      "codebase-audit"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "external_commands",
      "env_access"
    ],
    "category": "documentation"
  },
  "security_audit": {
    "risk_level": "high",
    "is_blocked": false,
    "safe_to_publish": false,
    "analysis_status": "ok",
    "summary": "The static findings are false positives caused by markdown backticks, regex examples, and references to .env.example. Semantic review found one real risk: the skill suggests running target repository scripts to inspect CLI help, which can execute untrusted code. No prompt injection attempt was found.",
    "remediation": [
      {
        "issue": "CLI verification can execute untrusted repository code.",
        "suggestion": "Prefer static inspection of argparse, click, Typer, or README usage text. Run target scripts only in a sandbox after user confirmation.",
        "severity": "high"
      },
      {
        "issue": "Environment checks could be misread as permission to inspect real secret files.",
        "suggestion": "State that audits should use .env.example, schemas, and source defaults. Avoid reading real .env files unless the user explicitly approves.",
        "severity": "low"
      },
      {
        "issue": "Command examples lack safety boundaries for untrusted projects.",
        "suggestion": "Add guidance to treat audited repositories as untrusted and to avoid executing project code during documentation checks.",
        "severity": "medium"
      }
    ],
    "risk_factor_evidence": [
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "extraction-patterns.md",
            "line_start": 17,
            "line_end": 18
          },
          {
            "file": "extraction-patterns.md",
            "line_start": 37,
            "line_end": 38
          },
          {
            "file": "SKILL.md",
            "line_start": 26,
            "line_end": 26
          },
          {
            "file": "SKILL.md",
            "line_start": 31,
            "line_end": 31
          },
          {
            "file": "SKILL.md",
            "line_start": 37,
            "line_end": 37
          },
          {
            "file": "SKILL.md",
            "line_start": 38,
            "line_end": 38
          },
          {
            "file": "SKILL.md",
            "line_start": 39,
            "line_end": 39
          },
          {
            "file": "SKILL.md",
            "line_start": 40,
            "line_end": 40
          },
          {
            "file": "SKILL.md",
            "line_start": 41,
            "line_end": 41
          },
          {
            "file": "SKILL.md",
            "line_start": 52,
            "line_end": 61
          },
          {
            "file": "SKILL.md",
            "line_start": 61,
            "line_end": 64
          },
          {
            "file": "SKILL.md",
            "line_start": 64,
            "line_end": 65
          },
          {
            "file": "SKILL.md",
            "line_start": 65,
            "line_end": 66
          },
          {
            "file": "SKILL.md",
            "line_start": 66,
            "line_end": 66
          },
          {
            "file": "SKILL.md",
            "line_start": 67,
            "line_end": 68
          },
          {
            "file": "SKILL.md",
            "line_start": 68,
            "line_end": 72
          },
          {
            "file": "SKILL.md",
            "line_start": 72,
            "line_end": 74
          },
          {
            "file": "SKILL.md",
            "line_start": 74,
            "line_end": 90
          },
          {
            "file": "SKILL.md",
            "line_start": 90,
            "line_end": 90
          }
        ]
      },
      {
        "factor": "env_access",
        "evidence": [
          {
            "file": "extraction-patterns.md",
            "line_start": 43,
            "line_end": 43
          },
          {
            "file": "extraction-patterns.md",
            "line_start": 43,
            "line_end": 43
          }
        ]
      }
    ],
    "static_findings": [
      {
        "id": "sensitive:checklist.md:40:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "checklist.md",
        "line_start": 40,
        "line_end": 40,
        "snippet": "- [ ] **config_default:** Check .env.example, config modules, code defaults"
      },
      {
        "id": "sensitive:checklist.md:41:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "checklist.md",
        "line_start": 41,
        "line_end": 41,
        "snippet": "- [ ] **env_var:** Grep for usage in code, check .env.example"
      },
      {
        "id": "external_commands:extraction-patterns.md:17:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "extraction-patterns.md",
        "line_start": 17,
        "line_end": 18,
        "snippet": "`[a-zA-Z0-9_/.-]+\\.(py|sh|md|sql|liq|json|yaml|yml|toml|service|timer)`"
      },
      {
        "id": "external_commands:extraction-patterns.md:37:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "extraction-patterns.md",
        "line_start": 37,
        "line_end": 38,
        "snippet": "(?:defaults? to|Default:?|default value is)\\s*[`'\"]?([^`'\".\\n]+)"
      },
      {
        "id": "env_access:extraction-patterns.md:43:python-getenv-function",
        "category": "env_access",
        "severity": "low",
        "pattern": "Python getenv function",
        "file": "extraction-patterns.md",
        "line_start": 43,
        "line_end": 43,
        "snippet": "3. Code: `os.getenv(\"VAR\", \"default\")`"
      },
      {
        "id": "env_access:extraction-patterns.md:43:getenv-function-call",
        "category": "env_access",
        "severity": "low",
        "pattern": "getenv function call",
        "file": "extraction-patterns.md",
        "line_start": 43,
        "line_end": 43,
        "snippet": "3. Code: `os.getenv(\"VAR\", \"default\")`"
      },
      {
        "id": "sensitive:extraction-patterns.md:33:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "extraction-patterns.md",
        "line_start": 33,
        "line_end": 33,
        "snippet": "- .env examples with `VAR=value`"
      },
      {
        "id": "sensitive:extraction-patterns.md:41:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "extraction-patterns.md",
        "line_start": 41,
        "line_end": 41,
        "snippet": "1. `.env.example` - documented defaults"
      },
      {
        "id": "sensitive:extraction-patterns.md:66:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "extraction-patterns.md",
        "line_start": 66,
        "line_end": 66,
        "snippet": "grep \"^VAR=\" .env.example"
      },
      {
        "id": "sensitive:extraction-patterns.md:155:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "extraction-patterns.md",
        "line_start": 155,
        "line_end": 155,
        "snippet": "Verify: Each against .env.example and code"
      },
      {
        "id": "external_commands:SKILL.md:26:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 26,
        "line_end": 26,
        "snippet": "1. Identify target docs (user-facing only, skip `plans/`, `audits/`)"
      },
      {
        "id": "external_commands:SKILL.md:31:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 31,
        "line_end": 31,
        "snippet": "6. Generate `docs/audits/AUDIT_REPORT_YYYY-MM-DD.md`"
      },
      {
        "id": "external_commands:SKILL.md:37:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 37,
        "line_end": 37,
        "snippet": "| `file_ref` | `scripts/foo.py` | File exists? |"
      },
      {
        "id": "external_commands:SKILL.md:38:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 38,
        "line_end": 38,
        "snippet": "| `config_default` | \"defaults to 'AI Radio'\" | Check schema/code |"
      },
      {
        "id": "external_commands:SKILL.md:39:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 39,
        "line_end": 39,
        "snippet": "| `env_var` | `STATION_NAME` | In .env.example + code? |"
      },
      {
        "id": "external_commands:SKILL.md:40:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 40,
        "line_end": 40,
        "snippet": "| `cli_command` | `--normalize` flag | Script supports it? |"
      },
      {
        "id": "external_commands:SKILL.md:41:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 41,
        "line_end": 41,
        "snippet": "| `behavior` | \"runs every 2 minutes\" | Check timers/code |"
      },
      {
        "id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 52,
        "line_end": 61,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:61:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 61,
        "line_end": 64,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:64:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 64,
        "line_end": 65,
        "snippet": "- Dead scripts: `scripts/*.py` references"
      },
      {
        "id": "external_commands:SKILL.md:65:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 65,
        "line_end": 66,
        "snippet": "- Timer intervals: `every \\d+ (seconds?|minutes?)`"
      },
      {
        "id": "external_commands:SKILL.md:66:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 66,
        "line_end": 66,
        "snippet": "- Service names: `ai-radio-*.service`, `*.timer`"
      },
      {
        "id": "external_commands:SKILL.md:67:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 67,
        "line_end": 68,
        "snippet": "- Config vars: `RADIO_*` environment variables"
      },
      {
        "id": "external_commands:SKILL.md:68:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 68,
        "line_end": 72,
        "snippet": "- CLI flags: `--flag` patterns in bash blocks"
      },
      {
        "id": "external_commands:SKILL.md:72:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 72,
        "line_end": 74,
        "snippet": "Generate `docs/audits/AUDIT_REPORT_YYYY-MM-DD.md`:"
      },
      {
        "id": "external_commands:SKILL.md:74:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 74,
        "line_end": 90,
        "snippet": "```markdown"
      },
      {
        "id": "external_commands:SKILL.md:90:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 90,
        "line_end": 90,
        "snippet": "| 135 | `claude-sonnet-4-5` | Actual: `claude-3-5-sonnet-latest` | Update |"
      },
      {
        "id": "sensitive:SKILL.md:39:environment-file-access",
        "category": "sensitive",
        "severity": "high",
        "pattern": "Environment file access",
        "file": "SKILL.md",
        "line_start": 39,
        "line_end": 39,
        "snippet": "| `env_var` | `STATION_NAME` | In .env.example + code? |"
      }
    ],
    "finding_verdicts": [
      {
        "id": "sensitive:checklist.md:40:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The line tells auditors to check .env.example and config defaults, not read real secret files. It is a documentation checklist item."
      },
      {
        "id": "sensitive:checklist.md:41:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The line asks to grep code and check .env.example for documented variables. It does not request secret extraction or live environment access."
      },
      {
        "id": "external_commands:extraction-patterns.md:17:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "This is a regex pattern inside a markdown code fence for finding documented file references. It is not shell syntax or execution."
      },
      {
        "id": "external_commands:extraction-patterns.md:37:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "This is a regex for extracting default-value claims in documentation. The backticks are markdown delimiters, not command substitution."
      },
      {
        "id": "env_access:extraction-patterns.md:43:python-getenv-function",
        "verdict": "false_positive",
        "confidence": 0.94,
        "reason": "This is a documentation example showing where default values may appear in code. It does not read the current process environment."
      },
      {
        "id": "env_access:extraction-patterns.md:43:getenv-function-call",
        "verdict": "false_positive",
        "confidence": 0.94,
        "reason": "The getenv call appears as a literal pattern to inspect in source files. It is not run by the skill."
      },
      {
        "id": "sensitive:extraction-patterns.md:33:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The text describes .env examples as documentation patterns. It does not instruct reading a real .env file or collecting secrets."
      },
      {
        "id": "sensitive:extraction-patterns.md:41:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.97,
        "reason": "The source is .env.example, a sample defaults file used for documentation checks. No real environment secret access is described."
      },
      {
        "id": "sensitive:extraction-patterns.md:66:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The command targets .env.example for a placeholder VAR value. It does not read .env or expose secret values."
      },
      {
        "id": "sensitive:extraction-patterns.md:155:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The line says to verify claims against .env.example and code. It is documentation validation, not secret harvesting."
      },
      {
        "id": "external_commands:SKILL.md:26:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The backticked entries are directory names to skip during a documentation audit. They are not commands or executable input."
      },
      {
        "id": "external_commands:SKILL.md:31:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.93,
        "reason": "The line names the report path to create. It does not execute shell code or invoke an external program."
      },
      {
        "id": "external_commands:SKILL.md:37:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The table shows a claim type and example path. It does not direct the agent to execute the path."
      },
      {
        "id": "external_commands:SKILL.md:38:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The line is a claim-type example for configuration defaults. It contains no command invocation."
      },
      {
        "id": "external_commands:SKILL.md:39:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The line is a claim-type example for environment variables. It does not execute commands or access live secrets."
      },
      {
        "id": "external_commands:SKILL.md:40:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The line describes checking whether a CLI flag exists. The flag text is not executed by itself."
      },
      {
        "id": "external_commands:SKILL.md:41:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The text is a behavior-claim example about timers. It does not run commands or code."
      },
      {
        "id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.97,
        "reason": "The fenced block contains illustrative audit findings such as dead scripts and wrong intervals. It is not executable shell code."
      },
      {
        "id": "external_commands:SKILL.md:61:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "This finding points at a markdown fence boundary and adjacent prose. There is no command execution construct."
      },
      {
        "id": "external_commands:SKILL.md:64:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The text names a search pattern for script references. It is a literal documentation pattern, not a shell command."
      },
      {
        "id": "external_commands:SKILL.md:65:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.97,
        "reason": "The backticked value is a regex for timer prose. It does not execute external commands."
      },
      {
        "id": "external_commands:SKILL.md:66:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The service and timer globs are examples of documented names to search for. They are not executed."
      },
      {
        "id": "external_commands:SKILL.md:67:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The variable glob is a documentation search pattern. It does not read environment values."
      },
      {
        "id": "external_commands:SKILL.md:68:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The flag pattern is used to identify documented CLI options. It does not execute a command."
      },
      {
        "id": "external_commands:SKILL.md:72:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.94,
        "reason": "The backticked path names the output report file. It is not shell execution."
      },
      {
        "id": "external_commands:SKILL.md:74:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The markdown fence introduces sample report content. It is not executable code."
      },
      {
        "id": "external_commands:SKILL.md:90:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.98,
        "reason": "The table compares documented and actual model names. The backticks mark text values, not command execution."
      },
      {
        "id": "sensitive:SKILL.md:39:environment-file-access",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The table example asks whether a documented variable appears in .env.example and code. It does not request reading runtime secrets."
      }
    ],
    "semantic_findings": [
      {
        "title": "Untrusted Repository Code Execution",
        "description": "The CLI verification pattern recommends running a target project script with a help flag. In an untrusted repository, even help output can execute Python initialization or argument parsing side effects.",
        "severity": "high",
        "locations": [
          {
            "file": "extraction-patterns.md",
            "line_start": 86,
            "line_end": 86
          }
        ],
        "confidence": 0.9,
        "confidence_reasoning": "The command is shown as a verification method and would execute code from the audited repository. The risk is contextual rather than malicious, but it is a real local code execution hazard."
      }
    ],
    "critical_findings": [],
    "high_findings": [
      {
        "title": "Untrusted Repository Code Execution",
        "description": "The CLI verification pattern recommends running a target project script with a help flag. In an untrusted repository, even help output can execute Python initialization or argument parsing side effects.",
        "locations": [
          {
            "file": "extraction-patterns.md",
            "line_start": 86,
            "line_end": 86
          }
        ],
        "review_kind": "security",
        "source_category": "semantic",
        "source_severity": "high",
        "confidence": 0.9,
        "confidence_reasoning": "The command is shown as a verification method and would execute code from the audited repository. The risk is contextual rather than malicious, but it is a real local code execution hazard."
      }
    ],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 3,
    "total_lines": 377,
    "audit_model": "codex",
    "audited_at": "2026-07-04T17:44:46.379Z",
    "agent_auto_install_policy": "confirmation_required",
    "manual_install_policy": "allowed"
  },
  "content": {
    "user_title": "Verify Documentation Against Code",
    "value_statement": "Documentation can drift after refactors, releases, and deleted files. This skill extracts claims, checks them against code, and produces an evidence-based audit report.",
    "seo_keywords": [
      "Claude",
      "Codex",
      "Claude Code",
      "documentation audit",
      "documentation drift",
      "docs verification",
      "claim verification",
      "codebase documentation",
      "release readiness",
      "technical writing QA"
    ],
    "actual_capabilities": [
      "Extracts verifiable claims from user-facing documentation.",
      "Checks file references, defaults, environment variables, CLI flags, and behavior claims.",
      "Expands searches from false claims to find related documentation drift.",
      "Compares documented scripts, services, config modules, and endpoints against repository inventory.",
      "Generates an audit report with evidence, false claims, suggested fixes, and human-review items."
    ],
    "limitations": [
      "Behavior claims often need human review because code evidence may be indirect.",
      "Results depend on repository access and the quality of available source files.",
      "Pattern expansion can produce false positives that need triage.",
      "The skill reports documentation issues but does not update files automatically."
    ],
    "use_cases": [
      {
        "title": "Release Documentation Gate",
        "description": "Check user-facing docs before release and identify stale claims that could mislead users.",
        "target_user": "Maintainers"
      },
      {
        "title": "Post-Refactor Docs Review",
        "description": "Verify that renamed files, settings, services, and CLI options are reflected in documentation.",
        "target_user": "Technical writers"
      },
      {
        "title": "Documentation Debt Triage",
        "description": "Group false claims by pattern so teams can fix high-impact documentation drift first.",
        "target_user": "Engineering leads"
      }
    ],
    "prompt_templates": [
      {
        "title": "Check One Document",
        "scenario": "Beginner audit",
        "prompt": "Use documentation-audit to check README.md against the current repository. List false claims, uncertain claims, and evidence for each result."
      },
      {
        "title": "Verify Selected Docs",
        "scenario": "Focused documentation review",
        "prompt": "Use documentation-audit on README.md and docs/*.md. Focus on file references, configuration defaults, environment variables, CLI flags, and timing claims."
      },
      {
        "title": "Run Two-Pass Audit",
        "scenario": "Advanced drift detection",
        "prompt": "Use documentation-audit to extract claims from user-facing docs, verify them, then search for related patterns from every false claim. Produce an audit report."
      },
      {
        "title": "Prepare Release Gate",
        "scenario": "Advanced release workflow",
        "prompt": "Use documentation-audit before release. Compare documented scripts, services, config values, and CLI options with the codebase. Include blockers and human-review items."
      }
    ],
    "output_examples": [
      {
        "input": "Audit README.md before a release.",
        "output": "The report identifies 42 claims, confirms 36, marks 4 false, and sends 2 behavior claims to human review."
      },
      {
        "input": "Check docs after a configuration refactor.",
        "output": "Finds stale default values, unsupported environment variables, and missing script documentation with file and line evidence."
      },
      {
        "input": "Compare documented services with actual service files.",
        "output": "Summarizes missing service references, renamed timers, and suggested documentation fixes for maintainers."
      }
    ],
    "best_practices": [
      "Audit user-facing docs first and exclude plans or historical notes unless requested.",
      "Keep file and line evidence beside every true, false, and uncertain verdict.",
      "Run pattern expansion after the first false claims are grouped."
    ],
    "anti_patterns": [
      "Treating plausible prose as verified without checking source evidence.",
      "Running target project scripts just to inspect help text outside a sandbox.",
      "Mixing historical plans with current user documentation in the same audit."
    ],
    "faq": [
      {
        "question": "What does this skill audit?",
        "answer": "It audits documentation claims about files, settings, environment variables, CLI flags, services, timers, and behavior."
      },
      {
        "question": "Does it edit documentation?",
        "answer": "No. It creates an audit report with evidence and suggested fixes for maintainers."
      },
      {
        "question": "Can it verify behavior claims?",
        "answer": "It can collect supporting evidence, but behavior claims often need human review."
      },
      {
        "question": "Which AI tools can use it?",
        "answer": "The skill supports Claude, Codex, and Claude Code."
      },
      {
        "question": "Is it safe for untrusted repositories?",
        "answer": "Use caution. Prefer static checks and avoid executing project code unless it is sandboxed and approved."
      },
      {
        "question": "What output should I expect?",
        "answer": "Expect a documentation audit report with counts, false claims, evidence, patterns, and human-review items."
      }
    ]
  },
  "file_structure": [
    {
      "name": "checklist.md",
      "type": "file",
      "path": "checklist.md",
      "lines": 105
    },
    {
      "name": "extraction-patterns.md",
      "type": "file",
      "path": "extraction-patterns.md",
      "lines": 167
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 105
    }
  ]
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall