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

description, applyTo

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

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.