Tarsk Plugins

Included skill

Doc Review

Reviews the docs folder against the current implementation, updates documentation only when the mismatch is certain, identifies missing documentation across the codebase, and asks the user whether to add docs for each missing topic. Use only when the user asks for documentation review, documentation audit, stale docs detection, missing docs discovery, or documentation updates.

Source: /skills/doc-review/SKILL.md

Doc Review

Use this skill only when the user asks for it.

Goal

Audit existing documentation against the current codebase.

You have two jobs:

  1. Find documentation in docs/ that no longer matches the implementation.
  2. Find important parts of the codebase that have no documentation and ask the user whether they want documentation added for each one.

Required Workflow

1. Inventory the docs

  • Read the docs/ tree first.
  • Group documents by topic, feature, subsystem, setup flow, API surface, and user workflow.
  • Note each document's claims, instructions, commands, screenshots, configuration names, file paths, and behavior descriptions.

2. Compare docs against implementation

For each doc or section:

  • Trace the documented behavior to the current implementation.
  • Verify commands against current scripts and tooling.
  • Verify config names, flags, env vars, routes, UI labels, component names, APIs, and workflows against the code.
  • Treat README files and docs outside docs/ as supporting evidence when useful, but prioritize the user's request to review docs/.

3. Decide whether the documentation is truly wrong

Only update documentation when you are sure it is incorrect.

Use this decision rule:

  • Update the doc if the implementation clearly contradicts it.
  • Do not change the doc if the code is ambiguous, incomplete, dead, experimental, or split across multiple paths and you cannot prove the intended behavior.
  • If uncertain, tell the user what looks stale and why you stopped short of editing.

4. Patch outdated docs conservatively

When you are certain a document is wrong:

  • Make the smallest accurate edit that fixes the mismatch.
  • Preserve structure unless a rewrite is necessary for correctness.
  • Do not invent behavior that the code does not prove.
  • Do not silently expand scope.

5. Find missing documentation

Review the codebase for features, flows, commands, settings, integration points, developer workflows, or architectural areas that likely need docs but do not appear in docs/.

For each missing item:

  • Name the topic clearly.
  • Cite the code or files that suggest the topic exists.
  • Explain in one or two sentences what the missing documentation should cover.
  • Ask the user whether they want you to add documentation for that specific item.

Do not add missing documentation until the user agrees for that item or gives a broad approval.

6. Apply stop-slop to any written documentation

For every documentation change you write:

  1. Read .agents/skills/stop-slop/SKILL.md
  2. Read the references in .agents/skills/stop-slop/references/
  3. Revise the changed text against the stop-slop rules
  4. Remove filler, passive voice, formulaic contrast, em dashes, and vague claims
  5. Deliver direct documentation written for humans doing the work

If you write docs, the stop-slop pass is required.

Output Requirements

When reporting results, separate them into these sections:

  • Updated docs
  • Potentially outdated but not changed
  • Missing documentation to consider
  • Questions for the user

For each updated doc:

  • Name the file
  • State what was wrong
  • State what evidence in the code proved the correction

For each uncertain doc:

  • Name the file
  • State what looks stale
  • State why the evidence was not strong enough to edit

For each missing documentation item:

  • Give the topic title
  • Point to the relevant code
  • Use ask_user to ask the user whether the user wants documentation added

Standards

  • Prefer direct evidence from code over comments.
  • Prefer current scripts, types, tests, routes, and UI text over old docs.
  • Do not claim a feature exists unless the code proves it.
  • Do not remove documentation just because you did not find the implementation quickly.
  • When several features are missing docs, ask about each one separately so the user can approve them one by one.

Suggested Review Heuristics

Look for drift in:

  • setup and install steps
  • CLI commands and flags
  • package names
  • environment variables
  • feature availability
  • UI labels and navigation
  • config file names and shapes
  • API request and response examples
  • authentication flows
  • desktop versus web behavior
  • screenshots or references to removed surfaces

Completion Checklist

  • docs/ reviewed
  • existing docs compared against implementation
  • only certain mismatches edited
  • uncertain mismatches reported without editing
  • missing documentation topics identified
  • user asked about each missing topic
  • stop-slop applied to all written documentation