Doc detective init
Skill doc-detective/agent-tools/src/skills/doc-detective-init
Initialize Doc Detective in a repository with documentation detection, config generation, test creation, and iterative fix loopFrom its SKILL.md
npx -y skills add doc-detective/agent-tools --skill doc-detective-initAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.0 KB, as published. Nobody here has run it
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