gener8v/gener8v.claude-skills.engineering

Documentation sync

Code and its documents change together, in the same commit. A document that is wrong is worse than no document.

Three ways documents go wrong

• Stale. The document still describes the old behavior, name or command.
• Missing. New behavior, a new command or a new setting has no documentation.
• Duplicated. The same fact is in two places. Later, one copy changes and the other does not.

Steps

1. See what changed.

   git diff --cached --stat
   git diff --stat
   

2. Find the repository's own rules. Read CLAUDE.md, CONTRIBUTING.md and docs/README.md. If they say which document owns which subject, follow them. They come before step 3.
3. Route each change to its owner. Use resources/doc-routing.md. One fact has one home. Other documents link to it.
4. Find stale references. For each name that you renamed or removed (a function, flag, endpoint, setting, file path, command):

   git grep -n '<old name>'
   

   Fix each hit in a document. Run the grep again. The post-condition is: no hits, or only hits that must stay (for example a CHANGELOG entry about the rename).
5. Edit. Change only what the code change makes wrong or incomplete. Do not rewrite unrelated sections. For clear wording, use the simple-english skill if it is installed.
6. Commit together. Stage the document changes with the code. Do not put them in a later PR.
7. Report. List the documents that you changed. If none needed a change, say so in one line and give the reason. For example: "No docs: internal refactor, no change to behavior, commands or settings."

When the owner is not clear

Ask the user. Do not create a new document to avoid the question.

A useful test: is it a fact about the current state (a setting, a version, a status)? It goes in the reference or status document. Is it a procedure (steps someone follows)? It goes in the guide, runbook or skill that owns that procedure.

Specifications come first

If the repository has a SPEC.md (see engineering:spec-writing) or gener8v specifications under .gener8v/specifications/, they define the intended behavior.

• If your change does what the specification says, the specification needs no edit.
• If your change contradicts the specification, stop. Tell the user. Change the specification first, through its owner: engineering:spec-writing for SPEC.md, gener8v:specification for pipeline specifications. Do not edit the specification silently to match the code.

Pipeline documents

Do not edit files under .gener8v/ by hand. The gener8v pipeline skills write and update them.

Related skills

• engineering:documentation-bootstrap: when a whole document is missing, not just a paragraph.
• engineering:github-pr-merge: runs this check before a PR.
• engineering:github-release: reads the CHANGELOG Unreleased section that this skill keeps current.