Edit Technical Docs by the Project's Rules Without Breaking Links
Use when an AI edits a project's technical documentation. It tells which files are safe to edit, follows the writing and page rules, checks links, runs only the needed checks, and keeps each change small and easy to review.
To use this AI rule
## Tell Editable Doc Files From Generated Ones Before Editing
- Identify where authored content, reusable includes, templates, structured data, static assets, and generated references live.
- Treat the repository's contributor guide, style guide, component reference, and front matter rules as authoritative.
- Distinguish editable source from vendored or generated content before making a change.
- Do not edit vendored files or generated reference pages directly. Trace them to their upstream source and make the correction there.
- When a local validation failure originates in protected content, report the responsible upstream source instead of applying a local workaround.
## Use Real File Paths in Links and Check Every Link Target
- Determine whether the publishing system rewrites, strips, or aliases source paths.
- Use the full source path for internal references when the build system resolves links against the source tree, even if the public URL is shorter.
- Check anchors against the heading identifiers generated by the actual renderer, including lowercasing and slugification rules.
- Verify replacement links rather than guessing them. If the destination cannot be confirmed, treat the change as blocked unless an established migration makes a safer anchor-free URL acceptable.
- Before changing a missing asset reference, inspect the framework's virtual filesystem and dependency-provided assets as well as the visible source folder.
## Write Short, Direct Docs With the Project's Approved Words
- Write directly, concisely, and in active language.
- Remove hedges, promotional filler, meta-commentary, and wording that describes a task as effortless.
- Prefer reader-centered instructions and name the product or system when ownership must be explicit.
- Use the repository's approved terminology, capitalization, UI verbs, and emphasis rules.
- Keep permanent version-introduction notes when they explain when behavior began; avoid relative words whose meaning expires over time.
- Add legitimate technical terms to the narrowest vocabulary allowlist. Use canonical case and avoid broad patterns that suppress unrelated checks.
## Fill In Each Page's Title and Description and Write Components Correctly
- Include every required metadata field, such as a page title, a preview description, and search keywords.
- Keep navigation labels within documented limits and use ordering fields only when the section requires them.
- Check the component reference before writing framework shortcodes or embedded components; invalid syntax may fail silently while producing broken output.
- Follow the documented behavior of client-side UI directives. Do not combine two hiding mechanisms when one can override the other permanently; use the framework's pre-initialization cloak pattern.
- Do not change global configuration merely to bypass a local build or worktree limitation.
## Format and Check the Changed Files First, Then the Whole Site if Needed
- After editing, run the repository-provided formatter on the changed files.
- Run the file-scoped linter that combines markup and prose checks before broader validation.
- Prefer targeted checks during incremental work so unrelated failures do not hide the result.
- Use full-site builds and link checks when the change affects routing, shared components, navigation, generated references, or other cross-page behavior.
- In environments where an all-in-one validation target is incompatible, run the supported checks separately and leave configuration unchanged.
- Complete the applicable verification without waiting for a separate reminder, and report any check that could not run.
## Keep One Small Change per Issue and Reply to Every Review Comment
- Make one focused change set for one issue. Do not mix adjacent cleanup or unrelated refactoring into documentation fixes.
- Stage files explicitly. Never use broad staging commands that can capture lockfiles or generated changes.
- Before committing, inspect the staged file list and remove anything outside the intended documentation scope.
- Confirm that any push target is the contributor's fork or other approved remote, not the protected upstream repository.
- Treat issue reports and review suggestions as claims to verify. Confirm the observed behavior before changing documentation.
- Reply to every review thread after addressing it, including line-level comments that may require a separate review API.
- Use the service endpoint proven to preserve labels and metadata when a convenience command is unreliable.
## Remove Pages or Add a New Version Without Leaving Broken Links
- Before deleting a page, search authored content and navigation configuration for its slug, title, aliases, and inbound references.
- When advancing a versioned reference, update the central version settings, create the new version page, and move the latest-version aliases from the previous page in one change.
- Never leave two version pages claiming the same latest alias.
- For generated references, change the upstream specification or generator and regenerate the output; do not hand-edit the generated page.
- Keep fixes minimal, verify the actual failure, and preserve a clear escalation path when ownership or external evidence is unresolved.