documentation_standards.mouse

4. Standards & Quality Assurance: Documentation Standards (Mouse Protocol)

Rationale: Ensures that all work performed and systems developed/modified by the Agent are adequately, accurately, and clearly documented at multiple levels. High-quality documentation is essential for User understanding, future maintainability, collaboration, onboarding, and overall project success. The Agent treats documentation as an integral part of task completion.

4.3 Documentation Standards (Agent's Direct Responsibility)

• A. Task-Level Documentation (Implicit via Protocol Adherence & Explicit Summaries):
  • Implicit & Foundational: The primary, detailed documentation for the work undertaken is inherently captured by strict adherence to the Mouse Protocol:
    • The Task object (<TaskID>.md): Description, Deliverables, HistoryLog.
    • The PlanFile (<TaskID>_plan.md for M/L/X tasks): Detailed SubTask.Objective, SubTask.InitialKeySteps, SubTask.ProactiveAnalysis, granular SubTask.ExecutionLog, and structured SubTask.FinalOutputSummary (JSON).
  • The Agent MUST ensure all these protocol-defined artifacts are accurate, comprehensive, and reflect the work performed precisely.
  • Explicit Summaries (If Required): If a Task.Deliverable or SubTask.Deliverable explicitly calls for a specific summary document, report, or presentation (e.g., "Generate a Markdown summary of findings for TaskID"), the Agent must produce this as a distinct artifact, linking to more detailed logs where appropriate.
• B. Code-Level Documentation (Inline Comments & API Documentation - Mandatory):
  • B1. Inline Comments (Clarity for Complex Logic): Agent MUST generate clear, concise inline comments within the code to explain:
    • Complex or non-obvious algorithm sections.
    • Important design decisions or trade-offs made within a function/method.
    • Workarounds for known issues or external system quirks (e.g., // API X returns inconsistent nulls, handling defensively.).
    • TODO:, FIXME:, HACK: annotations with clear explanations and, if possible, a reference to a TaskID for follow-up.
  • B2. API/Function/Class Documentation (Docstrings - Non-Negotiable for Public/Reusable Code):
    • For ALL new or significantly modified public/exported functions, methods, classes, interfaces, and modules, the Agent MUST generate standard API documentation using the idiomatic style for the language (e.g., JSDoc/TSDoc, Python Docstrings with Sphinx/Google/NumPy style, JavaDoc, GoDoc, Doxygen, Swift Markup, KDoc).
    • This documentation MUST minimally include:
      1. A concise summary of the component's purpose and primary responsibility.
      2. Detailed description of each parameter: name, type, purpose, optional/required, default value if any.
      3. Detailed description of the return value: type, purpose, structure if complex.
      4. Any exceptions/errors explicitly thrown or specific error conditions the caller should be aware of.
      5. Usage examples where they significantly aid understanding (especially for complex APIs or utility functions).
      6. Notes on thread safety, immutability, or other non-functional characteristics if relevant.
  • Logging: The generation or significant update of code-level documentation MUST be logged in the relevant SubTask.ExecutionLog (e.g., "Generated Python docstrings for all public methods in data_processor.py.").
• C. Project-Level Documentation (User Guides, READMEs, Architectural Docs, Changelogs - As Required):
  • If a task introduces new user-facing features, public APIs, significant architectural changes, new operational procedures, or breaking changes, the Agent MUST create or update relevant Bdocumentation. This is mandatory IF:
    • Explicitly specified as a Deliverable in the Task or a SubTask.