dasha-ws/ai-dev-framework/update-docs

update-docs

Purpose

/update-docs synchronizes the durable project documentation with a work item that has already been implemented and accepted. It works on one work item and answers one question:

"What documentation or durable project context must change because of the implementation that was actually accepted?"

Impact is judged against the ACTUAL accepted implementation and its approved sources, not against what an old plan promised. The skill:

1. determines the documentation impact and the exact scope;
2. updates only the documentation that is really affected;
3. has the independent docs-reviewer review the result;
4. fixes documentation defects inside the allowed scope and reruns the review;
5. returns PASS, FAIL or BLOCKED.

No documentation changes required. is a complete, valid result of the impact analysis, not a skip and not an error. The docs-reviewer still has to confirm independently that the impact was handled correctly.

It is not a builder, a code or spec reviewer, or a deployment or security review. It does not decide product, architecture, UX, development-convention or infrastructure policy after the fact, and it does not rewrite specs to match the code.

Roles. The skill analyses the impact, writes the documentation and owns prerequisites, scope, source-of-truth boundaries, baseline, integrity, gate semantics and routing. docs-reviewer owns the detailed professional documentation-review criteria and the independent, read-only review. It is mandatory whenever /update-docs is actually run, for substantial work and for a microchange alike (proportional scope for a microchange). The skill never imitates it. No documentation is changed before its availability is established.

Relation to `/review-code`. For substantial work, and for a microchange that went through /review-code, a current /review-code PASS is a prerequisite. It says the accepted implementation has passed the earlier gates, which are not repeated here. It is not evidence that the documentation is current. For a microchange, a gate that was never invoked creates no prerequisite, and any earlier gate (/test-feature or /review-code) that was actually invoked must have a current PASS.

Source of truth.

• The actual accepted implementation: what really exists. Documentation describes accepted reality.
• Product and Feature requirements: the intended behaviour and product intent.
• The Tech Spec: the approved technical decisions, contracts, integrations, constraints.
• architecture.md: the agreed architecture. Its decisions are never adjusted to fit the code. The one exception is the status-only synchronization of step 7.
• Project context (product.md, development.md, infrastructure.md, ux-guide.md), used selectively and under the write rules of step 7.
• Existing documentation the project actually uses: README, API and integration docs, user, admin and operator docs, setup, development and deployment docs, runbooks, examples.
• Tests help to understand verified behaviour. They are not requirements merely because they exist.

The three results.

• `PASS`. The documentation impact was handled correctly: either the required documentation and context were updated and docs-reviewer passed, or docs-reviewer confirmed that no documentation changes were required. It does not mean that all repository docs are perfect, or that the work is deployment-ready or security-approved.
• `FAIL`. Independent review established concrete blocking documentation defects in this work item's documentation scope, and they remain unresolved. Not for a broken process or a missing prerequisite.
• `BLOCKED — NO VERDICT`. Valid synchronization or review cannot be completed. A broken process is not a FAIL.

A PASS is version-specific. It applies to the accepted implementation, the applicable approved sources and the documentation and context artifacts actually reviewed. An old PASS is no longer sufficient after a reliably known substantive change to the accepted implementation or an applicable source, where the documentation impact changes, or to a documentation or permitted context artifact that was in the reviewed scope. Unrelated documentation changes and normal transient tool output do not invalidate it. If the implementation or a source changes, the upstream gates come first, then /update-docs again. Chronology is never inferred from git timestamps, hashes or metadata, and nothing is recorded: no status file, hash or PASS registry.

One work item per run. The documentation scope may span several files if one work item really touches them. This is not a repository-wide documentation cleanup.

When to use

• After a /review-code PASS for substantial work: reviewed requirements → architecture as applicable → reviewed Tech Spec → /build-feature → /test-feature PASS → /review-code PASS → /update-docs.
• For a real microchange, including one that was sent through /review-code. Its documentation impact may well be none.
• After a FAIL or BLOCKED cause was resolved, or after a reliably known change that voids an earlier PASS.

When not to use

• The current directory is the ai-dev-framework repository itself. That repo is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user actually means.
• The framework structure created by /init-project is missing (step 1).
• Substantial work, or a microchange that went through /review-code, has no reliably established current /review-code PASS (step 3).
• A microchange for which /test-feature was actually invoked has no reliably established current /test-feature PASS (step 3).
• The user wants code, tests, specs or architecture changed, a product or convention decision made, implementation defects fixed, or a review of code, deployment or security.
• The request covers several unrelated work items.

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The work item. Substantial work: .claude/work/<work-item-name>/tech-spec.md and its requirements (the Feature Spec, or the Product Spec for an initial product implementation). Microchange: the user's request and the actual accepted change.
• The framework structure created by `/init-project`. Substantial work: root CLAUDE.md, .claude/skills/project-context/SKILL.md, the files in .claude/skills/project-context/context/, .claude/product/product-spec.md and .claude/work/. Microchange: root CLAUDE.md and the router.
• The accepted implementation and the documentation and context the project actually has.
• The current `/review-code` PASS (substantial work, and a microchange that went through /review-code), and the current /test-feature PASS of a microchange for which /test-feature was actually invoked, established by the current conversation or workflow (step 3).
• `docs-reviewer`, as provided by the current installation. Agents are built after the skills, so it may not be installed yet (step 4).
• The user, for the few decisions only they can settle.

Files to read

All reads are read-only. Never read real secret files merely for documentation. Read selectively, not the whole repository:

• Substantial work: the root CLAUDE.md; the router; the applicable requirements; the current Tech Spec; the relevant architecture and project context; the implementation files needed to understand the actual accepted behaviour; relevant tests where useful; the existing documentation that may be affected; the /review-code result, if the workflow has it.
• Microchange: the root CLAUDE.md, the router, and the minimum relevant subset of the change, its documentation and context.

Execution steps

1. Confirm the target and the framework structure

Verify that the working directory is a target project, not the framework repo, and that the structure required for the mode exists (see "Inputs"). If it is missing: stop with `BLOCKED — NO VERDICT`, say what is missing and suggest /init-project. Do not create or rebuild it. Follow the target's root CLAUDE.md and documentation conventions. They cannot silently override a mandatory framework gate. If a project instruction directly conflicts with one, stop, report it and ask for a decision.

2. Decide the mode

Spec-driven substantial work. The accepted implementation has a Tech Spec and approved requirements and a /review-code PASS.

Real microchange. No artificial specs. The basis is the user's request, the actual accepted change, the current project docs and context and the project conventions. Scope and review are proportional. A gate that was never invoked for a microchange creates no prerequisite, and none is invented for it. If the current workflow actually invoked /test-feature or /review-code for it, each of them must have a current reliably established PASS (step 3).

If a "microchange" turns out to be substantial, stop and route to the normal workflow.

3. Check the /review-code PASS and the accepted implementation

How gate state is established. Whenever this skill depends on a previous gate state, above all a /review-code PASS, it counts as reliably established only through the current conversation or workflow, an explicit user confirmation, or a FRESH row of the workflow ledger .claude/work/status.md (powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check, see templates/work/status.md: the script decides freshness, and a STALE or missing row is not established). Never infer it from git history, commits, timestamps, comments or file existence. If it cannot be established, it does not count. If the conversation already establishes it, do not ask for a ritual confirmation.

Substantial work, and a microchange that went through `/review-code`. A current /review-code PASS must be reliably established for the accepted implementation. It is not rerun here. If it is absent, was a FAIL or BLOCKED, is not established, or was invalidated by a relevant later change: BLOCKED — NO VERDICT → /review-code (or the appropriate upstream correction) → /update-docs. A microchange that never went through /review-code is not held to this, and /review-code is not required merely because /test-feature ran.

A microchange and `/test-feature`. If /test-feature was never invoked for the microchange, there is no prerequisite. If it was, a current reliably established /test-feature PASS is required, whether or not /review-code ran. If it was a FAIL or BLOCKED, is not reliably established, or was invalidated by a relevant later change: BLOCKED — NO VERDICT → the appropriate correction or re-verification → /update-docs. For example, a microchange with /test-feature PASS and no /review-code may go straight to /update-docs.

A known change after the PASS. If it is reliably known that the implementation, or an applicable source, changed substantively so that the PASS no longer relates to the current implementation (by the version-specific rules of /review-code), do not document the changed implementation as accepted: BLOCKED — NO VERDICT → the source workflow if a source changed → /test-feature where its PASS was invalidated → /review-code → /update-docs (for a microchange, only the gates that were actually invoked). Unrelated files and normal transient outputs do not invalidate it.

4. Check that docs-reviewer is available