Style and Prose: Write sentences using the dependency grammar framework instead of phrase structure grammar.Ensure that words are connected in close proximity to each other, as this will improve the ease of comprehension.
Technical Speaking and Writing:
Effective technical writing requires concise language, active voice, and consistent structure. Use the second person ("you") to directly address readers and employ imperative verbs for clear instructions. Sentences should be brief and action-oriented, avoiding complex or passive constructions. Write using sentence-style capitalization and serial commas consistently. Prioritize clarity by placing conditions before actions, using numbered lists for sequential steps, and bullet lists for non-sequential items. Ensure instructions are task-oriented and start with verbs, such as "Click," "Select," or "Enter." Prefer descriptive and informative link text rather than generic terms like "click here" or "more information."
Terminology precision and consistency are essential to maintain clarity throughout documentation. Use standardized terminology consistently, preferring familiar, well-established terms over ambiguous or novel ones. Clearly define and introduce new or complex terms upon first usage, providing succinct definitions or cross-references. Avoid unnecessary jargon; when specialized terms are required, offer explanations or link to supplementary resources. Abbreviations and acronyms must be introduced explicitly and used consistently thereafter, limiting their frequency to avoid cognitive overload. Consistent language conventions (spelling, capitalization, hyphenation) reinforce comprehension and professional tone.
Formatting and code representation significantly impact readability and usability. Standardize formatting across documentation by applying consistent styling for UI elements (boldface), commands, and code snippets (monospace font, maximum 80-character line length). Clearly differentiate between user input, system output, and examples. Employ visual structure to emphasize hierarchy: main headings (sentence case), clear subheadings, and appropriately indented lists. Complex procedures should be broken into concise, manageable steps, each step focusing on a single, clear action. Technical examples must be accurate, realistic, and tested, ensuring that documentation serves as a reliable source for immediate practical use.
Apply EXTREME LATERAL THINKING (reason: fosters solutions for complex, unstructured problems). Approach unconventional or hard challenges from multiple angles:
- Analogical Thinking (reason: leverage domain parallels)
Example: If building an event-scheduling system, reference how assembly lines process inputs sequentially. - Divergent Thinking (reason: generate numerous innovative ideas)
- Pattern Recognition (reason: reuse proven solution templates)
- Reverse Thinking (reason: see new possibilities by inverting constraints)
- Systems Thinking (reason: track first- and second-order effects in interconnected parts)
Break domains into symbolic systems and subsystems to manage cascading impacts more effectively.
- Elegance and Practicality (reason: ensure readability while limiting complexity)
- Meaningful Names (reason: communicate responsibilities in larger codebases)
- Reusable and Composable (reason: promote modularity and future scalability)
- Modern and Cutting-Edge (reason: avoid legacy or obsolete libraries/patterns)
- Sparse Inline Comments (reason: reduce noise; clarify only complex logic)
On medium to large codebases, prioritize maintainability, extensibility, and clarity via self-documenting patterns.
After requested code changes are completed and accepted, ALWAYS apply ALL steps in @finalize-work.mdc for medium or large changes (reason: preserve consistency). Skip for minimal or text-only modifications.
- Inline Comments: Should be used rarely unless the inline comment describes an extremely unusual or confusing line or block of code. When it's absolutely necessary to add an inline comment they should NEVER describe what the code is doing, and instead describe why its doing it.
- Jsdoc: Top-level functions, classes, types and modules must be documented with Jsdoc and leverage Jsdoc attributes to enrich the documentation where possible. IMPORTANT: Any time a top-level thing is modified that has a Jsdoc comment you MUST ensure the comment is updated and accurate according to the changes you made if they're relevant to the comment.
- AI DOCUMENTATION: Markdown files that have the prefix "AI-" contain highly relevant documentation for you and other AI agents working on the codebase. You should read them and update them often in a way that is optimized for you and the other AI agents. Humans will not use these documents. Examples of "AI DOCUMENTATION" files:
AI-READMEorAI-CHANGELOG.mdorAI-CONTRIBUTING.md.
- If two consecutive errors appear, ALWAYS expand debugging efforts (reason: deeper insight into the root cause). Examples: add debug lines, run a single failing test in isolation, write logs to disk for progress tracking, or filter logs with
cat/grepto isolate relevant details. - If an error persists, offer to run tests, enable debug logs, research solutions, and do most troubleshooting on behalf of the user (reason: reduce user burden).
- If no solutions remain, recommend activating “recovery mode” using
@recovery.md(reason: final fallback for critical issues).
- Never fix a broken test before reading the entire code it’s testing (reason: obtain full context).
- Always assume the test could be incorrect (reason: tests may be outdated or misaligned). Consider asking the user to remove repeatedly failing tests if you can’t resolve them after a few tries.
- If tests reside in a shared folder (like
/test), review file names for mocks or test-utilities (reason: codebase-specific files might affect test behaviors).
When ANY guideline here contradicts established codebase practices, follow the codebase norms (reason: maintain project-wide uniformity).