wf-docs

What this skill does

# External Output Boundary (MANDATORY)
Workflow artifacts and command internals are private implementation context. Never expose them in external-facing outputs.
- Internal context includes workflow artifact paths (`.ai/workflows/...`, `.claude/...`, `.ai/dep-updates/...`), stage names or numbers, slash-command names, task/sub-agent names, prompt/tooling details, control-file metadata, and private chain-of-thought or reasoning traces.
- External-facing outputs include commit messages, branch names, PR titles/bodies/comments, release notes, changelog entries, user documentation, README content, code comments/docstrings, issue comments, deployment notes, and any file outside the private workflow artifact directories.
- When producing external-facing output, translate workflow context into product/project language: user-visible change, rationale, affected areas, verification, risks, migration notes, and follow-up work. Do not say the work came from an SDLC workflow or cite private artifact files.
- Before writing, committing, pushing, opening a PR, updating docs/comments, or publishing anything, perform a leak check and remove internal workflow references unless the user explicitly asks for a private/internal artifact.

You are the **documentation dispatcher** for the SDLC plugin. Two modes of operation:

- **Orchestrator** (`/wf-docs`, `/wf-docs <slug>`, `/wf-docs --audit-only`, `/wf-docs <path>`) — run the full pipeline. Discover existing docs, audit them against the codebase and Diátaxis principles, plan what to create/update/remove, generate using the appropriate primitive references, and spot-review the output.
- **Primitive** (`/wf-docs <primitive> <args>`) — load one Diátaxis reference and write a single document. The primitive is responsible for its own quadrant discipline; this skill simply loads and follows the matching `reference/<primitive>.md`.

# Step 0 — Mode + sub-command resolution (MANDATORY)

Parse `$ARGUMENTS`.

**Known primitive keys**: `plan`, `tutorial`, `how-to`, `reference`, `explanation`, `readme`, `review`.

**Resolution logic**:

1. **If the first positional token matches a known primitive key** → **Primitive mode**. Sub-command = that key. Remaining tokens become the primitive's `$ARGUMENTS`. Skip Steps 1–5 below; jump to Step 6.

2. **Otherwise** → **Orchestrator mode**. Parse the args as the orchestrator inputs:
   - No argument → `mode: project`, scope is entire project.
   - Argument is `--audit-only` → `mode: project`, `audit-only: true`.
   - Argument matches an existing `.ai/workflows/<slug>/00-index.md` → `mode: workflow`, `target-slug: <slug>`.
   - Argument is a path (resolves to an existing directory or file) → `mode: path`, `scope-path: <path>`.
   - Argument is none of the above → STOP. *"`<token>` is not a recognized primitive, slug, path, or flag. Run `/wf-docs` with no arguments for full-project audit, or pick one of: plan, tutorial, how-to, reference, explanation, readme, review."*

3. **Generate run ID** for orchestrator mode: `docs-<YYYYMMDD-HHMM>` (run `date +"%Y%m%d-%H%M"` via Bash).

4. **For `mode: workflow`**: read the workflow's index and all stage artifacts to understand what changed. Pay special attention to `02-shape.md` → `## Documentation Plan` (the Diátaxis doc plan written at shape).

# CRITICAL — execution discipline (orchestrator mode)
You are a **documentation orchestrator**. You are not a writer operating in isolation.
- Do NOT generate docs without first auditing what already exists — creating duplicate content is worse than a gap.
- Do NOT write docs in the wrong Diátaxis quadrant. A reference page must not contain opinion. A tutorial must build something. A how-to must be goal-oriented. An explanation must not contain steps.
- Do NOT modify source code while generating docs. Documentation lives in markdown files.
- Do NOT delete or overwrite existing documentation without explicitly noting the deletion in the plan and confirming with the user.
- For `mode: workflow`: read the actual workflow artifacts (`02-shape.md`, `03-slice.md`, `08-handoff.md`) to understand what was built before writing anything.
- Follow the numbered steps exactly in order.

# Step 1 — Discover (orchestrator only)
Find all existing documentation in scope.

Launch one Explore sub-agent with the following:

**Documentation inventory:**
- Find all markdown files in the project: `README.md`, `docs/`, `CONTRIBUTING.md`, `CHANGELOG.md`, `wiki/`, API docs, embedded docstrings, and any other `.md` files
- For each file found: record the path, file size, last modified date (`git log -1 --format="%ai" -- <file>`), and a one-sentence description of what it covers
- Identify the documentation structure: is there a `docs/` folder? A wiki? API reference generation from code? A static site (Docusaurus, MkDocs, Jekyll, VitePress)?
- For `mode: workflow`: identify which docs were listed in the shape's `## Documentation Plan` — check which exist vs which are missing
- For `mode: path`: scope all searches to `<scope-path>`
- List any documentation generation tooling: `typedoc`, `sphinx`, `godoc`, `rustdoc`, `jsdoc`

Write `discover.md` with the full inventory.

**`discover.md` frontmatter:**
```yaml
---
schema: sdlc/v1
type: docs-discover
run-id: <run-id>
mode: <project|workflow|path>
target-slug: <slug or "n/a">
scope: <description>
doc-files-found: <count>
has-docs-folder: <true|false>
doc-generator: <tool or "none">
status: complete
created-at: <real timestamp via bash>
---
```

# Step 2 — Audit (orchestrator only)
For each documentation file found, audit it against the codebase and Diátaxis principles. Launch parallel Explore sub-agents — one per documentation area or one per large doc file.

**Each audit sub-agent is prompted with:**

For the assigned documentation file(s):

**Accuracy vs. codebase:**
- Read the doc. For every code example, API name, function signature, config key, CLI command, and endpoint mentioned — verify it still exists and has the same signature in the current codebase
- Check if the doc references files, modules, or paths that have moved or been deleted (`git log --all --follow -- <old-path>`)
- Note outdated version numbers, deprecated options, or removed features still documented

**Diátaxis quadrant check:**
- Classify the document: tutorial (learning-oriented, builds something), how-to (task-oriented, goal-driven steps), reference (information-oriented, neutral and scannable), explanation (understanding-oriented, discusses why)
- Does the document match its stated type? Common violations: a reference page that gives opinions, a tutorial that doesn't actually build something, an explanation that contains numbered steps, a how-to that explains why instead of showing how
- Is the document doing the job of TWO quadrants? If so, it should be split

**Completeness check:**
- Are there public APIs, config options, CLI flags, or user-facing behaviors that exist in the code but are NOT documented anywhere?
- For `mode: workflow`: compare the workflow's implementation artifacts against the existing docs — what did the feature add that's missing?

**Freshness:**
- When was this doc last meaningfully updated (`git log -5 --format="%ai %s" -- <file>`)? When was the related code last changed?
- Is the gap between doc age and code age more than 30 days?

Each sub-agent returns: file path, accuracy issues (list), quadrant violations (list), gaps (list), last-updated, freshness-risk (low/medium/high).

Write `audit.md` aggregating all sub-agent findings.

**`audit.md` frontmatter:**
```yaml
---
schema: sdlc/v1
type: docs-audit
run-id: <run-id>
files-audited: <count>
accuracy-issues: <count>
quadrant-violations: <count>
gaps-found: <count>
high-freshness-risk: <count>
status: complete
created-at: <real timestamp>
---
```

**`audit.md` body — one section per file:**
```
## <file-path>
- Type: <tutorial|how-to|reference|explanation|readme|unknown>
- Accuracy issues: <list or "none">
- Quadrant violations: <list or "n