--- title: Documentation, References, and Model Agent Use version: 1.1 alwaysApply: true scope: code, project-plans --- # Directive on Documentation, References, and Model Agent Use in Code and Project Plans To ensure clarity, efficiency, and high-value documentation within code and project plans—and to leverage **model agents** (AI- or automation-based assistants) effectively—contributors must follow these rules: --- ## 1. Documentation and References Must Add Clear Value - Only include documentation, comments, or reference links when they provide _new, meaningful information_ that assists understanding or decision-making. - Avoid duplicating content already obvious in the codebase, version history, or linked project documents. --- ## 2. Eliminate Redundant or Noisy References - Remove references that serve no purpose beyond filling space. - Model agents may automatically flag and suggest removal of trivial references (e.g., links to unchanged boilerplate or self-evident context). --- ## 3. Explicit Role of Model Agents Model agents are **active participants** in documentation quality control. Their tasks include: - **Relevance Evaluation**: Automatically analyze references for their substantive contribution before inclusion. - **Redundancy Detection**: Flag duplicate or trivial references across commits, files, or tasks. - **Context Linking**: Suggest appropriate higher-level docs (designs, ADRs, meeting notes) when a code change touches multi-stage or cross-team items. - **Placement Optimization**: Recommend centralization of references (e.g., in plan overviews, ADRs, or merge commit messages) rather than scattered low-value inline references. - **Consistency Monitoring**: Ensure references align with team standards (e.g., ADR template, architecture repo, or external policy documents). Contributors must treat agent recommendations as **first-pass reviews** but remain accountable for final human judgment. --- ## 4. Contextual References for Complex Items - Use **centralized references** for multi-stage features (e.g., architectural docs, research threads). - Keep inline code comments light; push broader context into centralized documents. - Model agents may auto-summarize complex chains of discussion and attach them as a single reference point. --- ## 5. Centralization of Broader Context - Store overarching context (design docs, proposals, workflows) in accessible, well-indexed places. - Model agents should assist by **generating reference maps** that track where docs are cited across the codebase. --- ## 6. Focused Documentation - Documentation should explain **why** and **how** decisions are made, not just what was changed. - Model agents can auto-generate first-pass explanations from commit metadata, diffs, and linked issues—but humans must refine them for accuracy and intent. --- ## 7. Review and Accountability - Reviewers and team leads must reject submissions containing unnecessary or low-quality documentation. - Model agent outputs are aids, not replacements—contributors remain responsible for **final clarity and relevance**. --- ## 8. Continuous Improvement and Agent Feedback Loops - Encourage iterative development of model agents so their evaluations become more precise over time. - Contributions should include **feedback on agent suggestions** (e.g., accepted, rejected, or corrected) to train better future outputs. - Agents should log patterns of “rejected” suggestions for refinement. --- ## 9. Workflow Overview (Mermaid Diagram) ```mermaid flowchart TD A[Contributor] -->|Writes Code & Draft Docs| B[Model Agent] B -->|Evaluates References| C{Relevant?} C -->|Yes| D[Suggest Placement & Context Links] C -->|No| E[Flag Redundancy / Noise] D --> F[Contributor Refines Docs] E --> F F --> G[Reviewer] G -->|Approves / Requests Revisions| H[Final Documentation] G -->|Feedback on Agent Suggestions| B ``` --- ✅ **Outcome:** By integrating disciplined contributor standards with **model agent augmentation**, the team achieves documentation that is consistently _relevant, concise, centralized, and decision-focused_. AI ensures coverage and noise reduction, while humans ensure precision and judgment.