# Documentation Writing

> Creates and maintains project documentation in .claude/skills/project-knowledge/: interview, initial Project Knowledge, audit, edit, consistency, and feature finalization. Use when: "заполни документацию проекта", "опиши проект", "создай Project Knowledge", "проведи интервью по проекту", "проверь документацию", "обнови документацию", "аудит документации", "plan a new project", "fill project documentation", "check docs", "audit documentation", "update docs" For reading docs or explaining concepts, read project-knowledge skill directly.

- Skill: `pavel-molyanov/documentation-writing-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add pavel-molyanov/documentation-writing-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pavel-molyanov/documentation-writing-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: pavel-molyanov (https://skillmd.com/u/pavel-molyanov)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pavel-molyanov/documentation-writing-2

---

<!-- Generated by sync-to-codex v1. Do not edit directly. -->

# Documentation Management

Create and maintain `.claude/skills/project-knowledge/` from the evidence source the user named.

Outside Feature Finalization Mode, follow
[create-project-knowledge.md](references/create-project-knowledge.md) when the user starts or
continues initial documentation and either its interview is still in progress or Project Knowledge
is missing, still a template, or only partially filled. Apply
[project-knowledge-structures.md](references/project-knowledge-structures.md) for content ownership
and structure. After writing, run the manual sync and continue at Documentation Review.

When the user explicitly asks to reorganize existing Project Knowledge, apply
[project-knowledge-structures.md](references/project-knowledge-structures.md). Ordinary updates
preserve the filled structure already in use.

## Manual Project Documentation Sync

Project documentation source of truth is Claude-side: `CLAUDE.md` and `.claude/**`.
Codex-side `AGENTS.md` and `.codex/**` are generated runtime files.
No scheduled job performs this conversion. The agent that changes the Claude source runs the
matching command immediately and reviews the generated result before finishing the task.

After changing a project `CLAUDE.md` or any project-local `.claude/**` file, immediately run:

```bash
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply
```

If sync reports a conflict, stop and report it. Commit generated project `.codex/**` / `AGENTS.md`
changes with their Claude sources, except `.codex/.sync/**`, which is host-local runtime state.
When an approved deletion or rename produces `orphaned managed` outputs, verify that every reported
path corresponds to that approved source change, then remove those generated leftovers with:

```bash
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply --prune --confirm-delete
```

If the orphan list contains anything else, stop and report it instead of pruning unrelated output.

### Nested Agent Workspaces

Some projects keep an agent workspace under a subdirectory (for example
`nested-workspace/.claude/**`) while the repository root exposes selected skills or
agents through symlinks in root `.claude/**`. In that case, sync both levels:

```bash
~/.claude/scripts/sync-to-codex.sh --project "$PWD/nested-workspace" --apply
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply
```

Verify root `.codex/agents` / `.codex/skills` include every root-exposed agent or skill. A
generated file existing only inside the nested workspace is not enough when the root runtime
must invoke it. Treat `.codex/.sync/**` as host-local evidence: do not commit or synchronize it.

## Documentation Principles

The reader should understand the project's purpose, structure, decisions, and operation without
reconstructing them from code. Record durable project-specific facts: purpose and business logic;
architecture, components, and their relationships; lasting agreements, decisions, and why those
decisions were made; security rules and configuration names; deployment, operations, monitoring,
recovery, where key code lives, and operational details an agent cannot infer from configuration
alone.

Do not list functions, classes, local control flow, or implementation details that can be read from
code. Treat an important non-obvious rule that applies only to a particular code path as code-owned:
keep it out of Project Knowledge, and change a nearby code comment only when the user also requested
source changes.

Keep generic framework, Git, Linux, SSH, Docker, `journalctl`, and `systemctl` explanations out of
Project Knowledge. For operations, preserve facts such as host, user, non-default port, SSH alias,
service or container name, log location, monitoring URL, environment-variable names, and emergency
recovery behavior. Store an exact command only when the procedure is non-standard and cannot be
recovered from project configuration.

Use source links instead of code snippets or pseudocode. Each fact has one owner file; update the
existing section and cross-reference it elsewhere instead of appending a duplicate. `patterns.md`
contains project-specific conventions, not general implementation advice.

Plans, user specs, tech specs, handoffs, and other `work/` artifacts are evidence, not owners of
current project state. Keep changing inventories in their authoritative registry, configuration,
or runtime source; Project Knowledge records the durable rule, not current counts or members. If a
Project Knowledge claim depends on a completed work artifact, correct that boundary instead of
expanding the artifact.

File size alone is not a finding. Report a size-related issue only when evidence demonstrates
duplication, stale content, implementation-level detail, or a structure that prevents useful
selective loading.

## Phase 1: Select the Evidence Source

Use the narrowest mode that matches the user's request:

1. **One current change:** inspect the changed lines, the files they affect, and related callers or
   contracts needed to understand the durable result.
2. **Named commit or range:** inspect exactly that commit or range plus the related files needed to
   interpret it.
3. **Recent history:** when the user asks for the last N commits, inspect those N commits and their
   resulting current code.
4. **Full update or audit:** inspect current code, all Project Knowledge, and `CLAUDE.md`.
5. **Specific documentation edit, consistency check, or status:** inspect the named section and the
   documentation it can contradict.
6. **Feature finalization:** use this mode only when the user explicitly asks to finish a feature
   (including `/done`) and provides or identifies `work/{feature}/`.

Do not search for `user-spec.md` or require it outside feature-finalization mode. A normal
"update documentation" request does not archive work or create a finalization commit.

## Phase 2: Establish Durable Facts

1. Read the selected evidence and current target documentation before editing.
2. Trace names, versions, service boundaries, data model, environment variables, deployment
   triggers, and operational facts to current sources. For full audits, also check placeholders,
   duplication, stale links, generic tutorial content, inconsistent terminology, and facts that no
   longer match the code.
3. If Project Knowledge has no writable owner in the selected non-creation mode, report that no
   documentation target exists. Feature finalization keeps its explicit missing-documentation
   behavior below rather than starting an initial project interview from feature evidence.

## Phase 3: Update or Report

1. For an edit/update request, integrate facts into existing sections and update any directly
   contradicting references.
2. For an audit, consistency check, or status request, report evidence-backed issues without
   changing files unless the user also asked for fixes. Status classifications are filled, partial,
   template, or missing; size alone does not determine status.
3. After changing a project `CLAUDE.md` or project-local `.claude/**`, run the manual sync described
   above. For a nested workspace, sync the nested source first and the repository root second.

## Documentation Review

1. Run no more than two review waves. After documentation edits, run wave 1 with a fresh
   `documentation-reviewer` with no model override. Give it the complete touched documents, the
   selected evidence boundary, related code and contracts, and the user's request. It returns its
   JSON result directly. Include reviewers required by other active skills in these same waves
   instead of starting a separate wave sequence.
2. Review findings are diagnoses, not a work queue. Check the evidence and exact correction; apply
   only an authorized local correction to agreed normal documentation. If the scenario is rare or
   unagreed, or the correction adds behavior, state, entities, contracts, dependencies,
   architecture, or material complexity, reject it with a short reason or ask the user before
   editing. `user_decision_required: false` does not replace this check. Surface unrelated
   pre-existing defects without changing them.
3. If an accepted correction changes the reviewed documentation, run wave 2 with a fresh reviewer.
   Stop after a clean wave or when no authorized correction changes the documentation.
4. After wave 2, do not launch another reviewer automatically. Make only remaining local corrections
   inside the requested documentation change, run the applicable direct checks and manual sync, and
   show the user any remaining findings or required decisions.

## Feature Finalization Mode

1. Read `user-spec.md`, `decisions.md` when present, the implementation, and the relevant Git
   history. Compare the implemented result with the agreed spec.
2. If the feature is evidently incomplete, explain the concrete gap and ask whether to continue
   finalization.
3. Update only affected Project Knowledge through Phases 2-3 and Documentation Review. If Project
   Knowledge is missing, report that the documentation update was skipped and continue archival
   and finalization.
4. Remove active Project Knowledge and backlog links that treat `work/{feature}/` as a current
   source; do not add current operational inventory to completed artifacts.
5. Move `work/{feature}/` to `work/completed/{feature}/` after documentation review.
6. Commit the Project Knowledge changes and archive move with a concise documentation commit, then
   report the updated files and completed-feature path.

This is the only mode that reads feature artifacts by default, archives a feature, or creates the
finalization commit.

## Agent Entry Point

Keep `CLAUDE.md` minimal: project name, one-line description, reference to the Project Knowledge
skill, backlog path, and default branch. Detailed project information belongs in Project Knowledge.
Template: `~/.claude/skills/project-initialization/assets/new-project/CLAUDE.md`.

## Self-Verification

- [ ] The requested documentation outcome matches the selected evidence and remains within scope.
- [ ] No unresolved material deviation or contradiction is hidden from the user.