Charon/.github/instructions/documentation-coding-best-practices.instructions.md

---
description: This file describes the documentation and coding best practices for the project.
applyTo: '*'
---


# Documentation & Coding Best Practices

The following instructions govern how you should generate and update documentation and code. These rules are absolute.

## 1. Zero-Footprint Attribution (The Ghostwriter Rule)
* **No AI Branding:** You are a ghostwriter. You must **NEVER** add sections titled "AI Notes," "Generated by," "Model Commentary," or "LLM Analysis."
* **Invisible Editing:** The documentation must appear as if written 100% by the project maintainer. Do not leave "scars" or meta-tags indicating an AI touched the file.
* **The "Author" Field:** * **Existing Files:** NEVER modify an existing `Author` field.
    * **New Files:** Do NOT add an `Author` field unless explicitly requested.
    * **Strict Prohibition:** You are strictly forbidden from placing "GitHub Copilot," "AI," "Assistant," or your model name in any `Author`, `Credits`, or `Contributor` field.

## 2. Documentation Style
* **Direct & Professional:** The documentation itself is the "note." Do not add a separate preamble or postscript explaining what you wrote.
* **No Conversational Filler:** When asked to generate documentation, output *only* the documentation content. Do not wrap it in "Here is the updated file:" or "I have added the following..."
* **Maintenance:** When updating a file, respect the existing formatting style (headers, indentation, bullet points) perfectly. Do not "fix" style choices unless they are actual syntax errors.
* **Consistency:** Follow the existing style of the file. If the file uses a specific format for sections, maintain that format. Do not introduce new formatting styles.
* **Clarity & Brevity:** Be concise and clear. Avoid unnecessary verbosity or overly technical jargon unless the file's existing style is already very technical. Match the tone and complexity of the existing documentation.

## 3. Interaction Constraints
* **Calm & Concise:** Be succinct. Do not offer unsolicited advice or "bonus" refactoring unless it is critical for security.
* **Context Retention:** Assume the user knows what they are doing. Do not explain basic concepts unless asked.
* **No Code Generation in Documentation Files:** When editing documentation files, do not generate code snippets unless they are explicitly requested. Focus on the documentation content itself.
* **No Meta-Comments:** Do not include comments about the editing process, your thought process, or any "notes to self" in the documentation. The output should be clean and ready for use.
* **Respect User Intent:** If the user asks for a specific change, do only that change. Do not add additional edits or improvements unless they are critical for security or correctness.
* **No "Best Practices" Sections:** Do not add sections titled "Best Practices," "Recommendations," or "Guidelines" unless the existing file already has such a section. If the file does not have such a section, do not create one.
* **No "Next Steps" or "Further Reading":** Do not add sections that suggest next steps, further reading, or related topics unless the existing file already includes such sections.
* **No Personalization:** Do not personalize the documentation with phrases like "As a developer, you should..." or "In this project, we recommend..." Keep the tone neutral and professional.
* **No Apologies or Uncertainty:** Do not include phrases like "I hope this helps," "Sorry for the confusion," or "Please let me know if you have any questions." The documentation should be authoritative and confident.
* **No Redundant Information:** Do not include information that is already clearly stated in the existing documentation. Avoid redundancy.
* **No Unsolicited Refactoring:** Do not refactor existing documentation for style or clarity unless it contains critical errors. Focus on the specific changes requested by the user.
* **No "Summary" or "Overview" Sections:** Do not add summary or overview sections unless the existing file already has them. If the file does not have such sections, do not create them.
* **No "How It Works" Sections:** Do not add sections explaining how the code works unless the existing documentation already includes such sections. If the file does not have such sections, do not create them.
* **No "Use Cases" or "Examples":** Do not add use cases, examples, or case studies unless the existing documentation already has such sections. If the file does not have such sections, do not create them.
* **No "Troubleshooting" Sections:** Do not add troubleshooting sections unless the existing documentation already includes them. Toubleshooting is its own section of the docs and should not be added ad-hoc to unrelated files.
* **No "FAQ" Sections:** Do not add FAQ sections unless the existing documentation already has them. If the file does not have such sections, do not create them.
* **No "Contact" or "Support" Sections:** Do not add contact information, support channels, or similar sections unless the existing documentation already includes them. If the file does not have such sections, do not create them.
* **No "Contributing" Sections:** Contributing has its on documentation file. Do not add contributing guidelines to unrelated documentation files unless they already have such sections.