doc-detective/agent-tools/doc-detective-validate

Validate Command

Skill: doc-detective:validate

Validate Doc Detective test specifications or configuration files to ensure they're correctly structured.

Usage

Validate a test specification file or inline JSON:

/doc-detective-validate test-spec.json

/doc-detective-validate

{
  "tests": [{
    "testId": "login-flow",
    "steps": [
      { "goTo": "https://example.com/login" },
      { "click": "Sign In" }
    ]
  }]
}

Validate a configuration file:

/doc-detective-validate --config .doc-detective.json

Entry Criteria

Confirm all of the following before starting. If any item is unavailable or non-discoverable, stop and ask the user to provide it.

Exit Criteria

Before completing:

1. [ ] Validation executed against the provided input
2. [ ] Each error reported as: [FIELD]: [ERROR REASON]
3. [ ] Final result stated as Validation PASSED or Validation FAILED

Workflow

Validate Test Specification

Preferred: If a tool named validate_spec (or mcp__doc-detective__validate_spec) is registered in this session, call it instead of shelling out:

validate_spec({
  object: <spec-or-config>,
  schemaKey: "spec_v3",   // or "config_v3" for config files
  addDefaults: true,
  format: "auto"
})

The MCP tool returns {valid, errors[], normalizedObject, schemaKey, schemaVersion}. Report each entry of errors[] as [instancePath]: [message]. Treat valid: true as Validation PASSED.

Fallback: If the MCP tool is not available, run the validator (try in order; stop and tell the user if none are available):

# Option 1
echo '<spec-json>' | node skills/doc-detective-doc-testing/scripts/doc-detective-validate-test.js --stdin
# Option 2
npx doc-detective validate --input <spec-file>

See _shared/MCP-USAGE.md for tool-naming conventions across hosts and log_observation guidance when validation friction is unrecoverable.

Only report `Validation PASSED` when the output confirms no errors. On failure, report each error as [FIELD]: [ERROR REASON].

Test spec checks:

• tests array must exist and be non-empty
• Each test must have a non-empty steps array
• Each step must contain exactly one recognized Doc Detective action
• Action parameters must match expected types

Validate Configuration File

Preferred: Call validate_spec({object: <config>, schemaKey: "config_v3", addDefaults: true}) via MCP if available. Report each errors[] entry as [instancePath]: [message].

Fallback: Check the provided JSON against the doc-detective-common config schema. Report every field that fails as [FIELD]: [ERROR REASON].

Config checks:

• input: must be a string or string array of valid glob patterns or file paths
• recursive: must be a boolean
• output: must be a valid directory path string
• logLevel: must be one of silent, error, warning, info, debug
• browser: must be an object (not a string)
• env: must be an object or .env file path string
• defaultCommandTimeout: must be a number (milliseconds)

Valid config:

{ "input": ["docs/**/*.md"] }

Invalid config:

{ "input": "docs/", "browser": "chrome", "logLevel": "verbose" }

Errors: browser must be object, logLevel value invalid.

See doc-detective-common for the full configuration schema.