# Document

> Document is an Agent Skill for business published in the strapi/documentation repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

End-to-end documentation orchestrator: chains all four inki phases (research, write, review, submit) for a single subject. Gates between each phase by default; --non-interactive chains without pauses and runs a review-fix loop. The simplest way to document a subject from scratch.

- Skill name: `document`
- Category: [Business](https://www.openparable.com/skill/business/1)
- Source: https://github.com/strapi/documentation/blob/HEAD/claude-plugins/inki/skills/document/SKILL.md
- Repository: strapi/documentation (1,282 GitHub stars when collected)

## SKILL.md

# /inki:document: document a subject end to end

`/inki:document` is the one-shot entry point to the whole inki workflow. Given a subject to document, it runs the four families in order (**research → write → review → submit**), pausing for your approval between each phase so you stay in control. Pass `--non-interactive` (or `--no-questions-asked`, same effect) to chain all four without stopping; in that mode the review phase also runs a fix loop (review → fix → re-review) until the draft is clean or `--max-review-fix-rounds` is reached (defaults to 3).

It is a thin orchestrator: each phase is delegated to its existing top-level skill (`/inki:research`, `/inki:write`, `/inki:review`, `/inki:submit`). This skill adds no review logic of its own; it resolves the subject, sequences the phases, and manages the gates. The review fix loop is owned by `/inki:review`; this skill just invokes it with `--fix` and a round cap.

## Step 0: Parse arguments

If `$ARGUMENTS` contains `--help` or `-h`, print usage and stop, per `../../references/help.md`. Do not run the workflow.

Otherwise, from `$ARGUMENTS`, detect these flags anywhere in the list, then remove them:

- `--non-interactive` (canonical), aliases `--auto-approve`, `--auto`, `--yes`, `-y`, `--no-questions-asked` (all equivalent) → set `AUTO=true`. Chains all phases without pausing AND approves the review-fix loop in Step 4 (see below).
- `--max-review-fix-rounds <N>` (canonical), alias `--fix-rounds <N>` (both equivalent) → set `MAX_FIX_ROUNDS=<N>`. Caps how many review→fix→re-review iterations the review phase (Step 4) runs; this skill passes the value through to `/inki:review`. Defaults to `3` if not given.
- `--no-log`, `--log-dir <path>`, `--short-log` → logging flags, handled per `../../references/logging.md`.

What remains is the **subject**. If no subject remains, ask the user what they want to document and stop.

## Step 0b: Set up logging

Unless `--no-log` was passed, set up the run log by following `../../references/logging.md`: resolve the base directory, create the run directory `YYYY-MM-DD-<slug>` from `SUBJECT_LABEL` (resolved in Step 1), and write each phase's report into its subdirectory as that phase completes. If `--no-log` was passed, state once that nothing will be persisted. Logging is best-effort and never aborts the run.

## Step 1: Resolve the subject to a brief

Resolve the subject by following `../../references/subject-resolver.md`. It accepts keywords, a Strapi PR (URL, `owner/repo number`, a bare number, or prose naming a PR and repo), a Notion page URL, a Linear issue, a PDF (path or URL), a local text/markdown file, or pasted content.

The resolver returns:

- `BRIEF`: a normalized brief (title + summary + key facts/links) for the research and write phases.
- `SUBJECT_LABEL`: a short label for headers.
- `SOURCE_KIND`: the detected source type.
- `CLEANUP`: a command to run when the workflow finishes (temp-file removal); may be empty.

The resolver may stop the workflow before returning a brief, in which case relay its message and end:

- A bare PR number with no repo: the resolver asks which repo the PR belongs to. Stop until the user answers, then re-run.
- A `strapi/documentation` PR: that is a documentation PR, not a subject to document. The resolver tells the user to run `/inki:review <PR>` instead. Stop; do not continue into research.
- A PR on a repo that is not documented on docs.strapi.io (only `strapi/strapi` and `strapi/cloud` are): the resolver reports there is nothing to document. Stop.

If resolution otherwise fails (e.g. a Notion/Linear MCP is unavailable and no fallback content is provided), report why and stop.

## Step 2: Phase 1, Research

Invoke `/inki:research` on the subject (pass the brief's topic/keywords, or the original subject for PR/feature inputs).

**Gate on the result before continuing:**

- **If research concludes the subject is already documented** (an existing page covers it): **STOP.** Report the existing page path(s) from the research output and end the workflow. Do not chain into write. The user decides what to do next (they can run `/inki:review <path>` themselves to update the existing page). This stop happens even in `--non-interactive` mode: documenting a duplicate is never the intended outcome.
- **Otherwise:** the research output enriches the brief (gaps, related pages, routing). Carry the enriched brief forward.

**Phase gate (skipped when `AUTO=true`):** show the research summary and ask whether to proceed to writing. On no, stop.

## Step 3: Phase 2, Write

Invoke `/inki:write` with the enriched brief. In interactive mode `/inki:write` already gates on outline approval before drafting; let it. In `AUTO=true` mode, pass `--non-interactive` through so outline and draft are produced without an inner pause.

The output is a drafted page (and its outline file).

**Phase gate (skipped when `AUTO=true`):** show the draft path and ask whether to proceed to review. On no, stop (the draft is kept on disk for the user).

## Step 4: Phase 3, Review (with a fix loop)

This phase reviews the fresh draft and iteratively fixes it until it is clean or a round cap is hit. Because the draft was just generated by this same workflow (not pre-existing content a human is protecting), `/inki:document` is allowed to apply fixes here: that is the point of an end-to-end run.

The fix loop itself lives in `/inki:review` (the review→fix→re-review iteration and its `--max-review-fix-rounds` cap are review's own behavior). `/inki:document` does NOT re-implement it; it delegates by invoking `/inki:review` with the right flags and passing the round cap through.

`MAX_FIX_ROUNDS` here defaults to `3` (override with `--max-review-fix-rounds <N>`, alias `--fix-rounds <N>`). `/inki:document` passes this value to `/inki:review` as its cap.

**Behaviour depends on `AUTO`:**

- **`AUTO=true` (`--non-interactive`):** invoke

  ```
  /inki:review --non-interactive --fix --max-review-fix-rounds <MAX_FIX_ROUNDS> <draft>
  ```

  `/inki:review` runs the loop (apply every actionable fix → re-review → repeat up to the cap) without prompting. `--non-interactive` is what suppresses review's per-round confirmation: that is safe here because the draft was generated within this same run, not human-authored.

- **`AUTO=false` (default):** first invoke a single read-only `/inki:review <draft>` (no `--fix`) and show the report. Then ask whether to (a) run the fix loop, (b) proceed to submit as-is, or (c) stop. On (a), invoke `/inki:review --fix --max-review-fix-rounds <MAX_FIX_ROUNDS> <draft>` (without `--non-interactive`, so review shows each round's diff and confirms before writing).

Read the `ROUNDS_RUN` and final open-findings count back from `/inki:review`'s report for the summary. If the cap was reached with findings still open, do NOT loop further here: `/inki:review` already stopped at the cap and reported the remainder. Carry those into the summary and (in interactive mode) tell the user; they decide whether to submit anyway or iterate manually.

**Phase gate (skipped when `AUTO=true`):** after the loop, show the final review state and ask whether to proceed to submit. On no, stop (the draft and the review report are kept).

## Step 5: Phase 4, Submit

Invoke `/inki:submit` to branch (if on `main`), commit, push, and open the PR. In `AUTO=true` mode, pass `--non-interactive` through.

`/inki:submit` retains its own safety behavior, which `--non-interactive` does NOT override. Concretely, even in auto mode:

- **Deployment-infrastructure paths are never touched in auto mode.** `.github/workflows/` and `docusaurus.config.js` always require explicit human confirmation; `/inki:document` never writes them and never auto-approves a commit that includes them. (`sidebars.js` is NOT in this set: adding a new page legitimately requires a navigation entry, so `--non-interactive` may edit it. It stays visible in the diff and in the draft PR for human review.)
- **Branch discipline holds.** Commits land on a properly prefixed feature branch (`cms/`, `cloud/`, `repo/`), never directly on `main` or `next`.
- **git-rules.md governs the PR.** The commit message and PR title/description follow `git-rules.md` (imperative title, flat "This PR…" description, no headings, no test plan).
- **The PR opens as a draft** for human review; auto mode does not merge it.

If the original subject was a Linear issue, mention the issue ID in the PR body via the brief, but do NOT write `Fixes <ID>`: Linear issues are not GitHub issues and that syntax would not close anything.

## Step 6: Cleanup

Run the `CLEANUP` command returned by the subject resolver, even if the workflow stopped early at a gate. If `CLEANUP` is empty, there is nothing to do.

## Step 7: Summary

End with a one-block summary:

```
Documented: <SUBJECT_LABEL>
- Research:  <already-documented at <path> | gaps found, proceeded>
- Write:     <draft path>
- Review:    <ROUNDS_RUN round(s); N issues fixed, M still open by severity>
- Submit:    <branch> · <commit SHA> · <PR URL>
- Log:       <run directory path, or "disabled (--no-log)">
```

If the fix loop hit `MAX_FIX_ROUNDS` with findings still open, say so explicitly here.

In a workflow stopped at a gate, show the summary up to the phase reached and state where it stopped.

## Rules

- This skill never duplicates phase logic. It only resolves the subject, sequences phases, gates, and summarizes. The review fix loop is **not** implemented here: it belongs to `/inki:review` (Step 4 just invokes review with `--fix` and the round cap, and reads back the result). Each phase is run by **invoking its top-level skill** (`/inki:research`, `/inki:write`, `/inki:review`, `/inki:submit`), never by re-implementing that phase's steps inline. In particular, the submit phase MUST go through `/inki:submit` (which itself invokes `/inki:branch` / `/inki:commit` / `/inki:push` / `/inki:pr`); do NOT branch, commit, push, or open the PR with raw `git` / `gh` commands here, as that drops behavior the sub-skills own (e.g. the `/inki:pr` Vercel preview link). Read-only git/gh inspection is fine; mutating git/gh by hand in place of a phase skill is a defect.
- Default is **gated**: pause between every phase (research→write, write→review, review→submit). `--non-interactive` (canonical), aliases `--auto-approve`, `--auto`, `--yes`, `-y`, `--no-questions-asked` (all equivalent) removes the pauses but never the "already documented → stop" guard, the protected-path guard, or the branch discipline.
- `--non-interactive` approves the review fix loop too: it makes `/inki:document` pass `--non-interactive` to `/inki:review`, so review applies fixes without confirming each round. This is safe here only because the draft was generated within this same run. A bare `/inki:review --fix` on existing human-authored content still shows each round's diff and confirms first (review's human-content guard); `--fix` is always required for review to write anything at all.
- The fix loop runs at most `MAX_FIX_ROUNDS` times (default 3 here, `--max-review-fix-rounds <N>` / `--fix-rounds <N>` to change). The loop itself is enforced by `/inki:review`, which never loops unbounded; remaining findings are reported, not forced.
- If any phase fails, stop. Do not skip a phase.
- The submit phase's safety guards are not optional and `--non-interactive` does not lift them: protected paths stay untouched, commits stay on a prefixed feature branch (never `main`/`next`), the PR follows `git-rules.md` and opens as a draft. See Step 5 for the explicit list.

## Examples

Document a topic from keywords, gating between each phase:
```
/inki:document "MCP server configuration"
```

Document from a Notion spec, fully automatic up to the draft PR (review-fix loop runs up to 3 rounds):
```
/inki:document --non-interactive https://www.notion.so/strapi/Realtime-API-spec-abc123
```

Fully automatic, allowing up to 5 review-fix rounds for a tricky page:
```
/inki:document --non-interactive --max-review-fix-rounds 5 "Document Service API filters"
```

Document from a Linear issue:
```
/inki:document DOC-412
```

Document a code PR from strapi/strapi (CMS) or strapi/cloud (Cloud), any of these forms work:
```
/inki:document https://github.com/strapi/strapi/pull/26597
/inki:document strapi/cloud 1234
/inki:document PR 26597 from strapi/strapi
```

A bare PR number prompts for the repo first:
```
/inki:document 26597
```

A strapi/documentation PR is redirected to review (it is not a subject to document):
```
/inki:document https://github.com/strapi/documentation/pull/3234
→ "That is a documentation PR. Run /inki:review https://github.com/strapi/documentation/pull/3234 instead."
```

A PR on a repo not published to docs.strapi.io (e.g. strapi/design-system) stops with an explanation:
```
/inki:document https://github.com/strapi/design-system/pull/500
→ "strapi/design-system is not documented on docs.strapi.io (only strapi/strapi and strapi/cloud are), so there is no doc to write from this PR."
```

Document from a PDF RFC:
```
/inki:document ./specs/webhooks-rfc.pdf
```

Document from pasted notes (paste after the command):
```
/inki:document We need to document the new `transfer` CLI command:
it moves data between two Strapi instances over a token-authenticated
HTTP channel. Flags: --from, --to, --force...
```

---

Source: https://www.openparable.com/skill/business/document (OpenParable). Cite the canonical URL above.
