# Doc Detective Init

> Initialize Doc Detective in a repository with documentation detection, config generation, test creation, and iterative fix loop

- Skill: `doc-detective/doc-detective-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add doc-detective/doc-detective-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doc-detective/doc-detective-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: doc-detective (https://skillmd.com/u/doc-detective)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/doc-detective/doc-detective-init

---


# 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

```bash
/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 |

```bash
/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:

1. [ ] Config created or merged and confirmed
2. [ ] Test specs generated and validated for all identified procedures
3. [ ] Tests executed (unless `--skip-tests` or `--dry-run`)
4. [ ] Fix loop completed or skipped (unless `--skip-fix-loop`)
5. [ ] Any unresolved failures reported to user with "needs manual review" status
6. [ ] 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.**

1. Detect → 2. Configure → 3. Generate Tests → 4. Execute → 5. Fix Loop → 6. GitHub Action

### Phase 1: Detect Documentation

1. Search for documentation files matching: `**/*.md`, `**/*.mdx`, `**/*.adoc`, `**/*.rst`, `**/*.html`, `**/*.dita`
2. If no files found, stop and ask the user where documentation is located.
3. Check for existing config: `.doc-detective.json`, `doc-detective.config.js`
4. 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 |

```json
{ "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:

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`).
2. Confirm each spec passes validation before continuing. If a spec cannot be fixed, skip it and report it to the user.
3. If `--dry-run`, print each spec without writing to disk.

### Phase 4: Execute Tests

Run all generated specs:

```bash
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:

1. Read the step's `resultDescription` to identify the failure.
2. 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.
3. 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 |

4. Re-run the test. If it passes, move to the next failing test.
5. 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.

1. If not in `--ci` mode, ask the user if they want to set up the Doc Detective GitHub Action for CI. If the user declines, skip this phase.
2. If in `--ci` mode, default to yes — proceed without prompting.
3. Invoke `/doc-detective-install-github-action` with matching flags:
   - Pass `--ci` if init was called with `--ci`.
   - For `--exit-on-fail`:
     - In `--ci` mode, pass `--exit-on-fail` by default.
     - In interactive mode, ask the user and pass it only if they opt in.

## 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