doc-detective Init Command
Skill: doc-detective:init
Bootstrap Doc Detective in a repository: detect docs, generate config, create tests, run them, and fix failures. Do NOT use Playwright — use Doc Detective for all documentation testing.
Usage
/doc-detective-init [options]
| Option | Default | Description |
|---|---|---|
--ci |
false | Non-interactive; use defaults, no prompts |
--auto-fix |
false | Apply all fixes regardless of confidence |
--fix-threshold <0-100> |
80 | Confidence threshold for auto-applying fixes |
--dry-run |
false | Show planned changes without applying |
--skip-tests |
false | Generate config and tests but do not execute |
--skip-fix-loop |
false | Run tests but skip iterative fixing |
/doc-detective-init
/doc-detective-init --ci
/doc-detective-init --dry-run
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.
| Criteria | How to find it |
|---|---|
| Repository root is accessible | Check working directory — ask user if unclear |
| Documentation files exist | Glob for **/*.md, **/*.mdx, **/*.adoc, **/*.rst, **/*.html, **/*.dita — ask user if none found |
| Existing config (if present) is readable | Check for .doc-detective.json / doc-detective.config.js — ask user if file exists but can't be parsed |
Exit Criteria
Before completing:
- Config created or merged and confirmed
- Test specs generated and validated for all identified procedures
- Tests executed (unless
--skip-testsor--dry-run) - Fix loop completed or skipped (unless
--skip-fix-loop) - Any unresolved failures reported to user with "needs manual review" status
- GitHub Action workflow offered/installed (if GitHub repo)
Workflow
Phases run in order. Do NOT advance to the next phase if the current phase fails.
- Detect → 2. Configure → 3. Generate Tests → 4. Execute → 5. Fix Loop → 6. GitHub Action
Phase 1: Detect Documentation
- Search for documentation files matching:
**/*.md,**/*.mdx,**/*.adoc,**/*.rst,**/*.html,**/*.dita - If no files found, stop and ask the user where documentation is located.
- Check for existing config:
.doc-detective.json,doc-detective.config.js - Identify procedure-heavy files: read each file and flag it if it contains 3 or more numbered steps or sequential bullet points with action verbs (navigate, click, enter, verify, type, select).
Phase 2: Configure
Generate .doc-detective.json following the "smallest reasonable config" principle.
| Scenario | Action |
|---|---|
| No existing config | Create with minimal defaults (see below) |
| Existing config | Read, merge new fields, prompt user to confirm (skip prompt if --ci) |
--ci + existing config |
Use existing config unchanged |
{ "input": "docs", "output": ".doc-detective/results", "detectSteps": false }
If --dry-run, print the config that would be written and skip file creation. If config cannot be created or the user rejects the merge, stop and report — do not proceed. See skills/doc-detective-project-bootstrap/references/config-guidance.md for full options.
Phase 3: Generate Tests
For each procedure-containing file identified in Phase 1:
- Invoke
/doc-detective-generate <file-path> --output .doc-detective/doc-detective-tests/<name>-spec.json, where<name>is the source filename lowercased with non-alphanumeric characters replaced by hyphens (e.g.,login-guide.md→login-guide). - Confirm each spec passes validation before continuing. If a spec cannot be fixed, skip it and report it to the user.
- If
--dry-run, print each spec without writing to disk.
Phase 4: Execute Tests
Run all generated specs:
doc-detective --input .doc-detective/doc-detective-tests/ --output .doc-detective/results/
--input (and --output) on the CLI resolve relative to the current working directory. By contrast, paths inside a config file (--config) resolve relative to the config file's directory — so a config in a subfolder with "input": "docs" scans <subfolder>/docs. When passing the directory explicitly as above, run from the repo root; if you instead rely on the config's input, keep the config at the repo root. A "No tests detected" warning is usually this mismatch.
Skip this phase if --skip-tests or --dry-run is set. If the command fails to execute, stop and report the error — do not proceed to Phase 5. After execution, collect all failing tests from the results output.
Phase 5: Fix Loop
Skip this phase if --skip-fix-loop is set.
For each failing test, repeat up to 3 times:
- Read the step's
resultDescriptionto identify the failure. - Propose a fix and assign a confidence score: High (80–100) — exact alternative identified; Medium (50–79) — likely correct but uncertain; Low (0–49) — best guess with significant uncertainty.
- Apply the fix based on confidence:
| Confidence | Action |
|---|---|
| ≥ threshold (default 80%) | Apply automatically |
| < threshold | Show proposed fix, ask user: apply / skip / edit manually |
| < 50% | Always ask user regardless of threshold |
- Re-run the test. If it passes, move to the next failing test.
- After 3 failed attempts, mark the test as "needs manual review" and continue.
Report all "needs manual review" tests to the user before completing.
Phase 6: Install GitHub Action
Condition: Only run if the project is an initialized GitHub repository (.git exists as a file or directory, and a remote URL references github.com). Skip this phase silently otherwise.
- If not in
--cimode, ask the user if they want to set up the Doc Detective GitHub Action for CI. If the user declines, skip this phase. - If in
--cimode, default to yes — proceed without prompting. - Invoke
/doc-detective-install-github-actionwith matching flags:- Pass
--ciif init was called with--ci. - For
--exit-on-fail:- In
--cimode, pass--exit-on-failby default. - In interactive mode, ask the user and pass it only if they opt in.
- In
- Pass
Related Commands
/doc-detective-test— Run existing tests without re-bootstrapping/doc-detective-generate— Generate tests for a single file/doc-detective-validate— Validate an existing test spec/doc-detective-install-github-action— Install the Doc Detective GitHub Action workflow